Cumulus Wiki

Webtags (preserving history): Difference between revisions

Webtags (preserving history) (view source)

Revision as of 08:35, 19 May 2020

5,372 bytes added ,  08:35, 19 May 2020
m
no edit summary
mNo edit summary
Line 1: Line 1:
[[Category:Terminology]]
[[Category:Terminology]]
This Wiki page describes web tags (tokens that Cumulus uses to indicate where when processing a file it should insert values) that apply to all flavours of Cumulus (Cumulus 1, 2 and 3 aka MX), any differences are highlighted as necessary.


'''GENERAL TIP'''
This Wiki page covers more than just web tags, it lists the way that you can specify the naming format for the NOAA style reports that Cumulus produces.
 
 
However, the main purpose of this page is to explain web tags (tokens that Cumulus uses to indicate where when processing a file it should insert values) that apply to all flavours of Cumulus (Cumulus 1, 2, and 3 aka MX), any differences are highlighted as necessary. Remember as Cumulus is developed more and more web tags are made available, if you are not using the latest release, then some of those listed in this article may not be available. In general, Cumulus 1 will silently ignore any web tags it does not recognise, but MX will raise an error for any web tag it does not understand how to process.
 
Please note some items on this page apply to specifying the report name format (NOAA style), but all items refer to what are called '''template files''', those are files that Cumulus (1 or MX) is asked to [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|process]] and that processing involves Cumulus recognising special markers (also known in MX as tokens) placed in the template file.
 
{{TOCright}}
 
=GENERAL TIP=
 
