OPEN SOURCE INTERNET PUBLISHING SOFTWARE FOR NEWSPAPERS, MAGAZINES AND OTHER PERIODICALS

SITE NAVIGATION

GENERAL:

· home
· project goals
· mailing list / IRC
· how to help
· props in action
· links

FOR END USERS:

· introduction to templates and tags
· template tag reference

FOR DEVELOPERS

· accessing CVS
· submitting patches
· sourceforge project page


SourceForge Logo

INTRODUCTION TO PROPS TEMPLATES AND TAGS

Overview

PROPS allows page designers total control over the look and feel of a site. Templates for the front page, section fronts, stories and regular features can be created in standard HTML editing tools such as Dreamweaver, GoLive, BBEdit, etc.

By including special PROPS-Tags in the resulting HTML pages, a page designer indicates where dynamic content is to appear.

Defining a section hierarchy
Using the 'Sections Manager' admin screen, define a hierarchy of sections within your site. You may have just one section (the front page), or potentially dozens. Here's a sample hierarchy:

Creating template directories

Duplicate the sections hierarchy inside the 'templates' directory, using the short name you assigned to each section ('sports', 'dearabby', etc.) This directory structure will contain templates which define the look and feel of your site. Here's an example directory structure that corresponds to the section hierarchy shown above:

        templates/
                |-- national/
                |-- local/
                |-- sports/
                |       `-- baseball/
                |       `-- football/
                |       `-- basketball/
                |       `-- olympics/
                |       `-- highschoolsports/
                |-- lifestyle/
                |       `-- dearabby/
                |       `-- hintsfromheloise/
                `-- opinion/
                        `-- letters/
                        `-- charleyreese/
			
How PROPS determines which template to use

As you may have figured out by now, each section may have its own custom template. When serving requests for pages, PROPS will first look inside that particular section's directory for a template to use. If it doesn't find one there, it will look in the directory above that (i.e. the parent directory), and will continue moving up the hierarchy until it finds an appropriate template file, or until it reaches the default sitewide template stored just under the 'templates' directory.

It's certainly possible to get by with a master story template inside the templates directory, which will be used to serve all stories on the site. It's also possible, but a bit tricky, to create a master section template which will work for all section fronts within the site. Most sites, however, will probably want to give each major section front its own distinct appearance.

So far, so good, right? There's just one more wrinkle...

Each page request is handled by a particular module of the PROPS system. For example, when a story is requested, the request is handled by the "displaystory" module. Likewise, the "displaysection" module handles requests for section fronts.

So, you should use the filename "displaystory.html" for story templates, and "displaysection.html" for section front templates. There's more you'll need to learn about modules if you want to become a PROPS template guru, however if you're just looking to get a basic site up and running, that's all you need to know.

Creating templates using PROPS-Tags

Templates are basically just regular HTML pages. You can create them using whatever tools you're used to working with... Dreamweaver, GoLive, BBEdit, Notepad, chisel and stone, etc. They can be compliant with HTML 3.2 or 4.01, XHTML 1.0 standards, or they can be full of nasty Front Page extensions. The only thing you have to do is add a few special 'PROPS-Tags' to them where you want content to appear.

PROPS-Tags work a lot like HTML tags, so they shouldn't be too hard to pick up. Instead of being enclosed in <> signs, however, they're enclosed in squiggly braces {} so that WYSIWYG editors won't try to eat them. Here's an example PROPS-Tag:

{headline}

The {headline} tag is used within a story template. Wherever it appears, the headline of the story will appear. You can use it anywhere - even inside the TITLE section of the document, like this:

<TITLE>PROPS Gazette - {headline}</TITLE>

Many PROPS-Tags have attributes, like this:

{storylist section="sports"}

(In case you're wondering, this tag will output a list of stories in the sports section)

It's pretty easy to get started with PROPS-Tags. Once you're comfortable with the basics, you'll find that you can do a lot of really cool, powerful things with them.

Standard tag attributes

There are certain attributes which are implemented in most, but not yet all, tags:

altoutput="string"

This specifies the text to be output when the tag doesn't produce any results. Example use: if there are no stories in a given section, you might set altoutput to "There are no stories in this section today." This attribute is only available in tags for which there is a chance no output will be generated. It defaults to an empty string.

prepend="string" append="string"

If the tag generates output, these strings will be added to the beginning and end of that output. If the tag does not generate any output (for example, if there are no stories for a given day) these will not be output. altoutput will be returned instead.

For more information

Please see the online template tag reference on this site for documentation on all tags, annotated with user-submitted notes, tips and tricks.

For developers

PHP developers may add custom tags to PROPS. A sample tag_skeleton.php file containing API documentation is included with the software. These custom tags are part of a more comprehensive module API, which allows the addition not only of custom tags but of admin screens, database tables and more.