WebLingo

WebLingo provides a technique for embedding OScript language code into HTML files and, in effect, creates an OScript-enhanced version of HTML. WebLingo is embedded into HTML via three mechanisms: directives, statements, and expressions.

Directives

Directives are the meta symbols used by WebLingo to control how the statements and expressions are interpreted. Directives are always indicated by the presence of two semicolons at the beginning of a line. WebLingo includes the following directives:

The webscript and end directives

The webscript directive declares a WebLingo function, called a webscript, to which formal parameters can be passed. Whenever an webscript directive is used, a matching end directive must be used to indicate the end of the webscript. For example:

		;;webscript FuncPopup( Record args, Dynamic node, List cmds )
				.... additional WebLingo code here ...
		;;end

If no webscript directive is found within a WebLingo source file prior to the first non-blank, non-comment line, then the following implied webscript directive is used (with an implied end directive):

		;;webscript MyWebscript

The call directive

The call directive invokes a webscript (a WebLingo function) contained within the same or another HTML template. Parameters can be passed to the called webscript. There is no return value, however, because a webscript is designed for output generation, not necessarily computation.

The following examples call a webscript within the same HTML template:

		;;call UpdateUserTasks( userInfo, taskList )
		;;call DisplayUserTasks

The following examples call a webscript in a different HTML template:

		;;call <htmlPrefix + "navpopup.html">( "Head" )
		;;call <htmlPrefix + "menufoot.html">()

The oscript and html directives

The oscript and html directives change the current default language. The oscript directive changes it to OScript; the html directive changes it back to HTML (the default language). The oscript directive is particularly useful when including a long stretch of OScript code since escaping each line with a prefixing semicolon would become tedious. The oscript directive is specified as follows:

		;;oscript{
		...oscript lines go here, without prefixing semicolons...
		%HTML lines must be prefixed by percent symbols
		;;}

When OScript is the default language, HTML lines must be specified with a prefixing percent ( % ) symbol. Note that HTML is the default mode and that the htmldiretive is only necessary if an oscript directive is currently in effect. The html directive is particularly useful when including a long stretch of HTML within a long stretch of OScript code. The html directive is specified as follows:

		;;html{
		...html lines go here, without prefixing percent symbols...
		;OScript lines will require prefixing semicolons.
		;;}

When the html directive is in effect, OScript lines must be specified with a prefixing semicolon ( ; ).

Statements

Since WebLingo is built upon OScript, the full power of OScript is available to a WebLingo author. In general, any OScript statement can be included into a WebLingo source file by prefixing it with a semicolon ( ; ). For example, the OScript if and for constructs can be used as follows:

		;if Length( .TaskList ) == 0
			
			You have no tasks assigned at this time
		;else

			Your tasks are:

					;for task in .TaskList
						Task: 'task.TaskName'
					;end
		;end

The above WebLingo fragment examines the TaskList and generates either a message (You have no tasks assigned at this time) or a simple list of task names.

Expressions

WebLingo expressions are HTML source lines that have OScript expressions embedded within them. During execution of an HTML template, these embedded expressions are evaluated, and their resultant values substituted at the corresponding positions in the resulting HTML page.

WebLingo expressions are preceded and followed by a back quote character ( ' ) and can reference any OScript object or feature to which the HTML template has access. For example:

		Project Info for `.Project.ProjectName`
		INPUT TYPE="RESET" VALUE="`[WebDsp_HTMLLabel.ResetButtonLabel]`"

Expression Escaping

By default, when an OScript expression is evaluated and expanded within WebLingo, the result is converted into a String and HTML Escaping is applied. HTML Escaping converts any HTML metacharacters found in the String into the corresponding HTML code. For example, the metacharacter > becomes > and < becomes <. This allows you to use HTML expressions within Strings that will have no effect on the generated HTML.

In some cases, you may want to inhibit this type of escaping to allow your code to generate more precise HTML. In this case, the WebLingo expression can include escape codes. Escaping in OScript is accomplished by prefixing one of the following five codes: %L, %D, %S, %U, or %H. These codes are defined as follows: