This is part of a series on how to think like SyntaxCMS.

When last we spoke, we covered the components of SyntaxCMS from a conceptual standpoint. Now let's look at how some of these components interact in the first ways you'll probably want to use them in a real site: publishing.

Publishing always involves site sections in one way or another. The simplest way to think of a bare-bones SyntaxCMS site is just a site full of sections, analogous to pages in a book. One can publish pages to different sections of the book. So if you have a home section, you can publish a page About Us, another one with a way to Contact Us, and maybe something about the Projects you're undertaking. These can have HTML just like a blog post (ahem).

So to do this, you create a site section and then publish it to another site section. The new site section becomes a child, and your original site section, the one you're publishing the new one to becomes a parent. In fact, the relationship is hierarchical , so we can talk very much like a family tree--albeit the family tree of a bunch of asexually-reproducing amoebas, but even amoebas have to come from somewhere.

So another new site section published to the one you just created is a grandchild of the original site section. The original site section (and its parents) are ancestors of the site section you just created. If you go to your site and look from the home page, all these site sections you just created are descendants of the great grand-site-section of them all, the home page.

That sort of site, known colloquially as brochure-ware, is not terribly interesting, and it doesn't take advantage of SyntaxCMS's ability to use different content types and mix them all together. So say you don't want just a boring document library, but you have some text about applying for Jobs at your organization, and you create a site section for it and publish it to your About Us site section. But you also need some sort of form that applicants must sign before their employment application can be processed by HR. The SyntaxCMS way is to create a document object and then use the publish tab to publish it to the Jobs site section. You go to the jobs page, and sure enough, there's your text and a link to and description of your form.

But what if you're participating in a job fair? You can create an event object and publish it to that same page, so it shows up right after your form. Now you have a pretty complete Jobs page with some text, a form, and an event. Three different content types (site section, document, and event) coexisting for no other reason than their content is about jobs, which is how you think about finding them. People don't think "Hey, I'd better look in the Documents section for any jobs form, and the calendar for any jobs-related events, and then the Jobs page for any information about openings," they think "Hey, I should click on the Jobs page and see if there is anything there and how, where, and when to apply."

But say you've been having a hard time finding decent help and you'd like the job fair announcement to be featured more prominently, but it should still be there for the hopeful worthies who have bookmarked your Jobs page, awaiting breathlessly your next opening. In fact, the boss comes in and says he wants it on the home page, ASAP. Well, if you have the default configuration, all you do is publish that same event to the home page site section as well as the Jobs site section.

This should give you a taste of how SyntaxCMS lets you put information where it makes sense, even if it needs to be in multiple places. There's no retyping or copying and pasting, just click a couple of buttons in the admin area. And if, in the future, you have different types of jobs, all of whom need their own page, you can just keep adding new site sections and publishing them to the Jobs site section so users can drill down. Each of them can have their own form, or you can make sure that the original form is there on each of those pages.

But what if the job fair event has an admission form that applicants should fill out before attending? That gets into relationships, which we'll cover in the next part of this series. In fact, we'll find out that publishing is actually a special case of relationships in SyntaxCMS. For now, think about the myriad ways you can present the same information just by publishing content objects to site sections or forming a hierarchy of information by publishing site sections to one another.

This is part of a series on how to think like SyntaxCMS.

Content Types

The fundamental idea of a SyntaxCMS site is the content type. This is analogous to a "class" in object-oriented programming. In the API documentation and the programmer tool, you will see it referred to as a "datatype", but it's easier to communicate the idea of it to non-technical people by using the term "content type". A content type is any uniform type of data you want users to be able to access. Included are such content types as Events, Articles, Documents, and Third Party Links. Likely you have different types of content you'll want to maintain a directory or listing of on your site, such as Member Organizations. In addition, you can think of the parts of an interactive tool as content types. For example, a blog consists of Posts, Comments, and Trackbacks.

If you were programming a site from scratch using Object-Oriented Programming (OOP) you might think in these terms. SyntaxCMS frees you up from the from-scratch programming and database design you would ordinarily have to do, so you can spend your time thinking about how to break your site's content into structured content types. Accordingly, a record you create in the database is a content object. Much of what you do in programming SyntaxCMS is the manipulation of content objects. SyntaxCMS will let you use a web-based interface to define, edit, and delete properties of content types and will generate classes and other code to let you manipulate them in your site.

Site Sections

A special case of a content type is the site section. Site sections are special in that they can be thought of in two ways. First, they act like flat HTML pages in a navigation tree like you may remember from the Bad Old Days. However, they are easier in that they can be created on the fly, there are tools to let SyntaxCMS automagically generate the navigation for them and update it when you rearrange the site sections, and their content can be edited in a form in the administrative tool. Second, they can be thought of as "containers" for arbitrary collections of content objects.

Each content object has the built-in capability to be "published" to a site section. If your organization is holding a conference, you may wish to display events, conference papers, and general information articles in a single place separate from any calendar or document library your site may contain. Simply create a site section with the necessary introductory text and manually select the appropriate content objects and publish them to that section.

But what if you want to separate out some key articles or events for that conference? By default, SyntaxCMS comes with the ability to publish in two ways: normal and "featured". SyntaxCMS gives you the ability to filter how something has been published to a site section and display content accordingly. But what if you have "featured" documents, "key" documents, and run-of-the-mill documents? SyntaxCMS lets you expand the number of publishing types to as many as you like. Just set up a couple of defines and you're set.

Pick Lists

