Skip to content
Sitemason - Build on Us

Folders, Tools, and Items

There are three components used by Sitemason® to organize the data used by your website: Folders, Tools, and Items.  This section will discuss these components in more detail.


Simple websites with only a handful of pages may present all of those pages in-line (where each page is at the same level).  However, for larger websites, a hierarchical structure becomes inevitable, with subsections of the site containing multiple pages of related content.

Unlike some content management systems, Sitemason was built to support hierarchical sites elegantly - just like your workstation - through the use of Folders.

A Folder is a collection of Tools and possibly other Folders and is the highest level of organization within Sitemason.  Your website itself is a Folder (also known as the "root folder," answering to "") and contains a number of Sitemason Tools inside.  If your website has multiple levels, for example, an "About Us" section that has several pages inside, then "About Us" would be another Folder containing a subset of Tools.


A Tool is specialized module of Sitemason designed to store and present data in a manner that serves commonly-used features of websites.  The current Tool offerings are: Page, News, Gallery, Calendar, Form, and Store.  Based on the names of these Tools, you can easily surmise the purpose of each one.  A Page is simply a block of text, graphics, media files, and other content.  A News Tool is a group of articles, each with their own text, graphics, and media.  A Gallery is a group of images, a Calendar a group of events, and so forth.

Website Pages vs. Tools

A page of your website is what you would expect it to be: it's a page intended for a user to visit.  Each page of your website is constructed using one or more Tools.  And though each Tool has a unique URL, some Tools may be intended to serve as the primary or only Tool for a page in your website, while other Tools may be intended to never be the primary content on any page, but rather be displayed only as a callout in another page.

A website's home page provides an excellent example, since many home pages contain a variety of elements.  Suppose your home page contains a slider of images at the top (Gallery Tool), a paragraph for a mission statement beneath that slider (Page Tool), then two columns beneath that paragraph: one with the five most recent articles from your "Press Releases" page (the News Tool used for the "Press Releases" page) and another with the next five upcoming events from your "Events" page (the Calendar Tool used for your "Events" page).  In this example, we have one page (your website's home page) that is created using four different Sitemason Tools.  The slider and the paragraph are unique to the home page - they are not intended to be viewed elsewhere in your website.  On the other hand, the Press Releases and Events Tools each have their own page within your site - you're just wanting to include some data from those Tools on your home page as well.

So, to summarize the above example, "Press Releases" is a Tool that is also a page in your website.  "Events" is a Tool that is also a page in your website.  What about the home page - the Tool that responds to  You have two options: either the slider (Gallery Tool) or the paragraph (Page Tool) can serve as the page.  It does not matter which one you choose - the other one will simply be an included Tool when your template renders the home page (just like Press Releases and Events).


An Item is the smallest block of data in the Sitemason organization scheme.  Each Sitemason Tool consists of one or more Items.  The Page Tool consists of only one Item, while other Tools, like News, consist of one or more Items.  Tools allowing for more than one Item are considered list-based Tools because they contain a list of Items and you can visually manage the list from within the Sitemason interface.  Since the Page Tool is an exception (since it is intended to allow the user to enter a block of free text), we'll focus on Items for use in the list-based Tools.

Let's take a News Tool for example.  Each Item in that News Tool consists of handful of properties: a title, subtitle, summary, body, an "is important" flag, a start date and time, an image, one or more Tags, and many other properties.  Most of the properties are optional, the only required properties being the title and the start date/time.

A Closer Look at Items

Items are the most complex component in Sitemason, simply because an Item is where the vast majority of your content will be stored. Each Item has a variety of properties that you can use to organize and store.  As stated before, each Tool contains one or more Items, but underneath, Items are generic - the same Item(s) is/are used from Tool to Tool.  An Item contained in a News Tool is technically the same as an Item contained in a Gallery, however the presentation of each Item in the interface and the properties used have been tailored to fit the needs of the Tool.

A News Tool, for example, has many articles.  And each article may need a headline, sub-headline, summary, copy, photo, author name, and a variety of other data.  In this case, each article is an Item and each of the data points of that article belong to the Item.  In contrast, a Gallery has many photos.  Each photo may need a title, caption, copyright, and most importantly, a photo.  Each Gallery photo is an Item, just like News' articles.  Instead of requiring a headline, the Gallery wants "title." And instead of copy, the Gallery calls for a caption.  Each Sitemason Tool uses Items and the properties of each Item are the same, just re-purposed for the Tool.

You can see just how many fields there are in each Item by looking at the SMItem Class Reference.  More information on how Items are represented as PHP objects is discussed in the Development Library Data Structures section.

Custom Fields

Though there are a variety of pre-defined properties for each Item, sometimes you'll need more, or you might find it easier to implement your project using other fields.  Custom Fields are just that - generic fields used for any purpose that you see fit.  There are two kinds of custom fields:

  • Pre-defined custom fields: these are the sixteen custom fields that are (and have been since Sitemason 4) available to each Item.  Each custom field has a key of "1" through "16."
  • Developer-defined custom fields: these are a virtually-limitless number of custom fields that you may define in a custom interface.  These fields could consist of simple key-value pairs, or a series of relational database-style columns and rows (done through the interface's MultiRow content type, which is demonstrated in the Boilerplate Template's "Presidents" interface file).

Regardless of which kind of custom field you utilize, the values are accessed via SMItem's getCustomFieldWithKey() method.


Tags and Tag Groups

Tags are a powerful method used to relate and group data within your website.  Tags are simply words assigned to related content (Items).  Once Items are assigned Tags (the Items have been "tagged"), you can use Sitemason to filter and/or search for Items based on one or more Tags.

A Tag Group is simply a container for Tags.  All Tags contained in a Tag Group are available to the data model, regardless of whether or not they are used in any Items actually contained in the data.  Tag Groups can be used in more-complex implementations to simply organize the Tags.  Or, Tag Groups can be used for other purposes, such as to construct navigation based on the Tags in the Tag Group or to organize products offered in an online store.

Both Tags and Tag Groups are defined and managed in the Tags panel of each Sitemason Tool.  There, the Tag Manager can be used to add, delete, edit, and merge Tags used throughout your project.

Additionally, Tags can be added and/or assigned to an Item via the Item's Tags tab.