Page definitions

Once you've created content files and templates, you'll need a page definition to pull them together. You can use page definitions in two ways: either as the query string of a URL, or as the definition in a page definitions file. The latter is preferred since it results in cleaner URLs, provides a way to change the composition of a page globally, and allows you to use navigation tags and the Flattener if you need to.

To use the query string method, you would simply browse to a URL like this one:

http://www.yoursite.com/contemplate/assembler.php?template=default.html&main=field,main.html,home

To use a page definitions file, you would add this line to config/pages.txt (or another file specified in your config/constants.php file):

home: template=default.html&main=field,main.html,home

Then, you could browse to this simpler URL:

http://www.yoursite.com/contemplate/assembler.php?page=home

Each line of your page definitions file should consist of the page name, followed by a colon and then a space, followed by the template and other arguments needed to assemble your page. In addition, you can include comments and other text on their own lines to organize your page definitions file. And you can use extra line breaks to group your pages, which is especially useful in conjunction with navigation tags.

Content types

The first argument of each page definition should be the name of a template file, including the extension, and including the relative path to the file if it's not stored in the top-level templates folder. Additional arguments can have a different number of comma-delimited values, depending on the type of content they refer to:

file

main=file,home.html
The simplest way to embed content into a template is to embed an entire file. In this case, you can use a page argument with two elements: the keyword "file" and the name of the file, including the extension, and including the relative path to the file if it's not stored in the top-level content folder

field

main=field,main.html,home
The most common type of content is a field within an HTML or XML content file. To access one of these pieces of content, you can use a page argument with three elements: the keyword "field," the name of the content file, and the name of the field. If you leave out the last element, Contemplate will randomly select a field each time the page loads.

database

main=database,table,column,key_column, key_value
If you want to store your content in a database instead of a flat file, you can use the database embed type to display the content. This embed type includes five elements: the keyword "database," the name of the database table (this can be prepended with the name of the database if needed), the name of the column where your content is stored, the name of the column you're using as a key to select a row, and the value of the key. For example, this embed tag…

<!--#embed args=database,content,text,page,home -->

…is the equivalent of this SQL query :

SELECT `text` FROM `content` WHERE page='home'

If you leave out the last two elements, Contemplate will randomly select a field each time the page loads. In order to use this tag, you need to specify your database connection details in the constants.php file.

form

data=form,employee_data.html,joe,birth_date
If you want to access small pieces of content, such as an employee's birth date, and can't create a more complex database back-end, an alternative is to create an HTML form inside of a content field, then set the names and values of the form elements. In this case, you can use a page argument with four elements: the keyword "form," the name of the content file, the name of the field, and the name of the form element. Contemplate will automatically find the values of text, textarea, radio, checkbox, and select elements. When checkbox or select elements contain multiple values, Contemplate displays a comma-delimited list of values.

search

main=search
Contemplate includes a built-in site search feature, which you can try in the left sidebar of this site. To use it on your site, you can set the embed type of any tag to "search," then include an argument "search_string" in your page's query string. Contemplate will search all of your content files and display a ranked list of results where the embed tag appears. For example, if a template called "default.html" contains an embed tag called "main" and you make a page definition "search_results: template=default.html&main=search," then the address "contemplate/assembler.php?page=search_results&search_string=guitar" will generate a listing of all the pages in your site containing the word "guitar." You can control the appearance of the search results by adding CSS styles named contemplate_search_results_heading, contemplate_search_results_preview and contemplate_search_results_link to your site.

passthru

colors=#000000,#FF0000,#999999
Sometimes you just need to pass data directly from the page definition to the template, and don't need a content file at all. In this case, you can include additional arguments in your page definition with as many elements as you need, and you can then access those elements in your template with tags like <!--#embed colors[0] -->, <!--#embed colors[1] -->, and so on.

URL rewriting

If you're using a page definitions file and the simpler URL format, you can make your URLs even cleaner by using your the URL rewriting functionality built into some web servers. For example, this site uses a RewriteRule in an Apache .htaccess file to convert URLs like pages/home.html to contemplate/assembler.php?page=home. As a result, the site appears to the unsuspecting visitor to be a simple collection of static HTML pages; more importantly, it's completely compatible with search engines and other scripts that might ignore query strings in URLs.

Here's the rewrite rule this site uses:

RewriteRule ^pages/(.+).html$ /software/contemplate/contemplate/assembler.php?page=$1&%{QUERY_STRING}

Note that this rule passes any additional query variables through to the real URL. This allows you to build web applications that pass data unrelated to Contemplate into your pages, or even to override your Contemplate page definition on a per-request basis.

Other arguments

If you're using Contemplate to build a web application, you can include other arguments in your query strings regardless of which method you use. For example, you might use any of these URL formats...

http://www.yoursite.com/contemplate/assembler.php?template=default.html&main=field,main.html,home&user=1
http://www.yoursite.com/contemplate/assembler.php?page=home&user=1
http://www.yoursite.com/pages/home.html?user=1

...but in each case, the user argument will be available to any scripts contained in the assembled page.