What if you are or are working with a records-management or information architect-type person who wants a way to classify all your content objects across the site, so they can be categorized and searched for? In other words, what if you want a "controlled vocabulary", like a standard list of countries?

The SyntaxCMS way is to create a pick list. Essentially, it's a small database table that contains your vocabulary and lets you put access to it in any appropriate content type. So all your site authors have to do is put in their article content and pick which country or countries it applies to. Then you can either let SyntaxCMS create a browseable list for you, or you can cleverly use it to group or filter lists of content elsewhere on the site.

Modules

The way you construct the complex behaviors and filtering of content types is through modules. Modules can also stand alone, which is good for more complex behavior like the included Calendar module in SyntaxCMS. Each module is made up of capabilities, which can either be called through the API or addressed directly in the browser. Capabilities are just basic PHP scripts which can share a library of classes or functions with the rest of the module.

Templates

Templates are used throughout SyntaxCMS. They are simply PHP files, but they follow a couple of conventions: they are named .tpl, they contain only display logic, and to every extent possible, they do not use print or echo statements to produce HTML, but rather switch context out of PHP whenever possible.

Templates can be global, site section, or module templates.

Global templates are used throughout the CMS and are found in /private/templates/ and in various subdirectories.

A special subdirectory is /private/templates/section/, which contains custom site section templates. To override the default section template (/private/templates/section.tpl), just place a template with the same file path and name in that subdirectory. So if a site section is found at http://www.syntaxcms.org/section/test/my_section/, a custom template for it would be found at /private/templates/section/test/my_section.tpl.

Module templates are found in the templates subdirectory of each module (/private/modules/{module name}/templates/). For most modules, there is list.tpl, listitem.tpl, listitem-featured.tpl, and detail.tpl. list.tpl controls how a list of items will be displayed, listitem.tpl controls how each individual list entry will be displayed, listitem-featured.tpl controls how featured items will be displayed, and detail.tpl controls how a detailed view of a content object is displayed. SyntaxCMS will automatically look for these before using the default templates (in the general module), so their naming is important.

Admin Application

This is the application that site administrators will use to create and update content.

DBasis (Developer Administration)

This is the application developers use to create and update content types, set CMS-wide preferences, and view and edit the complete content of a site.

Learning how to "think like" a system is usually as or more difficult than installing it. As such, a new series, "Thinking Like SyntaxCMS," will be a guide to thinking about how to use SyntaxCMS 1.x for a project, how to go about altering it, and how to create the functionality you need for a new project. It will not discuss the technicalities of installing the system. However, it is written for the web programmer or webmaster who has to take the plan you have for a website, decide if SyntaxCMS is the right tool for the job, and then, if you’ve decided it is, planning and implementing your site with it. It will assume a certain amount of basic programming knowledge. The first installment, in the next post, will describe the components of SyntaxCMS.

There are additional sections, articles, and links to documentation in the developers' support area of the SyntaxCMS.org site. Among the new goodies:

• An overview of the architecture of SyntaxCMS.
• A tutorial on creating modules.
• Some tips on debugging while developing SytnaxCMS sites.
• Documentation for the ListWidget class.

When trying to install SyntaxCMS on a new Debian server, I ran into a weird problem. Everything worked except SyntaxCMS's file-handling script. It works by taking a request, such as:

/files/123_file_mydoc.doc

and using a mod_rewrite rule to turn it into:

files.php?file=123_file_mydoc.doc.

files.php then checks to see if the current user (or anybody if the user isn't logged in) has permission to read that file, and then passes it through with the proper MIME types.

Well, it was churning and giving me a zero-length file. So I commented out that rewrite rule to verify that the rewrite was being performed. I expected a 404 error once I commented out the rule. However, it worked the same way!

So I commented out the other rules to make sure they were working properly. Sure enough, 404 errors were generated for most pages. So I went ahead and moved the entire .htaccess file out of the public root.

It still rewrote the /files/123_file_mydoc.doc request!

After much floundering and checking, Oscar and I figured out that mod_negotiation was on and that MultiViews was set.

Here's the relevant quote from the mod_negotiation docs:

A MultiViews search (enabled by the MultiViews Options), where the server does an implicit filename pattern match, and choose from amongst the results.

So it was taking any request in the form of /foo/whatever and mapping it to any file named foo.*, no matter the file extension. So foo.php would work, as would foo.txt.

The fix was to disable the MultiViews directive from Apache's configuration file and restart Apache--bingo! Everything worked.

So beware MultiViews when using fancy rewrite rules in your applications, as well as when you install SyntaxCMS.

There has been some bruhaha over Google Web Accelerator and web applications. Google Web Accelerator works by "prefetching" pages in the background so clicking on a link results in a faster page load. Unfortunately, it blindly follows any link on the page, regardless of whether you've put a JavaScript confirmation on it. The practical upshot of this is that links to delete items may be followed, leading to simply viewing a list of items causing them to disappear. Fortunately, Google Web Accelerator uses the Mozilla Foundation's X-moz: prefetch HTTP header. So it can be detected and stopped with the following two lines in an .htaccess file:

RewriteCond %{X-moz} ^prefetch
RewriteRule ^.* - [F]

We have implemented this fix for the administration application in SyntaxCMS, so you can grab the latest copy of /syntax-cms/src/public/admin/.htaccess from the SyntaxCMS CVS repository on Tigris or, if you've modified that file, simply put the above two lines below RewriteEngine On in /public/admin/.htaccess on your installation.