Preferences

The config folder contains a constants.php file that lets you change some of its behavior on a site-wide basis.

NOTE: Before version 2.0, preferences were stored in a text file located at data/preferences.ini. If you've upgraded to version 2.0 or newer, you will need to copy your preferences into the new config/constants.php file.

Setting preferences on the fly

When you view a Contemplate page in your browser, you can a few of these preferences for the current view only by passing the preference name (changed to lower case) and value into the Contemplate script through the query string. For example, if the SHOW_ERRORS preference is set to 0 in your constants.php 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. Only a few preferences can be set in this way because the others either aren't likely to be used, and would create extra processing overhead, or would create security issues. Those that can 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.

read page definitions from

Default: config/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/config directory, but you can store your definitions file elsewhere if you use a setting like ../other/pages.txt.

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

read files from

Default: ../contemplate/config/,../content/,../templates/
Possible: any paths
As a security precaution, Contemplate can only read files from the folders listed here. However, you might want to organize your site differently and store your files in different folders. You can list additional folder paths here, relative to the contemplate folder, with a trailing slash, delimited by commas.

NOTE: Before version 2.0, Contemplate added the three default folders even if they weren't included in your preferences.ini file. In version 2.0 and above, you must list them in the new constants.php file that replaces preferences.ini.

read files recursively

Default: 1
Possible: true or false
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/
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: As of Contemplate version 2.0, this option is known to be broken. Please contact us if you would like to use this functionality and we will prioritize fixing it.

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

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.

search results preview length

Default: 128
Possible: any integer
If you use the search embed type, this value will determine how many characters of each matching page will be displayed in the search results.

prevent page caching

Default: 0
Possible: true or false
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.

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. Most likely, you would want to set this to match your server platform: \n for Linux, \r\n for Windows or \r for Macintosh.

log site traffic

Default: 0
Possible: true or false
Can be overridden
If you set this preference to 1, Contemplate will log every page request to a database table that you can view with the Reporter script. If Contemplate is not able to connect to this database, it will write a comment at the bottom of each page noting the error.

use cookies to track visitors

Default: 0
Possible: true or false
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.

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 expanded URLs

Default: 0
Possible: true or false
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.

show source

Default: 0
Possible: true or false
Can be overridden
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
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.

show errors

Default: 1
Possible: true or false
Can be overridden
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. You can override this setting on a tag-by-tag basis by including the show_errors or hide_errors attribute in your tag.

error box style

Default: border: 2px solid black; padding: 8px; color: #000000; background: #FFFFFF;
Possible: any CSS rule
When Contemplate displays an error, it wraps it in an HTML DIV tag with this text inserted into its style attribute. You can customize the appearance of the error boxes by changing this text.

error page 404

Default: nothing
Possible: a page name defined in pages.txt, or the URL of a static error page
If Contemplate receives a request for a page name that is not included in pages.txt, it will show its own error message by default. But it might be more natural to show a 404 error in this case. If you build a 404 page using Contemplate, you can specify its page name here. Alternatively, if your server already has a static 404 page set up, you can specify its URL here. However, building your own 404 page is better because the redirect to a static page will change the URL displayed in the web browser and make it harder for a user to find the desired page.

content database address
content database username
content database password
content database name

Default: nothing
Possible: text strings
If you want to use the database embed type, you can specify your database connection information here. Contemplate currently only supports MySQL databases.

content database tables

Default: nothing
Possible: any table names
As a security precaution, Contemplate can only read content from the tables listed here, delimited by commas. This is analogous to the "read files from" setting for content stored in HTML or XML files.

content database strip slashes

Default: false
Possible: true or false
This setting determines whether Contemplate runs the PHP stripslashes function on content it retrieves from your database. In most cases this is not needed, but if your content appears with unwanted backslash characters, you can turn on this setting to remove them.

Reporter preferences

password

Default: nothing
Possible: any string
By default, anyone can view your traffic reports. If you specify a password here, a simple login field will appear, requiring the user to enter the password before viewing the reports.

one big page

Default: false
Possible: true or false
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.

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.

maximum label length

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.

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.

graph image

Default: nothing
Possible: a path to an image file
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.

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.

exclude traffic from hosts

Default: bot,crawl,spider
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 robots. To exclude this traffic, set this value to a comma-delimited list of strings matching the hosts from which the bots originate. You can list complete hostnames like crawl.yahoo.net or portions of hostnames like "spider" or "bot." 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.

include error pages in totals

Default: true
Possible: true or false
If you configure your website to use a Contemplate page as an error page (e.g., a 404 page), then Contemplate will log all of those errors in its traffic reports. By default, it will then count those error pages in its report totals. You can disable this option to exclude these pages from the totals (they will still be visible in the HTTP Errors and Assembler Errors sections). Note that before Contemplate 2.0, the default behavior was to not include error pages in totals, so if you import prior data to Contemplate 2.0, you will see your totals change unless you disable this option.

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.

reporter database address
reporter database username
reporter database password
reporter database name
reporter database table

Default: nothing
Possible: text strings
In order to use the Reporter, you will need to install a table into any database using the schema provided in the xxx, then specify your database connection information here. Contemplate currently only supports MySQL databases.