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.