Cumulus Wiki

Php webtags: Difference between revisions

Php webtags (view source)

Revision as of 18:30, 26 June 2020

No change in size ,  18:30, 26 June 2020
m
sequence change
m (sequence change)
Line 26: Line 26:
*#When someone wants to view your customised web pages, the web server simply copies into the web page the latest script variables and generates HTML that has up to date values.
*#When someone wants to view your customised web pages, the web server simply copies into the web page the latest script variables and generates HTML that has up to date values.
*#You can even use Ajax (a JavaScript that runs in Client's browser) to update that HTML with new values at regular intervals (when a new script variable files has been uploaded).
*#You can even use Ajax (a JavaScript that runs in Client's browser) to update that HTML with new values at regular intervals (when a new script variable files has been uploaded).
= The different Main Approaches to data transfer =
The main focus of this article is assigning to PHP variables, but similar arguments apply for XML or JSON approaches so let us briefly review all the different approaches.
== Option 1: eXtensible Markup Language alternative ==
Extensible Markup Language (XML) is a mark-up language that defines a set of rules for defining data in a format which is very focussed on being machine-readable but both software and hardware independent. Therefore it has great appeal to those writing packages that are designed to be very efficient code, very portable across different applications, where non-technical people just accept the outputs provided and don't need to understand what goes on within the black box. If you don't want to use PHP, or just don't understand how to use it, you might consider this and you will find more about this approach on the [[xml webtags|XML web tags]] page in this wiki.
Some people consider XML is too complicated and a long winded way to represent variables (they would say languages like PHP are easier for humans to read), but XML was the way that Steve Loft chose to implement the Weather Diary feature in Cumulus 1, so if you want to include whether snow is falling or lying (or the text entered into the diary) in your web pages you must use a routine that reads XML within the PHP you write if you are still using Cumulus 1.
Before leaving the subject of XML it is worth recording that XML is considered as the best approach for the future by many after it became a part of the standard for SQL from 2000. SQL is the most popular way to access and maintain data, so extending it from only working with relational (table based) databases, to updating XML formatted information has given XML a big boost ''(for example the WMO and ICAO have specified a XML and geographical location based approach for reporting weather conditions at airports and for some years have been persuading those running airports to swap from reporting METAR in traditional alphanumeric characters. The alphanumerical shorthand approach was introduced when the shortness of the code was critical for easy transmission by telex)''. The new approach is not designed for human observers and pilots to read the weather reports as reported, but being machine readable makes it easier for computer driven flying to take account of changing weather conditions and it can be presented to pilots in a more friendly graphical way, in the cockpit, changing the mix of information shown as they move along their route.
== Option 2: PHP array or Multiple PHP Variables ==
Another approach is to create a separate PHP variable (or in a few cases an array) for each Cumulus web tag:
1. You write one or more Cumulus template files, each having a "<?php" in the first line, each then has a number of lines of the following format:
<pre>$_php_variable_name = '<#_cumulus_tag_name optional_input_parameters optional_output_parameters>';</pre>
2. One convention is to make the php_variable_name match the cumulus_tag_name. This breaks down if you use names like $version for other purposes, or if you get confused by the random naming standard adopted by Steve Loft (some yesterday tags have Y at end, some don't, sometimes Y means yesterday, other times Y means yearly), so feel feel free to invent you own consistent naming standard.
3. If the cumulus web tag always returns a numeric value, it is better to leave off the quotes, because then it can be used in PHP arithmetic more easily. To discover all available web tags for the Cumulus version you are using see [[Webtags|top of Web tags page]]. See the examples at the start of this article for some monthly tags that don't return numerical values on the first day of a month.
4. I have shown single quotes in my example, but they do not always work, see the notes at the start of this page, there is further discussion about problems with delimiting strings at [https://cumulus.hosiene.co.uk/viewtopic.php?f=4&t=1 this cumulus support forum link].
5. In the format example, I mention input parameters, see the [[Webtags|Web tags article]] page for full details of where you can use them, but they might indicate what information you are seeking if like '''Recent History''' you can get values for a range of different times. I also mention output formats, these are also explained on the web tags page, but they might select whether a time is shown in am/pm format or 24-hour format, whether a date uses the full month name or a number and so on.  You might want to quote the same web tag with different selections and either assign each to a different variable name or to a different element of an array variable.
6. You can include PHP comments any where you like, if on a separate line delimit by "/*" to "*/", if at end of line prefix by "#" or "//". '''Don't put any special characters''' at the end of this file, it will become '''pure PHP''', and that '''never uses a terminator''' "?&gt;". That terminator is needed only in mixed content files when there are HTML statements after the terminator.
7. I say above "1 or more template files". Since you can tell Cumulus to process/upload files at different intervals, you might want to include those web tags that change frequently (now and today for example) in a template file that you will action at the real time interval, and include those web tags that rarely change (e.g. yesterday, station-related, units) in a template file that is only uploaded at end of day. Yet another template file can be uploaded at normal updating interval, that might include the monthly and yearly tags for example. You decide what suits your own restrictions on total size of files to upload at different frequencies.
8. Having produced this template file, give it a name that makes sense to you, some people include a T just before the extension to remind you it is a template file. The normal extension is ".txt", although some peole use '.tpl' to indicate it is a template, but you could be inventive and put ".cum" if you want; Cumulus will not care what extension is used for a file it is asked to process.
9. The template files are then listed in the "extra files" settings of Cumulus, so they are processed at a selected interval and turned into PHP scripts. In this case your customised pages would replace any reference to a Cumulus web tag <code><#xxyyzz optional_parameter></code> by a PHP variable or array - either <code>$xxyyzz[optional_index]</code> or <code>$xyyxwx</code>.
10. To make use of the relevant script in your customised pages, use the instruction '''require cumuluswebtags.php''', substituting whatever you set as the remote name.
'''For more information''' on how to write a template file or how to ask Cumulus to process files see [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by Cumulus]] topic.
The ready made templates referenced earlier are all template files using either PHP variables or PHP arrays and therefore alternatives to producing your own files using the instructions above.
== Option 3: JavaScript Object Notation ==
This is a lightweight data-interchange format that is easy for humans to read and write, but critically it is easy for machines to parse and generate for transferring the variables in a portable way.
Cumulus MX uses this approach to provide variables for plotting the charts on your web site.
*To have the json files uploaded to your web site, you must enable '''Include standard files''' within the ''Web/FTP settings'' section of '''Internet Settings'''.
*Cumulus MX has one json file per weather chart
* Within each json file there is an array defined; each element of that array being a sub-array containing a time-stamp and the value at that time.
*The interval between sub-arrays depends on the chart, for daily rain and daily temperature there is a sub array for each day; but for most there is a sub-array for every minute (assuming Cumulus is left running for long enough) for a full 24 hours.
If you want to set up your own json files, you may follow the same approach but need to choose the interval between such sub-arrays that suits your use in your web pages.


= Using PHP script =
= Using PHP script =
Line 288: Line 341:
<?php } ?>
<?php } ?>
</pre>
</pre>
= The different Main Approaches to data transfer =
The main focus of this article is assigning to PHP variables, but similar arguments apply for XML or JSON approaches so let us briefly review all the different approaches.
== Option 1: eXtensible Markup Language alternative ==
Extensible Markup Language (XML) is a mark-up language that defines a set of rules for defining data in a format which is very focussed on being machine-readable but both software and hardware independent. Therefore it has great appeal to those writing packages that are designed to be very efficient code, very portable across different applications, where non-technical people just accept the outputs provided and don't need to understand what goes on within the black box. If you don't want to use PHP, or just don't understand how to use it, you might consider this and you will find more about this approach on the [[xml webtags|XML web tags]] page in this wiki.
Some people consider XML is too complicated and a long winded way to represent variables (they would say languages like PHP are easier for humans to read), but XML was the way that Steve Loft chose to implement the Weather Diary feature in Cumulus 1, so if you want to include whether snow is falling or lying (or the text entered into the diary) in your web pages you must use a routine that reads XML within the PHP you write if you are still using Cumulus 1.
Before leaving the subject of XML it is worth recording that XML is considered as the best approach for the future by many after it became a part of the standard for SQL from 2000. SQL is the most popular way to access and maintain data, so extending it from only working with relational (table based) databases, to updating XML formatted information has given XML a big boost ''(for example the WMO and ICAO have specified a XML and geographical location based approach for reporting weather conditions at airports and for some years have been persuading those running airports to swap from reporting METAR in traditional alphanumeric characters. The alphanumerical shorthand approach was introduced when the shortness of the code was critical for easy transmission by telex)''. The new approach is not designed for human observers and pilots to read the weather reports as reported, but being machine readable makes it easier for computer driven flying to take account of changing weather conditions and it can be presented to pilots in a more friendly graphical way, in the cockpit, changing the mix of information shown as they move along their route.
== Option 2: PHP array or Multiple PHP Variables ==
Another approach is to create a separate PHP variable (or in a few cases an array) for each Cumulus web tag:
1. You write one or more Cumulus template files, each having a "&lt;?php" in the first line, each then has a number of lines of the following format:
<pre>$_php_variable_name = '<#_cumulus_tag_name optional_input_parameters optional_output_parameters>';</pre>
2. One convention is to make the php_variable_name match the cumulus_tag_name. This breaks down if you use names like $version for other purposes, or if you get confused by the random naming standard adopted by Steve Loft (some yesterday tags have Y at end, some don't, sometimes Y means yesterday, other times Y means yearly), so feel feel free to invent you own consistent naming standard.
3. If the cumulus web tag always returns a numeric value, it is better to leave off the quotes, because then it can be used in PHP arithmetic more easily. To discover all available web tags for the Cumulus version you are using see [[Webtags|top of Web tags page]]. See the examples at the start of this article for some monthly tags that don't return numerical values on the first day of a month.
4. I have shown single quotes in my example, but they do not always work, see the notes at the start of this page, there is further discussion about problems with delimiting strings at [https://cumulus.hosiene.co.uk/viewtopic.php?f=4&t=1 this cumulus support forum link].
5. In the format example, I mention input parameters, see the [[Webtags|Web tags article]] page for full details of where you can use them, but they might indicate what information you are seeking if like '''Recent History''' you can get values for a range of different times. I also mention output formats, these are also explained on the web tags page, but they might select whether a time is shown in am/pm format or 24-hour format, whether a date uses the full month name or a number and so on.  You might want to quote the same web tag with different selections and either assign each to a different variable name or to a different element of an array variable.
6. You can include PHP comments any where you like, if on a separate line delimit by "/*" to "*/", if at end of line prefix by "#" or "//". '''Don't put any special characters''' at the end of this file, it will become '''pure PHP''', and that '''never uses a terminator''' "?&gt;". That terminator is needed only in mixed content files when there are HTML statements after the terminator.
7. I say above "1 or more template files". Since you can tell Cumulus to process/upload files at different intervals, you might want to include those web tags that change frequently (now and today for example) in a template file that you will action at the real time interval, and include those web tags that rarely change (e.g. yesterday, station-related, units) in a template file that is only uploaded at end of day. Yet another template file can be uploaded at normal updating interval, that might include the monthly and yearly tags for example. You decide what suits your own restrictions on total size of files to upload at different frequencies.
8. Having produced this template file, give it a name that makes sense to you, some people include a T just before the extension to remind you it is a template file. The normal extension is ".txt", although some peole use '.tpl' to indicate it is a template, but you could be inventive and put ".cum" if you want; Cumulus will not care what extension is used for a file it is asked to process.
9. The template files are then listed in the "extra files" settings of Cumulus, so they are processed at a selected interval and turned into PHP scripts. In this case your customised pages would replace any reference to a Cumulus web tag <code><#xxyyzz optional_parameter></code> by a PHP variable or array - either <code>$xxyyzz[optional_index]</code> or <code>$xyyxwx</code>.
10. To make use of the relevant script in your customised pages, use the instruction '''require cumuluswebtags.php''', substituting whatever you set as the remote name.
'''For more information''' on how to write a template file or how to ask Cumulus to process files see [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by Cumulus]] topic.
The ready made templates referenced earlier are all template files using either PHP variables or PHP arrays and therefore alternatives to producing your own files using the instructions above.
== Option 3: JavaScript Object Notation ==
This is a lightweight data-interchange format that is easy for humans to read and write, but critically it is easy for machines to parse and generate for transferring the variables in a portable way.
Cumulus MX uses this approach to provide variables for plotting the charts on your web site.
*To have the json files uploaded to your web site, you must enable '''Include standard files''' within the ''Web/FTP settings'' section of '''Internet Settings'''.
*Cumulus MX has one json file per weather chart
* Within each json file there is an array defined; each element of that array being a sub-array containing a time-stamp and the value at that time.
*The interval between sub-arrays depends on the chart, for daily rain and daily temperature there is a sub array for each day; but for most there is a sub-array for every minute (assuming Cumulus is left running for long enough) for a full 24 hours.
If you want to set up your own json files, you may follow the same approach but need to choose the interval between such sub-arrays that suits your use in your web pages.


=Option 2 - implementation details=
=Option 2 - implementation details=
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/6417"