If you don't have a Sitemason account, signup now.
Sitemason is a hosted development platform & CMS. It relies on a PHP template environment which parses XML or JSON published by the CMS. Additionally, it utilizes a library to simplify common tasks.
JSON is available to all sites, but does not currently included its own PHP library
Before starting development, it will be worthwhile to look through the PHP Library and get familiar with the Sitemason functions. When ready for development, begin looking through your default template. A single template file is applied to each site, in location www.website.com/sm_template/template.php. From FTP, this location is /www/sm_template/template.php, and is the Sitemason boilerplate that offers a starting off point for the Sitemason beginner.
Every line of a template, with the exception of calling the library (1) and loading the content (2), is optional.
1)
require_once('/web/shared/php/1.0/sitemason.inc');
2)
$content = new Content($content_xml); $content_xml = $content->getXML();
However, it does include a handful of Library functions which Sitemason strongly recommends keeping. Sitemason's stock layouts often rely on CSS and Javascript published by printPageHead() and printBodyLast() while printInitHTML() and printBodyTag() will likely simplify your development experience.
Important note: While the Sitemason PHP Library does take a lot of the work out of programming, understanding the basics of PHP is instrumental in developing with Sitemason. Although it can be a beginner's tool, it is most powerful when used by those with a mature development background.
When including resources in your primary template file, like CSS and Javascript, always use paths relative to the hostname, and not to a parent directory. For example, load a page's stylesheet like /sm_template/css/style.css instead of css/style.css. Since all site traffic goes through a single template file to display all pages, resource paths must always be relative to the site's top level.
While a site is in development and it's DNS is pointed elsewhere, it's URL will always include .sitemason.com tacked to the end of the hostname. For example, if your site is at www.website.com, it's development URL will be www.website.com.sitemason.com. When redeveloping a website already on Sitemason, use a sub-directory or a PHP switch.
Site data is published as XML. To see any page's data, tack "xml" to the end of the query string. For example, to see the XML for a website's home page, use www.website.com?xml. This is the XML available to work with for a given page. It includes navigation and the current page content, as well as header, footer, and general site data XML. Using PHP, you can print any data from the XML tree. For example, to print a site's title, echo $content_xml->title; where $content_xml is the variable loaded with the page XML.
To apply separate layouts to site pages and sections, utilize PHP to key off unique values in the CMS output. For example, a site often has unique home and interior layouts. A common way of handling this is to key off a page's ID to load an appropriate layout for the page being visited.
if ($content_xml->current_nav->id == '{id}') {
include('inc/home.php')
} else {
include('inc/interior.php');
}
Important note: The most useful key to work from when switching layouts is the Tool ID, which can always be accessed through current_nav->id in the current page's XML. When a number of layouts are needed, it's often helpful to declare layouts by name, like: if ($content_xml->current_nav->id->{home_id}) { $layout = 'home'; }
Often a layout requires content from another tool beyond what's available in the current page's XML. To include this additional content, use the Sitemason function SideContent() to call the page URL with "toolxml" in the query string for the content desired. For example, there's often the requirement to list a news feed in a side column.
$side = new SideContent('http://www.website.com/news?toolxml');
$side_xml = $side->getXML();
foreach ($side_xml->content->data->item as $item) {
echo '<h2><a href="' . $item->url . '">' . $item->title . '</a></h2>';
}
Important note: Only load SideContent in a template or layout when it is required by the page. Loading extraneous XML per page will only slow a site down. As with loading CSS & Javascript, it is good practice to avoid loading site resources on pages where it is not required. For example, if a list of news items is only required on the home page, load SideContent() from the home layout, and not from the primary template.php file, which would load SideContent() on every page, hindering performance.
Sitemason provides a number of query parameters that help a developer access only the data needed for a particular use. For example, to return items tagged with "apple" add xtags=apple to the query string. This works for displaying items on a web page, but more importantly, as a developer, pairing this principle with SideContent() provides a simple and powerful way to return only the XML needed for a particular application. For example, instead of looping through an entire set of items to find all those tagged with "apple", add a query to the URL in SideContent():
$side = new SideContent('http://www.website.com/news?xtags=apple&toolxml');
$side_xml = $side->getXML();
Add multiple queries to the same path to further refine a search, like ?is_important=1&sort=title,asc&xtags=apple
Sitemason URLs are documented on our URLs developer page.
The same principle applies to working with JSON. Add "json" to the end of the query string to access site data and "tooljson" for individual tool content in the JSON format. In most cases, XML is the preferred data format for building websites. Common uses of Sitemason JSON are development of mobile apps as well as one-off web applications. There is not a Sitemason PHP Library for JSON, so all development with JSON requires working with raw data.
The suite of Sitemason tools is covered in our standard documentation at support.sitemason.com, but as a developer, it's important to understand when to use a certain tool. Sitemason's tools are broken up into two general types: single-page and list. Single-page tools include the Page Builder and Form. List tools are News, Calendar, Gallery and Store. All of these have a predictable application, with the exception of Page Builder and News.
The Page Builder's most common use is of course a free-form, word processor-like interface, to manage most site pages. However, it can be used for a universal side bar, additional content areas, or if a single WYSIWYG field is needed in a pinch. While the News tool is more often than not exactly that - a news publication tool - it is often repurposed for more complex applications needing a list and detail view of items. Examples might include a people directory, recipe repository, job board, or project list.
When repurposing a tool, like News, it's important to remember that Sitemason is a set of available fields. Though the user interface labels each field for a specific purpose, they are still just fields in a database that a webapp can apply its particular use. For custom applications, map the project requirements to available fields, then customize the interface for the end user.
List based tools offer a near unlimited palette for a developer to create a customized user interface, unique to a specific application. Interface configs are javascript files set in a list tool's Setup->Advanced tab (enabled through the Behavior tab). They override both the list and detail views of an item in the UI.
Custom Interface is a beta development and is loosely documented here.
Look over our boilerplate template and the PHP Library to get familiar with the basic pieces of a Sitemason template. Then, walk through the PHP Template Tutorial to better understand the moving parts. If you have questions, head over to the developer forum.