Contemplate Assembler

1.0a

2/7/03
By popular demand, the ability to use a combination of hard-coded and passthru arguments in your embed tags has been reinstated. Just include a hard-coded tag, then insert any passthru variables with square brackets, and join the variable and hard-coded arguments with a + symbol. For example, if you include the argument name=Joe in your dynamic URL, then your template can include the tags

<!--#embed args=field,content.html,name[0] -->
<!--#embed args=field,content.html,name[0]+_age -->
<!--#embed args=field,content.html,name[0]+_occupation -->

This functionality was removed in version 4.0 to emphasize the direct relationship between arguments in the dynamic URL and embed tags, but it has proven too useful to do without in templates that include many small pieces of embedded content.

Even more significantly, the PHP version will automatically render any PHP code in your content files or templates. The rendering takes place after the extraction, so code contained in a template will share the same variable scope as code contained in a content file. This behavior is identical to what you can achieve by running the Perl version in the PHP wrapper.

Unfortunately, PHP and ASP error messages that refer to line numbers aren't very useful in this scenario, since the line number is relative to the assembled file, whereas you'll be editing a separate script with different numbering. Therefore, assembler.ini now supports a "show source" setting; if you add "show source: 1" to assembler.ini, the assembler will render the page normally, then append a numbered dump of the page source -- after assembly, but before PHP or ASP parsing. This will allow you to pinpoint the part of your script that the error messages are referring to. To retain the security of your server-side code, however, you can't pass the show source setting to the assembler through the page URL; you can only set it in the ini file.

A new embed tag attribute called "variable" tells Contemplate to put embedded content into a variable rather than displaying it in the assembled page. This allows you to manipulate the content as desired from your scripts, then optionally print it when you're done. The variable that Contemplate creates is available to scripts written in the same language as Contemplate itself. For example, if you're using assembler.php, and you include the tag <!--#embed main variable --> in your template, Contemplate will create a PHP variable called $main that contains the embedded content.

It's now easy to modify your pages on the fly based on the current page or template name -- just include one of these passthru tags in your template to obtain the value: <!--#embed page[0] --> <!--#embed template[0] -->.

A bug was fixed that prevented some complex conditional statements from evaluating accurately.

A bug was fixed that resulted in values passed to assembled pages via the URL string appearing as arrays to server-side scripts. Internally, Contemplate converts page definitions to variables and arrays so that you can easily refer to file and field names in your embed tags. Now, however, Contemplate returns these values to their original formats before displaying the page and rendering any code it contains.

Numerous insignificant adjustments were made to conform the code between the Perl and PHP versions.

1.0b

5/27/03
Assembler.asp will now render ASP code in your content files or templates, in the same way that assembler.php renders PHP code. Please note, however, that assembler.asp only supports ASP code written using the JScript language (not VBScript), and that it will only recognize scripts enclosed in <% %> tags. Incidentally, assembler.cgi will never support this functionality, since it's impossible to embed Perl scripts inside HTML pages.

For the first time, the Assembler will parse any embed tags or conditional tags that you place into your content files. This means, for example, that you can create a header file that contains Contemplate-based logic or embedded content, and embed that header file into your templates. This is called recursive parsing, and it's enabled automatically.

Assembler.ini is now called preferences.ini, and will soon contain settings for other components besides the Assembler.

A new setting in preferences.ini lets you control how assembler determines the host values in your traffic reports. If you set "host lookups for logs" to "off," assembler will rely on the web server to look up your visitors' host names. If you set it to "auto," assembler will perform its own host name lookups if the web server provides the same value for the visitor's host name and IP address. If you set it to "on," assembler will perform its own host name lookups regardless of the web server configuration. The default setting is "auto."

In addition to accessing the current page name and template name with passthru tags (e.g. <!--#embed page[0] -->, <!--#embed template[0] -->), you can also access the page definition (e.g. <!--#embed page_definition[0] -->). This allows your own scripts to do any parsing you like based on any element of the page definition.

Furthermore, you can now access the page[0], template[0], and page_definition[0] variables in Contemplate's conditional tags, so you can add logic to your templates based on these values without using any additional scripting. You can't, however, use these three variables as names for your embed tags; Assembler will show an error stating that page, template, or page_definition is a reserved word.

A new attribute for embed tags, fill_defer, tells the Formulator to parse the tag normally and then show the popup menus for selecting content at the bottom of the page rather than at the spot where the content appears. This is useful when you're embedding content into a script or an HTML tag, and positioning the popup menus there would seriously disrupt the display of the page. The fill_defer option doesn't apply to hard-coded tags, which you can't set in the Formulator, or to passthrough tags, which always appear as an input field at the top of the page, but adding it to these kinds of embed tags won't cause any problems.

Previously, the assembler's pre-rendering feature and all of the flattener's functionality did not work on password-protected sites. Now, these features work in the PHP and ASP versions, on password-protected sites that use HTTP-standard, basic authentication. Making this work in the Perl version is an item on the Known Issues list.

The form parsing routine was revised considerably. You can now surround your input values with single quotes, double quotes, or neither -- although the equals signs in your tag attributes should not have spaces around them. Also, you can now include punctuation and other special characters in form values.

Contemplate's error messages no longer contain any single or double quote marks, so if you place embed tags into variable assignments in your own scripts, and those tags result in Contemplate errors, your scripts won't generate additional errors caused by conflicting quote marks.

Contemplate no longer continues processing tag attributes like strip and replace after it encounters an error. Therefore, the error message text won't be inadvertently processed and possibly rendered unreadable.

A bug in the alpha which allowed "secure" preference settings, like read_files_from, to be overridden through the URL string was fixed. If you include allowed preference overrides in your URL string, however, you will not be able to also refer to those argument values in your embed tags (e.g. the passthru tag <!--#embed show_errors[0] --> won't work if you include &show_errors=1 in the URL).