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).

1.0

8/29/03
All Contemplate scripts now look for different environment variables depending on what server platform they're running from. This resolves a particular problem when running PHP as a CGI module, but should make the scripts more compatible in general.

In the last release, Assembler.cgi was not processing replace attributes. This functionality is now restored.

The Assembler now correctly reads XML content fields whose names are not surrounded by quote marks.

The Assembler now parses large content files faster, especially the ASP version, which was parsing large files quite slowly in the previous release.

The Assembler now warns you in more situations if you use an embed tag name that conflicts with one of its internal variable names. Removing the possibility of such conflicts has been added to the known issues list.

The get_setting function now contains an extra line to ensure that Contemplate will evaluate a setting of "0" in the preferences file as false in every language. The ASP version was evaluating "0" as true, resulting in some preference settings not taking effect.

1.0.1

10/30/03
The Assembler now takes a new preference called "show source to IP address," and the previous "show source" preference works differently. Now, you can show the page source on the fly by adding show_source=1 to your page URL, but you must first list your local IP address in the "show source to IP address" setting. This makes it easy for site developers to see their own page source at any time, while making it impossible for other site visitors to ever see the source.

You can now list multiple page definitions files, separated by commas, in the "read page definitions from" setting of preferences.ini, and the Assembler will search through each definitions file you list until it finds the page you've specified. Please note that this functionality is only a partial step toward future support for multiple page definitions files. It is not yet mentioned in the Contemplate documentation and is not yet supported in the other Contemplate components.

You no longer need to specify the directory location of your page definitions file if you store it in the contemplate directory. For example, your setting for "read page definitions from" in preferences.ini might be simply "pages.txt." You can still store your definitions file elsewhere by using a setting like "../other/pages.txt."

If you're using Apache's mod_rewrite or other software to rewrite dynamic URLs, you no longer need to use "assembled" as the string that triggers the rewrite. If you wish to use a different string, you can open each of the server-side scripts included with your version of Contemplate, look for the $URL_rewriting_flag variable definition, and change it in the script. (This setting is not available in the preferences file because the scripts need it in order to read the preferences file.)

Previously, the Assembler returned script errors when it tried adding an external link target to an anchor tag that contained a server-side script embedded into it. Now the Assembler correctly parses those anchor tags.

The $allow_partial argument in the get_setting() function in assembler.cgi was misnumbered, causing some preference settings to behave incorrectly. This is now fixed.

1.0.2

11/21/03
By default, Contemplate will read files in all the subfolders of the content and templates folders and the additional folders you specify in the read files from setting. However, you can now disable this recursiveness by adding a "read files recursively" setting to your preferences file and setting it to 0.

The $URL_rewrite_flag variable is now properly declared as a global in PHP functions. This problem primarily affected the Flattener and only affected the PHP version of Contemplate.

The navigation embed types no longer generate errors when the name of the current page also appeared in the page definitions file as a part of the definition of a different page.

1.0.3

05/18/04
Assembler.asp now supports embedded ASP scripts written in either JScript or VBScript -- it formerly only supported scripts written in JScript. However, it will now interpret scripts enclosed within <% %> as VBScript, rather than as JScript as before. If you want to embed JScript code, you'll have to enclose it in <script language="JScript" runat="Server"></script> tags.

When using the "variable" tag attribute, assembler.asp used to create variables whose names started with the $ symbol, which were accessible from JScript code. Now it creates variables whose names do not start with that symbol, so the variables are accessible from within both JScript and VBScript code. For example, the tag <!--#embed skin variable --> creates a variable called $skin in assembler.php and assembler.cgi, and a variable called skin in assembler.asp.

Assembler.asp no longer stops with a script error when you create a conditional tag that contains a reference to an argument that does not appear in the page definition. The conditional will simply evaluate false and the Assembler will continue processing your page.

Assembler.asp now correctly generates error messages with &quot; entities rather than actual double-quote symbols, so that content embedded into variable assignments in your scripts will not cause string termination errors in your script if the embed fails.

The built-in search function no longer returns error messages or oddly formatted content in assembler.asp. The ASP version of the search function now behaves like the PHP and Perl versions.

You can now access the special passthrough variables page[0], template[0], and page_definition[0] in combo tags.

You can now access the values of navigation and environment tags in conditional tags. For example, the following code prints a message if the current page is the last in a group in your page definitions file:

<!--#if (page[0] == nav_last) -->
Sorry, there are no more pages after this one!
<!--#end if -->

Assembler.php was logging HTTP errors into the reporter/data/YYYY-MM.txt files rather than the reporter/data/YYYY-MM-errors.txt files. Now it will log HTTP errors in the correct file, provided you are running PHP 4.1.0 or newer.

All versions of the Assembler no longer display the wrong XML field if a preceding field in an XML file had a name that began with the name of the desired field.

Assembler.php and flattener.php now come with a few lines commented out to enable compatibility with open_basedir restrictions on some servers. The commented-out lines let the scripts write data to files with relative paths, which usually works and avoids open_basedir problems. To use absolute paths, if you receive errors writing data, you can search the scripts for "open_basedir" and restore the indicated lines.