Cumulus template file - Revision history

Sfws: /* Case sensitivity */

2021-04-08T22:10:03Z

Case sensitivity

← Older revision		Revision as of 22:10, 8 April 2021
Line 18:		Line 18:
	==== Case sensitivity ====		==== Case sensitivity ====

	The '''tag_name''' in the general format (see above) is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]]. Steve Loft did not define a consistent naming standard, so don't make any assumptions about what case he selected for each character, and remember that some names (as explained later) are less easy to predict than others.		The '''tag_name''' in the general format (see above) is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]]. Steve Loft did not define a consistent naming standard, so don't make any assumptions about what case he selected for each character, and remember that some names (as [[#Inconsistency_of_web_tag_names\|explained later]]) are less easy to predict than others.

	Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.		Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.

Sfws: /* Using web tags in scripts */

2021-04-08T22:08:00Z

Using web tags in scripts

← Older revision		Revision as of 22:08, 8 April 2021
Line 45:		Line 45:
	If your JavaScript is less structured, then a .js script template can perform arithmetic, and/or validation, on web tags. This gives you more flexibility about how information appears on your web page, and it can support graphical ways of presenting data. JavaScript files can be called from a web page when it is viewed in a browser; consequently, your HTML file can be a static file on your web server, and call a JavaScript file that Cumulus has generated and uploaded, and that script can amend the contents of table cells in your HTML to display the latest data. A variant is AJAX, where a timer allows a fresh JavaScript file to be uploaded (without reloading the web page) and thus refresh the table cell contents; this is discussed elsewhere on more technical pages of this wiki (see [[:Category:WebTips]]).		If your JavaScript is less structured, then a .js script template can perform arithmetic, and/or validation, on web tags. This gives you more flexibility about how information appears on your web page, and it can support graphical ways of presenting data. JavaScript files can be called from a web page when it is viewed in a browser; consequently, your HTML file can be a static file on your web server, and call a JavaScript file that Cumulus has generated and uploaded, and that script can amend the contents of table cells in your HTML to display the latest data. A variant is AJAX, where a timer allows a fresh JavaScript file to be uploaded (without reloading the web page) and thus refresh the table cell contents; this is discussed elsewhere on more technical pages of this wiki (see [[:Category:WebTips]]).
	*As JavaScript can not understand a real number that has the integer and decimal parts separated by a comma, but your computer may be set to use that representation in standard tags, there are special versions of many tags to use in script - see [[Webtags#No_Commas\|tags with commas removed]] section.		*As JavaScript can not understand a real number that has the integer and decimal parts separated by a comma, but your computer may be set to use that representation in standard tags, there are special versions of many tags to use in script - see [[Webtags#No_Commas\|tags with commas removed]] section.
	*JavaScript is available in every modern browser (Microsoft's Internet Explorer initially used a different language '''jScript'''), but actually it is hard to get right. A human being recognises something as a number or text or operation. Programmers writing in JavaScript can use Objects, but you need to be skilled to do that. Without Objects, it is easy to write code that gets text and numbers confused; for example you can have two variables ('''door1''' and '''door2''') defining width of two adjacent doors and want total opening size in variable '''Opening'''. The code <tt>Opening = door1 + door2;</tt> ~~might~~ ~~return~~ ~~the~~ ~~correct~~ ~~number~~ ~~if it recognises these are numbers (because they contain a decimal point)~~, or it ~~might treat~~ them as ~~text~~ ~~(especially~~ if ~~they~~ ~~are~~ ~~integers)~~ ~~and~~ ~~just~~ ~~concatenate~~ ~~the~~ ~~text!~~ ~~See bullet point below where~~ "~~parseInt~~" ~~is used~~ to make JavaScript recognise ~~integers as~~ numbers.		*JavaScript is available in every modern browser (Microsoft's Internet Explorer initially used a different language '''jScript'''), but actually it is hard to get right. A human being recognises something as a number or text or operation. Programmers writing in JavaScript can use Objects, but you need to be skilled to do that. Without Objects, it is easy to write code that gets text and numbers confused; for example you can have two variables ('''door1''' and '''door2''') defining width of two adjacent doors and want total opening size in variable '''Opening'''. The code <tt>Opening = door1 + door2;</tt> generally will just concatenate the text, rather than add them as numbers! There is some guidance below on how to use "parse" functions to make JavaScript recognise numbers.

	PHP Hypertext Preprocessor (PHP) is another script language, it is parsed on the web server and so the browser only sees what is generated by the PHP script, not the actual script. PHP can do a lot, so it takes some time to learn, but it is very simple in concept, and you should find writing simple scripts is surprisingly easy once you master the syntax. There are many guides to writing PHP online, and you may find the notes on [[PHP]] page helpful in a Cumulus context.		PHP Hypertext Preprocessor (PHP) is another script language, it is parsed on the web server and so the browser only sees what is generated by the PHP script, not the actual script. PHP can do a lot, so it takes some time to learn, but it is very simple in concept, and you should find writing simple scripts is surprisingly easy once you master the syntax. There are many guides to writing PHP online, and you may find the notes on [[PHP]] page helpful in a Cumulus context.
Line 57:		Line 57:
	Alternatively, in most script languages, apply ' 1', i.e. multiply by one, to implicitly convert the tag from string to base 10 number.		Alternatively, in most script languages, apply ' 1', i.e. multiply by one, to implicitly convert the tag from string to base 10 number.
	*Another alternative is to add zero when a web tag is being assigned to a script variable, this is frequently used in scripts where the web tag being used is not available in all versions of Cumulus, because Cumulus does not implement the concept of null values and often zero is used when a true value is not available because that sensor is not installed for example. Adding 0 means that if the web tag is not recognised, the script is still able to give a variable in its language some value and won't fail because that variable is undefined. If the web tag is available, adding zero does not prevent the true value of that web tag being assigned to the variable.		*Another alternative is to add zero when a web tag is being assigned to a script variable, this is frequently used in scripts where the web tag being used is not available in all versions of Cumulus, because Cumulus does not implement the concept of null values and often zero is used when a true value is not available because that sensor is not installed for example. Adding 0 means that if the web tag is not recognised, the script is still able to give a variable in its language some value and won't fail because that variable is undefined. If the web tag is available, adding zero does not prevent the true value of that web tag being assigned to the variable.


	==Inconsistency of web tag names==		==Inconsistency of web tag names==

Sfws: /* Template files you add */

2021-04-08T22:04:40Z

Template files you add

← Older revision		Revision as of 22:04, 8 April 2021
Line 26:		Line 26:
	=Template files you add=		=Template files you add=

		⚫	As explained on this page, template file can generate a variety of file types. People writing their own templates can use any file extension (some popular choices are "tmpl" or "cum" to indicate they are Cumulus templates). To ensure that the template files and generated web pages cannot be confused, Steve Loft realised the "T" notation used by the provided templates may not be part of the name used by third parties for their templates, hence he designed Cumulus such that (for a non-standard name) the generated file will have "tmp" added to the end of the template name you selected, just to remind you of its temporary existence (until the source template is processed again). That "tmp" is removed when the final web page is stored on your web server.
⚫	~~The~~ ~~page~~ ~~dealing~~ ~~with~~ ~~the~~ ~~customisation~~ of web ~~templates~~ is [[Customised templates]], ~~and~~ it ~~includes~~ a diagram that explains how file names are affected by your choices in some of the settings for file transfer.

⚫	People writing their own templates can use any file extension (some popular choices are "tmpl" or "cum" to indicate they are Cumulus templates). To ensure that the template files and generated web pages cannot be confused, Steve Loft realised the "T" notation used by the provided templates may not be part of the name ~~you~~ ~~choose~~, hence the generated file will have "tmp" added to the end of the template name you selected, just to remind you of its temporary ~~existance~~ until the source template is processed again. That "tmp" is removed when the final web page is stored on your web server.

	''Note: When you put a tag into your template, be careful that whatever program you are using to develop your web pages doesn't change the angle brackets to slightly different symbols -- this is a common cause of failure!'' There are a number of editing tools that are '''designed for editing programming code''' and you should use one of those (e.g. Notepad++, Brackets, NoteTab Light, HTML kit, amongst many others), ''rather than a tool designed for web page design editing'' (e.g. Dreamweaver, word press, amongst others).		''Note by Steve Loft: When you put a tag into your template, be careful that whatever program you are using to develop your web pages doesn't change the angle brackets to slightly different symbols -- this is a common cause of failure!''

			There are a number of editing tools that are '''designed for editing programming code''' and you should use one of those (e.g. Notepad++, Brackets, NoteTab Light, HTML kit, amongst many others), ''rather than a tool designed for web page design editing'' (e.g. Dreamweaver, word press, amongst others).

	=== Using web tags in templates for creating HTML pages ===		=== Using web tags in templates for creating HTML pages ===

		⚫	If you want your template file to generate a web page, then this is discussed fully on the [[Customised templates]] page, where there is a diagram that explains how file names are affected by your choices in some of the settings for file transfer.
	You can include special markers in your template file that are called web tags; during processing Cumulus will replace them with the actual values.

			Here I just remind you that [[Webtags\|Cumulus web tags]] are the special markers in your template file; during processing of that template file, Cumulus will replace them with the actual values, in the web page it creates. However, this is just one of many ways to build your own website with Hyper-Text Manipulation Language file with your layout, including static text and perhaps graphics, calling a Cascading Style sheet to define the look. Creating a template with all the content needed for a web page means you are uploading large files (with a significant proportion of their content never changing) every time you want new data on your web site, so the next section describes an alternative way to use a template file to get just the data to your web server.
	Typically you would use this to build your own website by having an HTML template file with your layout, static text and graphics.

	=== Using web tags in scripts ===		=== Using web tags in scripts ===

			As mentioned in previous section, it is inefficient to create a template file where the majority of the content is not web tags and so never changes. JavaScript Object Notation (JSON) files are probably the most efficient way for template files to include just web tags, with minimal structure around them. (In fact MX uses this approach).
	*You can also use the tags within script, this might be a PHP script, or JavaScript either embedded in HTML, or in external files, to transfer the values (or the result of calculations based on those values) to your web server for further processing.

⚫	*As JavaScript can not understand a real number that has the integer and decimal parts separated by a comma, but your computer may be set to use that representation in standard tags, there are special versions of many tags to use in script - see [[#No_Commas\|tags with commas removed]] section.
			If your JavaScript is less structured, then a .js script template can perform arithmetic, and/or validation, on web tags. This gives you more flexibility about how information appears on your web page, and it can support graphical ways of presenting data. JavaScript files can be called from a web page when it is viewed in a browser; consequently, your HTML file can be a static file on your web server, and call a JavaScript file that Cumulus has generated and uploaded, and that script can amend the contents of table cells in your HTML to display the latest data. A variant is AJAX, where a timer allows a fresh JavaScript file to be uploaded (without reloading the web page) and thus refresh the table cell contents; this is discussed elsewhere on more technical pages of this wiki (see [[:Category:WebTips]]).
		⚫	*As JavaScript can not understand a real number that has the integer and decimal parts separated by a comma, but your computer may be set to use that representation in standard tags, there are special versions of many tags to use in script - see [[Webtags#No_Commas\|tags with commas removed]] section.
			*JavaScript is available in every modern browser (Microsoft's Internet Explorer initially used a different language '''jScript'''), but actually it is hard to get right. A human being recognises something as a number or text or operation. Programmers writing in JavaScript can use Objects, but you need to be skilled to do that. Without Objects, it is easy to write code that gets text and numbers confused; for example you can have two variables ('''door1''' and '''door2''') defining width of two adjacent doors and want total opening size in variable '''Opening'''. The code <tt>Opening = door1 + door2;</tt> might return the correct number if it recognises these are numbers (because they contain a decimal point), or it might treat them as text (especially if they are integers) and just concatenate the text! See bullet point below where "parseInt" is used to make JavaScript recognise integers as numbers.

			PHP Hypertext Preprocessor (PHP) is another script language, it is parsed on the web server and so the browser only sees what is generated by the PHP script, not the actual script. PHP can do a lot, so it takes some time to learn, but it is very simple in concept, and you should find writing simple scripts is surprisingly easy once you master the syntax. There are many guides to writing PHP online, and you may find the notes on [[PHP]] page helpful in a Cumulus context.

	*Note that if a PHP or JavaScript file contains any Cumulus web tags then you must [[Customised_templates#What_to_select_on_the_.27Files.27_tab_of_the_Internet_Settings_screen_within_the_.27Configuration.27_menu\|ask Cumulus to process]] the script file.		*Note that if a PHP or JavaScript file contains any Cumulus web tags then you must [[Customised_templates#What_to_select_on_the_.27Files.27_tab_of_the_Internet_Settings_screen_within_the_.27Configuration.27_menu\|ask Cumulus to process]] the script file.
	*JavaScript processing code can be embedded in a template that is already being processed into HTML. (This technique has been used in the standard 'monthlyrecordT.htm' template).		*JavaScript processing code can be embedded in a template that is already being processed into HTML. (This technique has been used in the standard 'monthlyrecordT.htm' template).
	*Alternatively embed a bit of JavaScript assignment code in HTML, that is already been processed, to convert the tags to a collection of string variables and use those variable names in any external script called from the HTML file. (This technique has been used in the standard 'gaugesT.htm' template).		*Alternatively embed a bit of JavaScript assignment code in HTML, that is already been processed, to convert the tags to a collection of string variables and use those variable names in any external script called from the HTML file. (This technique has been used in the standard 'gaugesT.htm' template in the legacy Cumulus 1 software).
	*To use the value from a tag as an integer in JavaScript assigning code you need to use a		*To use the value from a tag as an integer in JavaScript assigning code you need to use a
	<pre>integer_variable_name=parseInt(string_variable_name,10)</pre> type conversion		<pre>integer_variable_name=parseInt(string_variable_name,10)</pre> type conversion
Line 82:		Line 89:

	In the web tag to PHP variable scripts, I have posted, see [[Php_webtags#Minimised_Upload_size]], I have tried to introduce better consistency in the PHP variable names, so "T" is added as a suffix to all "today" variables for example. Some other script authors try to match the inconsistent web tag names, so their script variable names are also inconsistent.		In the web tag to PHP variable scripts, I have posted, see [[Php_webtags#Minimised_Upload_size]], I have tried to introduce better consistency in the PHP variable names, so "T" is added as a suffix to all "today" variables for example. Some other script authors try to match the inconsistent web tag names, so their script variable names are also inconsistent.



	=Cumulus MX=		=Cumulus MX=

Sfws: /* Case sensitivity */

2021-04-08T21:13:24Z

Case sensitivity

← Older revision		Revision as of 21:13, 8 April 2021
Line 18:		Line 18:
	==== Case sensitivity ====		==== Case sensitivity ====

	The tag_name in the general format (see above) is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]]. Steve Loft did not define a consistent naming standard, so don't make any assumptions about what case he selected for each character, and remember that some names (as explained later) are less easy to predict than others.		The '''tag_name''' in the general format (see above) is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]]. Steve Loft did not define a consistent naming standard, so don't make any assumptions about what case he selected for each character, and remember that some names (as explained later) are less easy to predict than others.

	Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.		Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.

Sfws: /* Case sensitivity */

2021-04-08T21:13:08Z

Case sensitivity

← Older revision		Revision as of 21:13, 8 April 2021
Line 18:		Line 18:
	==== Case sensitivity ====		==== Case sensitivity ====

	The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]].		The tag_name in the general format (see above) is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]]. Steve Loft did not define a consistent naming standard, so don't make any assumptions about what case he selected for each character, and remember that some names (as explained later) are less easy to predict than others.

	Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.		Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.

Sfws: /* General Format for Web Tags */

2021-04-08T21:09:12Z

General Format for Web Tags

← Older revision		Revision as of 21:09, 8 April 2021
Line 14:		Line 14:
	==General Format for Web Tags==		==General Format for Web Tags==

	In the position on the ~~page~~ you wish Cumulus to insert the relevant data place a web tag in the '''general format''' specified here: <pre><#tag_name [optional input parameters][optional output parameters]></pre>		In the position, in the template file, where you wish Cumulus to insert the relevant data, place a web tag observing the '''general format''' specified here: <pre><#tag_name [optional input parameters][optional output parameters]></pre>

	==== Case sensitivity ====		==== Case sensitivity ====
Line 20:		Line 20:
	The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]].		The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags\|web tags page]].

	~~The optional~~ input parameters always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.		Any '''input selection parameters''' always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.

	~~The optional~~ output parameters are case insensitive ~~when~~ ~~used~~ in Cumulus 1. But for ~~Cumulus 2 and later, so this includes~~ MX, ~~the~~ output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully.		Where '''output formatting parameters''' are used, they are ''case insensitive'' for processing by Delphi parser in legacy Cumulus 1. But '''for MX''', all output parameters are ''case sensitive'', '''and''' also ''dependent on what other output formatters are being used'' if any, so please read the sections on output parameters and study the examples in the tables carefully.

	=Template files you add=		=Template files you add=

Sfws: /* Introduction */ typo

2021-04-08T21:03:43Z

Introduction: typo

← Older revision		Revision as of 21:03, 8 April 2021
Line 8:		Line 8:
	A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.		A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.

	When Cumulus processes any template file, it generates an output file where every included [[Webtags\|Cumulus web tags]] ~~have~~ been replaced by values, while any other content is retained unchanged.		When Cumulus processes any template file, it generates an output file where every included [[Webtags\|Cumulus web tags]] has been replaced by values, while any other content is retained unchanged.

	Consequently, a single template will actually generate a different file each time Cumulus processes that template because the part of the content that was web tags is now populated with text (values, times, dates, etc.) and, as these values change, a newly generated file is different to the previous generated file.		Consequently, a single template will actually generate a different file each time Cumulus processes that template because the part of the content that was web tags is now populated with text (values, times, dates, etc.) and, as these values change, a newly generated file is different to the previous generated file.

Sfws: /* Introduction */

2021-04-08T21:03:17Z

Introduction

← Older revision		Revision as of 21:03, 8 April 2021
Line 8:		Line 8:
	A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.		A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.

	When Cumulus processes ~~these~~ ~~files~~ it generates output ~~files~~ where ~~the~~ tags~~/tokens~~ have been replaced by values.		When Cumulus processes any template file, it generates an output file where every included [[Webtags\|Cumulus web tags]] have been replaced by values, while any other content is retained unchanged.

	Consequently, a single template will actually generate a different file each time Cumulus processes that template because the part of the content that was web tags is now populated with text (values, times, dates, etc.) and, as these values change, a newly generated file is different to the previous generated file.		Consequently, a single template will actually generate a different file each time Cumulus processes that template because the part of the content that was web tags is now populated with text (values, times, dates, etc.) and, as these values change, a newly generated file is different to the previous generated file.

Sfws: /* Your own templates */

2021-04-08T21:00:43Z

Your own templates

← Older revision		Revision as of 21:00, 8 April 2021
Line 148:		Line 148:
	#Next you ask Cumulus [[Customised_templates#What_to_select_on_the_.27Files.27_tab_of_the_Internet_Settings_screen_within_the_.27Configuration.27_menu\|to process]] that template file, it will create a HTML page from the template, and during that file creation replace the tag with the current value of the item the tag represents.		#Next you ask Cumulus [[Customised_templates#What_to_select_on_the_.27Files.27_tab_of_the_Internet_Settings_screen_within_the_.27Configuration.27_menu\|to process]] that template file, it will create a HTML page from the template, and during that file creation replace the tag with the current value of the item the tag represents.
	#You also need to tell Cumulus that the resulting HTML file is to be uploaded to the internet (or copied to a local web server).		#You also need to tell Cumulus that the resulting HTML file is to be uploaded to the internet (or copied to a local web server).
			[[Category:Cumulus MX]]

Sfws: /* Introduction */

2021-04-08T20:58:52Z

Introduction

← Older revision		Revision as of 20:58, 8 April 2021
Line 5:		Line 5:
	=Introduction=		=Introduction=

			[[Category:WebTips]]

	A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.		A '''Cumulus Template File''' is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.

Line 23:		Line 23:

	The optional output parameters are case insensitive when used in Cumulus 1. But for Cumulus 2 and later, so this includes MX, the output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully.		The optional output parameters are case insensitive when used in Cumulus 1. But for Cumulus 2 and later, so this includes MX, the output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully.


	=Template files you add=		=Template files you add=