As mentioned in the overview, a Tool Template is the stock layout (HTML) used by each Sitemason® Tool. In fact, most tools have multiple pre-defined layouts. A Calendar, for example, will have different layouts depending on how you choose to view the data: a grid layout for a month, a list layout for viewing a week or day, and standard list view just as you would see when viewing a News Tool's listing of articles.
Sitemason comes with a default Tool Template Set ("smDefault") that resides in your website's file space and is available for you to use, replace, or modify to your liking. The Tool Template Set's layout is presented within your Site Template by calling SMTool's printHTML() method. However, one important thing to keep in mind is: you are not forced to use the Tool Template Set to define the layout for any Tool. Instead of calling printHTML() on a Tool, you could simply write your own custom HTML to present the data however you want. The Tool Template Set simply provides a generic layout to get you going. And this layout works well as-is in many cases.
Another way to frame it is: the Sitemason Development Library provides a mechanism to work with the data coming out of Sitemason. Your template is responsible for presenting that data to the end user in the form of HTML, XML, or any other format that you wish. The Tool Template Set provides some stock code to take some of the programming load off of your template.
Modifying the Tool Template Set
The Tool Template Sets reside in your file space, so you are free and encouraged to alter it to your liking! Don't worry - if you mess it up, you can always replace it, so feel free to experiment. When you created your Sitemason® account, the "smDefault" Tool Template Set was copied and placed into your account under "~/[host name]/smToolTemplateSets/smDefault" (the host name is usually "www").
You'll notice that there are a handful of files and folders. Let's examine three important files in the root folder of the Tool Template Set:
- 404.php: This is a layout for the "404: File not Found" page that a visitor would see when attempting to view a page that does not exist. This page is displayed in the case where your Site Template does not have its own 404.php layout.
As far as the layouts go, the meat of the code is found under the "toolType" folder. Each Sitemason Tool requires a different layout, simply due to the fact that each Tool was intended to serve a specific purpose. A Gallery presents photos while a Calendar presents events - those are two fundamentally different tasks with each requiring a different layout. In the "toolType" folder you'll find a number of other folders corresponding to the Sitemason Tools (the Calendar Tool's template set resides in the "calendar" folder, Gallery in "gallery," and so forth). Let's examine the News Tool's Template Set, which resides in the "newsfeed" folder.
The News Tool has two views: the list view, which is a listing of the articles (Items) in that News Tool. Most likely each article has a headline, a thumbnail of the image, a summary, and then a link to view the full article. The full article is contained in the detail view, which displays more of the article's properties. The Tool Template Set therefore has two layouts for the News tool: detail and list, which are housed in the detail.php and list.php files, respectively.
You'll notice that there are a few more files in the newsfeed* folder, not just list.php and detail.php. Each of those files has two supporting files. So, list.php also has list.head.php and list.last.php. Likewise, detail.php has detail.head.php and detail.last.php. This convention applies throughout the Tool Template Set for each Tool's view(s). Let's take the News Tool's detail view for example:
- detail.php: this is the main layout for the detail view of the Sitemason News Tool. It defines the HTML for the content of an article (all of the text and supporting data. Detail.php is loaded by your template making a call to SMTool's printHTML() method (typically $smCurrentTool->printHTML();)
It's common for the "head" and "last" scripts of an individual Tool's view to contain no code - often any supporting code requirements for that view will have been placed in the file pertaining to the entire Tool Template Set (head.php and last.php in the main Tool Template Set's folder). It is also possible for the view's main layout file (detail.php in this case) to simply reference another file, used commonly amongst several layouts. List view layouts are a typical example of this, since multiple tools utilize similar list view layouts, therefore they can all be contained in one centralized file.
*Why is the folder called "newsfeed" when it's for a News Tool? Because the tool used be called "News Feed" and some of the behind-the-scenes terminology is still present.