The web tags available in the version/build you are using, can be listed (in Cumulus 1 or Cumulus MX) by adding the following line to [[Cumulus.ini#Section:_Station|Cumulus.ini]] in the [station] section...
The web tags available in the version/build you are using, can be listed (in Cumulus 1 or Cumulus MX) by adding the following line to [[Cumulus.ini#Section:_Station|Cumulus.ini]] in the [station] section...


  ListWebTags=1
  ListWebTags=1


Then start Cumulus and it will create a file called WebTags.txt in the program folder containing a list of all the tags your build of Cumulus can currently generate. This list only contains the tag_names, it does not indicate what parameters they can take, nor does it include the brackets the tag name is surrounded by when you quote it in a template file for Cumulus to process. An example of the output for MX is at the end of this page (the actual output does not include commas, and has just one item per page, it has been compressed for inclusion there).
Then start Cumulus and it will create a file called WebTags.txt in the same folder as where the executable is found. That file will list all the tags your build of Cumulus can currently generate. This list only contains the tag_names, it does not indicate what parameters they can take, nor does it include the brackets the tag name is surrounded by when you quote it in a template file for Cumulus to process. An example of the output for MX is at the end of this page (the actual output does not include commas, and has just one item per line, it has been compressed for inclusion in this article).


To stop Cumulus continuing to produce new versions of that file change the line to say ...
To stop Cumulus continuing to produce new versions of that file change the line to say ...
Line 15: Line 24:
{{Version badge 1}}If you are using Cumulus 1, each build of that contains a build specific version of Cumulus Help, and within that help is a list of web tags with basic information on what each tag_name returns.
{{Version badge 1}}If you are using Cumulus 1, each build of that contains a build specific version of Cumulus Help, and within that help is a list of web tags with basic information on what each tag_name returns.


{{TOCright}}
= NOAA style Report Naming =
== Web tags available in Cumulus ==
 
Please note some items on this page apply to specifying the report name format (NOAA style), but all items refer to what are called '''template files''', those are files that Cumulus (1 or MX) is asked to [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|process]] and that processing involves Cumulus recognising special markers (also known in MX as tokens) placed in the template file.
== A brief history of these reports ==
 
Cumulus 1, 2, and MX, generate climatological reports for both Monthly and Yearly periods. The reports were first added to Cumulus 2 after someone asked for this feature in enhancement request 44. They were based on Weatherlink reports, that in turn were based on climatological reports issued by The US National Oceanic and Atmospheric Administration's National Weather Service (the reason for using NOAA in the naming of the reports). Ken True implemented the Weatherlink reports in his Saragota suite, and Steve Loft took that as his starting point. Although they were tested in Cumulus 2, they were added to Cumulus 1 in version 1.9.2 (build 1004) released in July 2011.
 
== Encoding ==
 
Let me expain that technical term, essentailly encoding refers to the character set used by any file. A computer uses binary, binary can only be in state 0 or state 1, so a combination of 0 and 1 states needs to be defined for every character you want to represent. What you can include in that character set depends to some extent on how many binary bits are used to be mapped to individual characters; and if more than one byte worth of bits is used the order in which the bits within the multiple bytes are used must be defined for each particualar encoding. With any fixed number of bits available, there will be a limit to how many characters can be defined, and different organisations might select different characters to include. This is what leads to multiple encoding standards. One might use a particular arrangement of bits to represent the degree symbol, while another encoding uses that particular arrangement of bits for a different purpose. This means that when you read a file you might find the letters A to Z where you expect them, but unless you know the encoding used, you don't know what character to display for certain combinations of bits.
 
If you use 7 bits, you have 127 combinations, enough for standard 26 letters in bothe upper case, and lower case, plus 10 digits (0 to 9), some punctuation, and some control characters (like new line, end of file, and so on). If you use 8 bits, a whole byte, you have 254 combinations, and you can start coping with accented letters, with alphabets that don't have 26 letters, and even add some symbols. Obviously, once you start using more than one byte, you can have 16, 32, or more bits to use and can include lots more characters.
In April 2014, Steve introduced the choice in Cumulus 1 of either ISO-8859-1 encoding (as he used originally) or UTF-8 encoding (what he migrated his web page templates to) for these reports. This choice remains unchanged in MX. The default selected by Steve Loft is his original ISO-8859-1 encoding, but be aware the encoding you use should match the encoding of any web page used for viewing these reports, and most modern web pages use UTF-8 encoding. The encoding can be selected on the NOAA Settings screen of either Cumulus 1 or MX.
 
== The format used for naming ==
 
The monthly reports have a name in this format '''"NOAAMO"...".txt"'''.  The yearly reports have a name in this format '''"NOAAYR"...".txt"'''
 
It is between the double quotes where I have placed '...' that Cumulus expects us to use the date output modifiers described. Note that the double quotes must be used at each of the places where they are shown when you define your report naming in the NOAA Settings screen of either Cumulus 1 or MX.  The default selected by Steve Loft is '''MMyyyy''' and '''yyyy''' respectively (expressed in a way that suits both Cumulus 1 and MX) so the inserted part is all numerical. Here is a table showing the main alternative options, for more details about these selectors see the [[to be inserted|table below]]  as there are obviously a lot more options.
{| class="wikitable" border="1"
|-
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!style="width:150px" | [[File:Badge vMx.png]]Mono Specifier for Cumulus MX
!style="width:600px" | Explanation
!style="width:150px" | Setting
!style="width:600px" | Example of produced name
|-
|mmyyyy
|MMyyyy
|Note that Cumulus 1 accepts lower or upper case, this is equivalent to default mentioned above
|"NOAAMO"MMyyyy".txt"
|NOAAMO032010.txt
|-
|YYYY
|yyyy
|Note that Cumulus 1 accepts lower or upper case, this is equivalent to default mentioned above
|"NOAAYR"yyyy".txt"
|NOAAYR2010.txt
|-
|MMMyyyy
|MMMyyyy
|Note that Cumulus 1 accepts lower or upper case, this represents a 3 letter month name as defined for your locale on your device, in '''.NET''' or in '''MONO'''
|"NOAAMO"MMMyyyy".txt"
|NOAAMOMar2010.txt
|-
|YY
|yy
|Note that Cumulus 1 accepts lower or upper case, this represents a 2 digit year number
|"NOAAYR"yy".txt"
|NOAAYR10.txt
}
 
 
= Web tags available in Cumulus =


Those special markers in the file are called web tags, during processing Cumulus will replace them with the actual values.  Typically you would use this to build your own website by having an HTML template file with your layout, static text and graphics.  In the position on the page you wish Cumulus to insert the relevant data place a web tag in the form:
Those special markers in the file are called web tags, during processing Cumulus will replace them with the actual values.  Typically you would use this to build your own website by having an HTML template file with your layout, static text and graphics.  In the position on the page you wish Cumulus to insert the relevant data place a web tag in the form:
Line 100: Line 160:


=Output 'format' Parameter=
=Output 'format' Parameter=
=== Output (format modifier) parameters for decimal places ===
=== Output (format modifier) parameters for decimal places ===
*<tt>dp=i</tt> is used for both Cumulus 1 and MX. The value '''i''' following the attribute '''dp''' is an integer, how many decimal places you want for the output you see. Only available for a limited range of web tags (including in MX <#MoonPercent> and <#MoonPercentAbs>).
*<tt>dp=i</tt> is used for both Cumulus 1 and MX. The value '''i''' following the attribute '''dp''' is an integer, how many decimal places you want for the output you see. Only available for a limited range of web tags (including in MX <#MoonPercent> and <#MoonPercentAbs>).
*<tt>tc=y</tt> is a new parameter for MX, the attribute '''tc''' takes the value 'y' to remove decimal places by truncation instaed of using <tt>dp=0</tt> which would round to nearest integer. e.g. <#MoonAge tc=y>. At present not available in any other web tags.
*<tt>tc=y</tt> is a new parameter for MX, the attribute '''tc''' takes the value 'y' to remove decimal places by truncation instead of using <tt>dp=0</tt> which would round to nearest integer. e.g. <#MoonAge tc=y>. At present not available in any other web tags.
 
=== Output (format modifier) indicating remove commas ===


=== Output (format modifier) for remove commas ===
"rc=y" is a '''new parameter for MX''', the attribute '''rc''' takes the value 'y' to replace any commas defined by the locale with full stops to separate integer and decimal parts of the output value. It is only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge) for MX versions up to and including 3.5.3. At the time of writing it is planned that all web tags that can output real numbers will implement an alternative syntax of <tt><#tag_name rc=y></tt> from the next version.
"rc=y" is a '''new parameter for MX''', the attribute '''rc''' takes the value 'y' to replace any commas defined by the locale with full stops to separate integer and decimal parts of the output value. It is only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge) for MX versions up to and including 3.5.3. At the time of writing it is planned that all web tags that can output real numbers will implement an alternative syntax of <tt><#tag_name rc=y></tt> from the next version.


=== Output (format modifier) parameters for times and dates ===
=== Output (format modifier) parameters for times and dates ===
Time/Date format codes are used in two places:
Time/Date format codes are used in two places:
# As part of report names for NOAA style reports (see [[Cumulus.ini#Section:_NOAA]])
# As part of report names for NOAA style reports (see [[Cumulus.ini#Section:_NOAA]])
Line 139: Line 203:
|-
|-
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!style="width:150px" | [[File:Badge vMx.png]].NET Specifier for Cumulus MX
!style="width:150px" | [[File:Badge vMx.png]]Mono Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Displays
!style="width:600px" | Example
!style="width:600px" | Example
Sfws
5,838

edits

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