Quick start
Terminology
Site organization
Templates
Content files
Page definitions
Preferences
Other components
Tips and tricks
Release notes
Known issues
|
Latest release Contemplate 1.2.3 |
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 contemplate/data/pages.txt (or another file specified in your contemplate/data/preferences.ini 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.
random
sidebar=random,tidbits.html
If you want to embed one field from an HTML or XML content file,
but want to embed a different field each time the page loads,
you can use a page argument with two elements: the keyword "random"
and the name of the content 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, it might be more convenient 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.
menu
nav=menu,main.html,main,text
Imagine being able to rearrange, add to, or update a heirarchical,
animated menu by simply pushing links around in an HTML editor.
If you build content-driven menus in Flash, DHTML, or another
technology, Contemplate can help you bridge the gap between data
formatted for the menu software and data formatted for a human
to update. You can set up your menu data in simple bulleted lists
in your content file, like this:
Then you can place any of these embed tags into JavaScript code in your template:
<script language=JavaScript>
menu_text = <!--#embed args=menu,main.html,menu,text -->;
menu_links = <!--#embed args=menu,main.html,menu,links -->;
menu_images = <!--#embed args=menu,main.html,menu,images -->;
menu_images_width = <!--#embed args=menu,main.html,menu,images_width -->;
menu_images_height = <!--#embed args=menu,main.html,menu,images_height -->;
menu_images_alt = <!--#embed args=menu,main.html,menu,images_alt -->;
menu_active = <!--#embed args=menu,main.html,menu,active -->;
</script>
<noscript>
<!--#embed args=menu,main.html,menu,HTML -->
</noscript>
And Contemplate will convert the menu HTML to JavaScript arrays:
<script language=JavaScript>
menu_text = ['Home', ['Products', 'Betaboard', 'Macroscope'], ['Contact', 'Remote', 'In person'], 'Site map'];
menu_links = ['../contemplate/assembler.php?page=home', ['../contemplate/assembler.php?page=products', '../contemplate/assembler.php?page=products_betaboard', '../contemplate/assembler.php?page=products_macroscope'], ['../contemplate/assembler.php?page=contact', '../contemplate/assembler.php?page=contact_remote', '../contemplate/assembler.php?page=contact_in_person'], '../contemplate/assembler.php?page=site_map'];
menu_images = ['', ['', '', ''], ['', '', ''], ''];
menu_images_width = ['', ['', '', ''], ['', '', ''], ''];
menu_images_height = ['', ['', '', ''], ['', '', ''], ''];
menu_images_alt = ['', ['', '', ''], ['', '', ''], ''];
menu_active = [0,1];
</script>
<noscript>
<ul class="body">
<li><a href="../contemplate/assembler.php?page=home">Home</a></li>
<li><a href="../contemplate/assembler.php?page=products">Products</a>
<ul>
<li><a href="../contemplate/assembler.php?page=products_betaboard">Betaboard</a></li>
<li><a href="../contemplate/assembler.php?page=products_macroscope">Macroscope</a></li>
</ul>
</li>
<li><a href="../contemplate/assembler.php?page=contact">Contact</a>
<ul>
<li><a href="../contemplate/assembler.php?page=contact_remote">Remote</a></li>
<li><a href="../contemplate/assembler.php?page=contact_in_person">In person</a></li>
</ul>
</li>
<li><a href="../contemplate/assembler.php?page=site_map">Site map</a></li>
</ul>
</noscript>
Menu arguments contain four elements: the keyword "menu," the name of the content file that contains your bulleted list, the name of the field that contains your bulleted list, and the type of data you wish to extract from the list: "text," "links," "images," "images_width," "images_height," or "images_alt" (the value of the HTML alt tag for each image). You can also use an embed tag with a fourth argument of "active" to embed an array indicating the position in the menu that corresponds to the current page. And we recommend using an embed tag with a fourth argument of "HTML" to place the menu HTML directly into a <noscript> tag, to allow search engines and other software to navigate your site.
Contemplate supports heirarchical menus with any number of levels. The only exception is that the active function in the Perl version of Contemplate only finds the menu position down to the second level.
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."
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 assembled/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 ^assembled/(.+).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&userID=1
http://www.yoursite.com/contemplate/assembler.php?page=home&userID=1
http://www.yoursite.com/assembled/home.html?userID=1
...but in each case, the userID argument will be available to any scripts contained in the assembled page.