Introduction

 Explanation

 Comparison

 Demonstration

 Documentation

   Quick start
   Terminology
   Site organization
   Templates
   Content files
   Page definitions
   Preferences
   Other components
   Tips and tricks
   Release notes
   Known issues

 Downloads

 Community

Preferences

The Contemplate folder contains a preferences.ini file that lets you change some of its behavior on a site-wide basis. To set a preference, just list the name of the preference on a line, followed by a colon and then a space, followed by the value you wish to set the preference to. If you don't include a preference name in your preferences.ini file, Contemplate will use the default value, which you can look up in the list below. For an example, you can view the preferences.ini file for this site.

NOTE: Before version 1.0.4, the default location for this file was the contemplate directory. If you've upgraded to version 1.0.4 or newer and Contemplate isn't reading your preference settings, move your preferences file from contemplate to contemplate/data.

Setting preferences on the fly

When you view a Contemplate page in your browser, you can change most of these preferences for the current view only by passing the preference name (with spaces changed to underscores) and value into the Contemplate script through the query string. For example, if the show errors preference is set to 0 in your preferences.ini file, but you want to temporarily see the errors on a particular page, you can add &show_errors=1 to the URL you're viewing. Contemplate won't let you set a few preferences in this way for security purposes; those preferences are noted in the list below.

Assembler preferences

field marker

Default: ##
Possible: any string
The field marker is a special string that helps Contemplate locate the names of content fields. You should use a string that won't appear anywhere in your site content. The default field marker will usually work, but if you need to use a different string, you can set it here.

log site traffic

Default: 0
Possible: 1 or 0
If you set this preference to 1, Contemplate will log every page request to a data file that you can view through the Reporter component. You'll also need to set the contemplate/data/reporter folder to be world writable, otherwise Contemplate will write a comment at the bottom of each page noting that the data file is unavailable.

host lookups for logs

Default: auto
Possible: on, off, auto
When Contemplate logs site traffic, it can log the hostname of the visitor even if hostname lookups are turned off at the server level by performing its own hostname lookup. If you set this to on, Contemplate will always perform a lookup and therefore always log a hostname. If you set this to off, Contemplate will never perform a lookup and therefore only log a hostname if lookups are turned on at the server level. If you set this to auto, Contemplate will perform a lookup only if lookups are turned off at the server level and therefore always log a hostname. The auto setting is preferable because it provides the most useful logs reports without duplicating the hostname lookups.

show errors

Default: 1
Possible: 1 or 0
When Contemplate assembles pages, it will display errors if it encounters an invalid page definition or it can't find the files or fields you specify. If you set this to 1, it will display these errors on the assembled page so the visitor can see them. If you set this to 0, it will surround these errors in HTML comment tags so the visitor has to view the page source to see them. If the log site traffic preferences is set to 1, Contemplate will log these errors in the data file regardless of this setting.

pre-render files

Default: nothing
Possible: any file extensions
Example: cgi
Normally, Contemplate reads all content files and templates through the filesystem, then assembles the final page. However, if your content files or templates contain server-side scripting, you might want those scripts to execute before Contemplate begins the assembly. If you list file extensions here, with no periods, delimited by commas, Contemplate will read any files with those extensions through the web server rather than through the filesystem, so the scripts will execute first. Then Contemplate will perform its assembly based on the output of those scripts.

read page definitions from

Default: data/pages.txt
Possible: any path
By default, Contemplate looks for page definitions in this file, but you can move or rename your page definitions file if you update this preference. The default path for this setting is the contemplate/data directory, but you can store your definitions file elsewhere if you use a setting like ../other/pages.txt.

NOTE: Before version 1.0.4, the default location for this file was the contemplate directory. If you've upgraded to version 1.0.4 or newer and Contemplate can't find your page definitions, change this value from pages.txt to data/pages.txt.

read files from

Default: nothing
Possible: any paths
Example: ../scripts/, ../other/
No override
As a security precaution, Contemplate can only read files in the top-level content and templates folders as well as its own folder. However, you might want to organize your site differently and store your files in different folders. If you list folder paths here, relative to the contemplate folder, with a trailing slash, delimited by commas, Contemplate will be able to read any files in those folders as well.

read files recursively

Default: 1
Possible: 1 or 0
No override
By default, Contemplate will automatically 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, sometimes you may want to ignore subfolders, especially to speed up page display or avoid problems with irrelevant file types in the Formulator. If so, you can include this setting in your preferences file and set it to 0. You can still direct Contemplate to read from specific subfolders by adding those subfolders to your read files from setting.

require authentication to read files from

Default: nothing
Possible: any paths
Example: ../staff/, ../clients/
No override
Adding a password-protected area to your site can be difficult since Contemplate pages are comprised of elements from several different folders. You can't simply password-protect the Assembler file because that would require a login for all your pages; and you can't password-protect individual content folders, because the Assembler reads content through the filesystem, bypassing any password protection. This option lets Contemplate work in conjunction with the HTTP Basic Authentication mechanism on your web server. If you list folder paths here, the Assembler will check to see if users have authenticated before loading content files or templates that are stored in those paths. The Assembler won't actually check to see that the username or password is correct; it relies on the web server to do that, and assumes that if a username is present among the server's environment variables, the user authenticated correctly. If a username is not present when a user tries to view an affected page, the Assembler will display an error message. NOTE: This option has not been tested in the ASP version and is not included in the Perl version.

prevent page caching

Default: 0
Possible: 1 or 0
If you set this preference to 1, Contemplate will add Pragma, Cache-control, and Expires headers to every page it assembles, which will prevent most web browsers from caching those pages.

show expanded URLs

