|
Predefined Object Properties
Predefined image properties are property names that have special meaning to WebLord. Some of these properties must be defined by you to give an object meaning, and in other cases a property supplies optional information or defines alternate behavior; such a missing property definition may thus merely influence how an object is constructed.
This section describes the properties for each object that have a predefined meaning.
- SITE object
-
- PAGE objects
-
- TEXT objects
-
- IMAGE objects (HTML only)
-
- Properties for use with IF / IFDEF / IFNDEF / SELECT
-
Predefined Properties for the SITE Object
NOTE: The SITE object occupies a special place with WebLord. Only the first such object is ever available, and its name is of little direct importance.
Properties defined in the SITE are inherited by all pages as well as the objects that these pages reference.
- pages
- If WebLord is run without a specific list of pages to generate, then the 'pages' property in the first SITE object supplies the list of pages that comprise the entire site. Pages that are defined in the site file, but not listed here can be generated only through explicit reference with a program argument.
- value-is-inheritable
- Although most properties not defined in one object are inherited from the object that referenced it, the
value property is not one of these. In other words, if an object does not define a value property (or one of its equivalents, such as if , select , etc.) then it simply has no value. There are times, however, when this is not desirable. To this end, the non-inheritance of the value property can be turned off, to allow it to inherit normally. This does not affect the value property's equivalents, of course.
- requires-version
- You should always use this property to indicate the lowest version of WebLord whose features your file relies on. In other words, if you make use of the
select-case feature introduced with WebLord 1.1, you should add a property definition sch as
requires-version = "1.1";
to your SITE object.
Why? WebLord ignores features that it does not yet know about; if, for example, WebLord 1.0 encounters a select-case property, it will completely ignore it, and instead complain that the object has no value property defined. In more subtle cases your objects may completely fail to produce the desired results because the version of WebLord you happen to be using is outdated.
The requires-version property guards against such unpleasant surprises!
- auto-quote-digits
- Fundamentally, WebLord processes two types of things: string literals and property/object references. String literals are quoted (with "..." or '...' or »...« sequences) and property/object references are not quoted. This means that what commonly passes as a literal value, such as the character sequence 12345678 is treated by WebLord as a property/object reference!
You can get WebLord to make a special exception to this rule by defining the auto-quote-digits property in the site object. Any property/object reference that begins with a digit is then auto-quoted so that it is treated as if it had been properly enclosed in quotes.
NOTE: This capability is switched on while WebLord loads the file. If the SITE object is the last one, then this switch is performed too late to be of any value. If your SITE object is the first one, however, then all subsequent objects are affected by the changed behavior of the "auto-quote-digits" property. It is worth noting that this limitation is based on the fact that WebLord does not dynamically quote numerically named references, but instead performs this step while object definitions are being loaded.
Predefined Properties for PAGE Objects
The 'value' of page objects is written to the file specified by their 'output' property.
- value (Not inherited, unless a (global) 'value-is-inheritable' property is defined)
- A list of identifiers that define the contents of the page.
- output
- A list of identifiers that define the output filename for the page.
- pre-exec (Never inherited)
- A list of identifiers that define an external command to be executed before the page is generated. This may be employed to produce a backup copy of a previous version of the page, prepare specific input files needed for the page, etc. Notice that the external command to be executed is operating system specific. An example of how to implement a more operating system independent method of executing external commands, see the
tools.wl file.
- post-exec (Never inherited)
- A list of identifiers that define an external command to be executed after the page has been generated and its output written to a file. If a page is not generated for any reason, the 'post-exec' command is not executed, either. Notice that the external command to be executed is operating system specific. An example of how to implement a more operating system independent method of executing external commands, see the
tools.wl file.
The 'post-exec' command is useful for post-processing of a page, such as archiving it, running an HTML validator on the page, and/or uploading the file to an internet service provider.
- post-exec-batch
- By declaring a 'post-exec-batch' property, all 'post-exec' commands for pages can be caused to be "batched" (grouped) together for execution after the last page has been generated. The 'post-exec-batch' property defines the filename that is used to store the commands. A NOEXEC argument given to WebLord will suppress the creation of this file as well as suppress all 'post-exec' commands.
WebLord knows how to ensure that the given file is executable for your particular operating system.
Predefined Properties for TEXT Objects
NOTE: By avoiding TEXT object properties marked "HTML only" you ensure that your output is free of any language dependency.
- ifdef (Never inherited)
- A list of identifiers, all of which must be defined (and have a non-empty value), otherwise the current object returns an empty value.
- ifndef (Never inherited)
- A list of identifiers; if any of them are defined (have a non-empty value), then the current object returns an empty value.
- if (Never inherited)
- A simple comparison expression of the form "value1 operator value2" where the operator is one of the six basic equality, inequality, less-than, greater-than, less-than-or-equal, or greater-than-or-equal (= != < > <= >=); if both operands begin with a digit 0 through 9 then the operation is performed numerically, else a string comparison is used. Depending on the success or failure of the expression the value is taken from a 'then' or 'else' instead.
Not that if a 'value-in-file' property is defined, then the value of the 'then' or 'else' properties is treated no differently than the standard 'value' property: it is the name of a file.
- foreach (Never inherited)
- As of version 1.2 WebLord supports the "foreach" property: Each word of the foreach property is in turn assigned to the (temporary) property named by the using property, and then the object is evaluated which is named by the do property.
The result of the object with the foreach property then has a value that is a concatenation of all the patterns generated by repeated evaluations of the do property using the named variable with the values named in the foreach property.
text = meaningOfLife
{
value = "<UL>n"
thingsInLife
"</UL>n";
}
text = thingsInLife
{
foreach = "Birth" "Growing up" "Programming the Amiga" "Get famous" "Enjoy life";
do = myList;
using = item;
}
text = myList
{
value = "<LI>" item "n";
}
Instead of referencing a new object (such as the myList object in the example above) you could have simply defined the thingsInLife object thus: text = thingsInLife
{
foreach = "Be born" "Grow up" "Program the Amiga" "Get famous" "Enjoy life";
do = myList;
using = item;
myList = "<LI>" item "n";
}
For simple cases like the above, this would certainly be easier!
- select-case (Never inherited)
- A convenient multi-if construct, selecting a property and producing a value that depends on the property value. The
select-case requires one or more additional properties, whose names begin with case: ; an example is:
text = YourSystem
{
select-case = _OS;
case:AMIGA = "Amiga";
case:UNIX = "Unix system";
case:WIN32 = "Windows 95 or Windows NT machine";
case: = "operating system";
}
Assuming that the _OS property is 'AMIGA' (or 'amiga' or 'AMiGA' or any combination of upper/lower case letters) then the case:AMIGA property is selected, and the value of the 'YourSystem' object becomes 'Amiga'. Notice that there is a property whose name begins with case: but has no additional text. This acts as the default property, if none of the others matched.
- html-quote-if-required (Never inherited)
- If an object defines this property, then the value of the object is enclosed in quotes if it contains any characters that are not HTML 3.2 legal in unquoted strings. Such characters include # / : and others.
- exec (Never inherited)
- Executes an external (shell) command to obtain a value for the object. The output of the command must be written to a file and the contents of this file is then retrieved by setting the 'value' property of the object to this file name and also defining the 'value-in-file' property (any value will do).
Most modern operating systems support the concept of "I/O redirection", which refers to sending the output of a program to a diskfile instead of the display. Syntactically, this is usually accomplished by placing a > symbol on the command line, followed by the name of the file that is to receive the output from the program.
By constructing the 'exec' property to include such I/O redirection, and setting the 'value-in-file' property to some value, the object can thus call upon external programs to generate values for the object dynamically.
Use the 'exec-cleanup' command to perform a cleanup operation (such as deleting the file after it is no longer needed.)
On the AMIGA, it is also possible to use named pipes, thus avoiding the use of physical diskspace and the need to cleanup a temporary file again.
- exec-cleanup (Never inherited)
- Executed after the object's value has been constructed (through the use of an 'exec' property). This is useful to get rid again of an external file that was needed to momentarily store an external program's output and allow WebLord to retrieve it as the object's value.
- value-in-file (Never inherited)
- If a 'value-in-file' property is defined then the 'value' property (or 'then' / 'else') defines the name of a file from which the value of the object is retrieved.
- file-has-variables (Never inherited)
- When combined with a
value-in-file property, the file-has-variables property permits the replacement of special sequences in the file with values defined (or inherited) by the current object. The sequences that WebLord requires begin with a ${ sequence, are followed by the property name, and ends with a } symbol. Do not use blank spaces within this sequence.
- As of version 1.2, WebLord supports an optional
(...) sequence within the ${...} symbol. This is the modifier list. Modifiers enclosed in the (...) sequence are comma-separated keywords that alter the meaning of the property name. The currently supported modifier are "include" which causes the specified property name to be considered a filename to be included instead, and "literal" which considers the specified property to be a literal value and will not resolve it first. Such a sequence would look like this:
${(include)file-to-include} or
${(include,literal)sys:etc/passwd}
This causes the contents of the file-to-include property (or object) to be resolved; the file named by this value will then be included; in the second version, the literal keyword overrides this resolution process and the named file sys:etc/passwd is included directly as named. This file is again parsed for ${...} sequences. At this time, this recursive inclusion can go 10 levels deep before WebLord aborts the operation. This limit will become adjustable sometime in the future.
Look here for an example of this feature!
- file-line-pattern (Never inherited)
- A single
%s symbol found in the file-line-pattern will cause lines read from a file to be enclosed in the text preceding and following that symbol. This provides for uniform modification of text from a file.
Notice that when the file-line-pattern is used to modify output, the trailing \n symbol must also be specified in the file-line-pattern , else lines will be merged all into one.
- value-is-date-pattern
- The 'value' property defines a pattern of special symbols according to the following table. Any sequence not understood is simply not interpreted in a special way, but instead inserted directly. If you do not actually use any of the symbols below, then the given value is effectively what you define:
Category | Symbol | Description of Symbol |
Year | %y | the year without the century as a decimal number (00-99) |
| %Y | the year with the century as a decimal number |
Month | %m | the month as a decimal number (01-12) |
| %b | the locale's abbreviated month name |
| %B | the locale's full month name |
Day | %j | the day of the year as a decimal number (001-366) |
| %d | the day of the month as a decimal number (01-31) |
Weekday | %a | the locale's abbreviated weekday name |
| %A | the locale's full weekday name |
| %w | the weekday as a decimal number (0-6), where Sunday is 0 |
Week | %U | the week number of the year (the first Sunday as the first day of week 1) as a decimal number (00-53) |
| %W | the week number of the year (the first Monday as the first day of week 1) as a decimal number (00-53) |
Hour | %H | the hour (24-hour clock) as a decimal number (00-23) |
| %I | the hour (12-hour clock) as a decimal number (00-12) |
Minute | %M | the minute as a decimal number (00-59) |
Second | %S | the second as a decimal number (00-59) |
Timezone | %Z | the timezone identifier¹ |
| %z | the timezone hours offset from GMT (ex: '+0100')¹ |
Other | %c | the locale's appropriate date and time representation |
| %x | the locale's appropriate date representation |
| %X | the locale's appropriate time representation |
| %p | the locale's equivalent of the AM and PM designations |
| %% | the percent sign |
¹ If the timezone (TZ) variable is not set, then the %Z/%z symbols will be resolved as if the value was "CST6" |
- value-is-env
- The 'value' property names an environment variable and the object's name becomes the contents of that environment variable.
- value (Not inherited, unless a (global) 'value-is-inheritable' property is defined)
- A list of identifiers that that define the value for the text object.
If the object defined an 'if' operation, then the 'then' or 'else' portion is used instead of the 'value'
NOTE: The 'value' (or 'then' / 'else') property defines a file name if a 'value-in-file' property is defined.
- value-is-static (Never inherited)
- If this property is defined (any value will do) then the value of the object is evaluated only the first time it is encountered and is thereafter stored. This is useful especially on objects with both an 'exec' and a 'value-in-file' property where you do not wish (or need to) execute the external program again and again to retrieve the same value.
Objects with the 'value-is-static' property are only affected in future references by 'ifdef' and 'ifndef' properties; any decision as to the object's value that was made due to an 'if' property, or (possibly inherited) 'link' properties, etc. no longer apply once the value has been determined and was "frozen".
- link (HTML only; Never inherited)
- A list of identifiers that define a URL that is used to enclose the text object with an HTML anchor specification. Note that the use of a 'link' property
Predefined Properties for IMAGE Objects
NOTE: IMAGE objects are specifically designed to improve the ease with which images (and image links) are employed on HTML pages. There is nothing that an IMAGE object does that cannot be done with TEXT objects as well. IMAGE objects are, however, more convenient to use as they already know how to assemble an reference with various optional properties.
If you are using WebLord to generate non-HTML output then you will definitely want to avoid IMAGE objects, of course.
IMAGE objects function just like TEXT objects (including all properties defined above) with the single exception that instead of the common 'value' property (which is never inherited), IMAGE objects use an inheritable 'image-url' property that supplies the filename (or URL) of the image. A 'value' property in an IMAGE object is therefore meaningless and is ignored.
- image-url (HTML only)
- A list of identifiers that define the URL of the image. This is given to the the "src" tag in the
specification.
- width and height (HTML only)
- Each a list of identifiers that define the width and height, respectively, of the image. The values are given to the "width" and "height" tags in the
specification.
Acceptable values depend on the HTML specification, of course; in general, they specify the dimensions of the image so that browser software can proceed with the page layout before the entire image has been downloaded and its size become known. As a result pages appear to load much faster, so the use of width and height tags is strongly encouraged. The width and height may also specify a percentage of the browser's display window size. While this is useful to ensure that an image is always scaled to the same relative size, not all browsers support this feature.
Furthermore, some browsers use the width and height tags to scale an image that is actually larger or smaller than the given numbers. Not all browsers support this feature.
- border (HTML only)
- A list of identifiers that define the thickness of the border that is to be placed around the image. Most browsers place this border around the image only when the image is enclosed in an anchor (see 'link' below.)
By setting this value to "0" the border is usually entirely avoided. While this tends to enhance the visual appearance of a page with such image anchors, the missing border also removes the feedback that the user would get from such a border. As a result, image anchors without borders tend to appear like any any image on the page and may never be recognized as "clickable." Use a border with "0" thickness with care!
- align (HTML only)
- A list of identifiers that defines the placement of the image on a page: "top", "middle", or "bottom". "Left", "center", and "right" are also available. The alignment was originally meant to align surrounding text to the "top", "middle" or "bottom" edge of the image. The HTML specification has since been extended to allow "left", "center" and "right" but it is somewhat unclear about combinations of the two (such as how to specify both "left" on the page, and "top" edge of the image.)
- alt (HTML only)
- A list of identifiers that defines the alternate text for the image. This text (or at least as much as will fit) is usually displayed by browsers in the space where an image will be displayed before it has been actually downloaded and made visible. Some browsers are unable to display images or are configured by their users to download image only when explicitly ordered to do so by their users (perhaps to save time because of a slow connection.) In such cases the "alt" tag can provide valuable information about the nature, purpose, or subject of the image.
- hspace (HTML only)
- A list of identifiers that defines the horizontal space (left and right) around the image to separate it from surrounding text.
- vspace (HTML only)
- A list of identifiers that defines the vertical space (above and below) around the image to separate it from surrounding text.
- losrc (HTML only)
- A feature supported by Netscape's Navigator. The image (URL) specified by this option will be loaded first, as it is supposed to be a (much) smaller but lower quality source image. The usual effect is that a low-quality black-and-white version of the image appears first and is then (slowly) filled-in by a (non-interlaced) color version. This can make for a rather nice effect, but only lengthens the total download time.
- target (HTML only)
- Clicking on this link will cause the data to be retrieved to a new window. It is possible to create a simple help system this way by specifying a target window name that is, for example, "my-help-window"; if you use the word "new" then a new window is opened for this link regardless of how many previous windows have been opened; if you use "this" then the current window is used (which is what would happen without the "target" tag.)
Predefined properties for use in IF / IFDEF / IFNDEF / SELECT-CASE properties
The following special purpose properties are defined globally, especially for use in 'if' property to conditionally select either the 'then' or the 'else' value of the the associated object:
- _OS
This has one of the following values (the list will expand in the future):
- AMIGA
- WebLord for the Amiga computer (AmigaOS) (68K & PowerPC)
- UNIX
- WebLord for Unix
- WIN32
- WebLord for 32-bit MS Windows (Win95 or WinNT)
The following may be added in the future but are currently not defined:
- WIN16
- WebLord for 16-bit MS Windows (Win31)
- MSDOS
- WebLord for MS-DOS
- MAC
- WebLord for Macintosh (68K & PowerPC)
The following special purpose properties are defined globally, especially for use in the conditional 'ifdef' and 'ifndef' properties to conditionally suppress a value for the associated object:
- _AMIGA
- Defined (a value of '1') if running on an Amiga
- _UNIX
- Defined (a value of '1') if running on a Unix system
- _WIN32
- Defined (a value of '1') if running on a 32-bit MS Windows (Win95 or WinNT) system
|