Default: 0
Possible: 1 or 0
If you browse to a Contemplate page using a URL of the format assembler.php?page=page_name, and this preference is set to 1, Contemplate will reload the page with the full URL as shown in the page definitions file. This can be useful for troubleshooting but is not recommended as a permanent setting for your site since it causes every page to load twice.

split page names on

Default: nothing
Possible: any character or string
If you set a value for this preference and then use the special page variable in your embed tags, Contemplate will split the page name on this value and let you access elements of the resultant array by providing an index to the page variable (e.g., page[1]). You can still access the entire page name by leaving out the index to the page variable (e.g., page[]).

external link target

Default: nothing
Possible: any string
Example: "_blank"
You can ensure that every link on your website that connects to a separate site opens in a new window by setting an external link target. When Contemplate assembles a page, it will include a target attribute, with the value set here, in every anchor tag whose href contains an absolute URL to an http page. This setting does not affect https or ftp URLs. If you want Contemplate to put quotes around the value, include the quotes in your preference setting.

line ending for assembled files

Default: \n
Possible: any string
You can control the line endings that Contemplate uses when assembling files by setting this preference. For example, if you're flattening a site and want to easily read the source of the flattened files on a Windows computer, you can set this preference to \r\n.

show source

Default: 0
Possible: 1 or 0
If you're adding server-side scripting to your templates or content files and those scripts generate errors, the line numbers in your error messages may be inaccurate because they refer to the line number of the error in the context of the assembled page rather than in the context of the actual script file you're editing. To help locate errors from one context to the other, you can set this preference to 1 (including setting its value on the fly by passing it through the URL string). In that case, Contemplate will display the assembled page, and at the bottom will also display the complete source code of the assembled page (including your scripts before they execute), along with line numbers for the assembled page. Those line numbers should correspond to the line numbers specified in your error messages, which will help you locate the problematic line of code.

show source to IP address

Default: nothing
Possible: any addresses
Example: 216.08.59.13, 10.0.1.12
No override
In order to keep your source code private, Contemplate will only respect the show source setting for requests that come from IP addresses that you specify. You can list IP addresses here, delimited by commas, to enable the show source preference for requests coming from those addresses. Contemplate currently doesn't support any wild card matching of partial addresses or subnets; it only recognizes single, complete addresses.

Reporter preferences

top n

Default: 5
Possible: any integer
By default, the Reporter shows initial lists of the top 5 items in each category, but you can change this value to show any number of items in the initial lists. In any case, Reporter always provides a link to see the complete lists.

graph image

Default: ../graphics/logo.jpg
Possible: any string
If you're using the real-time traffic view at reporter/realtime.swf, you can specify any image file on your website to display behind the timeline. Contemplate will fade the logo into the background of the window so your traffic timeline is still legible. The only supported image format is non-progressive JPEG, and the path to the image is relative to the contemplate directory.

graph color

Default: 0000FF
Possible: any string
If you're specifying your own logo for display behind the real-time traffic view, you can also use this setting to make text links and buttons color-coordinate with your logo. Just enter any RGB hex value here.

real-time update interval

Default: 10
Possible: any integer
If you're using the real-time display feature, you can change the frequency with which the Flash file reads the current traffic data file to count new page views. This value specifies the number of seconds between updates.

maximum column width

Default: 64
Possible: any integer
When the Reporter displays referrer data and other long values, it will crop those values to a reasonable length so that the traffic reports still display well in your browser window. However, depending on your preferred window size, you can adjust this number to make the Reporter crop the values to longer or shorter sizes, optimizing your display.

display monthly report on one big page

Default: 0
Possible: 0, 1
By default, the Reporter displays the top n lists on one page, and provides links to view the complete lists on separate pages. However, if you enable this value, the Reporter will display the top n lists as well as the complete lists for each category on one page. It presents the same links, but in this case they simply jump to different portions of the page. This option results in a much slower initial page load, but faster navigation between sections once the page is loaded.

show inspector rollover

Default: 1
Possible: 0, 1
Each entry in your traffic reports includes a small magnifying glass icon that you can use to open an "inspector" view, providing a different cross-section of your traffic reports. By default, this icon uses a standard HTML rollover effect. However, the additional code required for the rollover effect may cause a noticeable increase in page load time with longer reports, and you can optionally skip the rollover effect and speed up the page loading by disabling this option.

exclude traffic from hosts

Default: googlebot, msnbot
Possible: any hostname or portion of a hostname
You can exclude selected site traffic from your traffic reports with this option. For example, you might wish to exclude traffic from your own company to get a more accurate picture of your site's public users. You might also wish to exclude traffic from automated search engine "bots." To exclude traffic from these hosts, set this value to a comma-delimited list of strings that identify the hosts you wish to exclude. The Reporter still logs traffic from these hosts, it just doesn't include them in the report. This means you can change your preference setting at any time without losing any traffic data.

use cookies to track visitors

Default: 0
Possible: 0, 1
Normally, the Reporter tracks individual page views but does not try to link consecutive page views together into a "visit." With this option enabled, the Assembler will assign each website visitor a randomly-generated visitor ID and save it in a cookie on the visitor's computer. It will then include the visitor ID in each page view record so the Reporter can link them together. When the option is enabled, the Reporter's month menu page will display the number of visitors in the month, the number of visits and average visits per visitor, and the average visit duration, and the monthly report pages will display the visitor IDs and the entry and exit pages.

minutes until visit expires

Default: 30
Possible: any integer
With the "use cookies to track visitors" option enabled, the Reporter will consider a group of page views by the same visitor with no more than 30 minutes between any consecutive page views as a "visit." To change the 30-minute limit to a different value, you can use this option. Contemplate determines visits when you view a report, not when it logs the page view, so you can change this value at any time and view the effects on your reports retroactively.