The included Sitemason tool layouts have been designed to be as easy to implement as possible, however, there are many cases where designs must deviate from the stock layout.
Sitemason provides a PHP Library to customize your site & templates much like a common API. Using defined PHP methods you can access various content blocks, and in many cases pass parameters that alter the HTML output for your specific needs.
This document will review the support methods that our stock templates reference. Because these methods already account for the appropriate user settings in Sitemason and offer degrees of flexibility wherever possible, they can be used directly to quickly implement custom Sitemason template designs.
When a method has a parameter, it will be documented in a uniform manner. The type will be either a string, boolean or integer abbreviated preceding the parameter as string, bool, or int. Following the type will be the parameter name in bold and the default in red. A description is provided where applicable. Example:
type parameter default - description
Detailed examples are provided for all methods including parameters where available. If you have any questions, you can comment below each method detail or contact developer-group@sitemason.com.
These are the major methods used when creating a Sitemason PHP template. Remember that you must always include the PHP Library in the top of your template by adding the following:
<?php
require_once('/web/shared/php/1.0/sitemason.inc');
?>
object SideContent (string)
Creates a PHP SimpleXML object from the given Sitemason XML. This is useful for adding additional content to a page, such as what is usually included in a side bar.
[PHP SimpleXML object] getXML ()
Returns the Sitemason XML for the Content/SideContent object as a PHP SimpleXML object.
string printContent ([ array() ])
Displays the Sitemason template for the given layout based on the available XML. printContent accepts many parameters, so please have a look at the full article.
These methods are called by printContent(). Calling these methods directly will aid in effectively implementing custom template layouts with minimal code. And since all of these methods are used by Sitemason's standard template set, using them will retain maximum use of the user's settings and controls). Some methods are passed arguments by value (comma delimited). More-complex methods with more-specific and customizable features accept an associative array for passed arguments.
string getMetaDescription ( array(bool cumulative_description [default true]) )
string getMetaDescriptionTag ( array(bool cumulative_description [default true]) )
void printMetaDescriptionTag ( array(bool cumulative_description [default true]) )
Generates an SEO-friendly description based on the currently-displayed item from the item's summary, tool's description, and site's description. This method is called by printPageHead() and is passed all parameters received by printPageHead(). getMetaDescription() returns just the description itself. getMetaDescriptionTag() returns the description within an HTML <meta> description tag. printMetaDescriptionTag() outputs the HTML <meta> description tag instead of returning it as a value.
string getMetaKeywords ( array(bool cumulative_keywords [default true]) )
string getMetaKeywordsTag ( array(bool cumulative_keywords [default true]) )
void printMetaKeywordsTag ( array(bool cumulative_keywords [default true]) )
Generates SEO-friendly keywords based on the currently-displayed item from the item's tags, tool's keywords, and site's keywords. This method is called by printPageHead() and is passed all parameters received by printPageHead(). getMetaKeywords() returns just the list of keywords. getMetaKeywordsTag() returns the keywords within an HTML <meta> keywords tag. printMetaKeywordsTag() outputs the HTML <meta> keywords tag instead of returning it as a value.
string getStoreCartHTML ([ array(string storeName, string cartTitle [default 'Shopping Cart'], string checkoutButtonText [default 'Check Out']) ])
Returns the HTML to include a Sitemason Store shopping cart. The cart is hidden until an item is added, then the item listing and totals are dynamically updated each time an item is added. If used outside of the store, the Foxycart Store Sub Domain must be specified.
string getWindowTitle ( array(string delimiter [default " | "], string default_title, bool cumulative_title [default true], bool display_index_title_for_site_landing_page [default false]) )
string getWindowTitleTag ( array(string delimiter [default " | "], string default_title, bool cumulative_title [default true], bool display_index_title_for_site_landing_page [default false]) )
void printWindowTitleTag ( array(string delimiter [default " | "], string default_title, bool cumulative_title [default true], bool display_index_title_for_site_landing_page [default false]) )
Generates an SEO-friendly title based on the currently-displayed tool. This method is called by printPageHead() and is passed all parameters received by printPageHead(). getWindowTitle() returns just the title itself. getWindowTitleTag() returns the title within HTML <title> tags. printWindowTitleTag() outputs the HTML <title> tag instead of returning it as a value.
void printAlphaSearchList ( [ array(string query[default "xbegins"], string field[default "title"], string spacer[default " "]) ] )
Displays an A-Z list for searching Sitemason items within the current tool by query string parameters. Accepts an optional query (default: "xbegins"), field (default: "title"), and spacer (default: " ''). The resulting UL will have a class of "sm_alpha_search" and the selected LI will have a class of "selected".
void printArchiveDateSelect ()
Displays the archive selection <SELECT> menu for the current content.
void printBackButton ()
Displays a simple “Back” button triggering with an onClick action history.back() (unless a specific URL has been defined in Display Settings.
void printBodyLast ([ array(string google_analytics_id[default null]) ])
Includes HTML and Javascript that should come directly before the closing </body> tag; currently calls printGoogleAnalytics() with the Google Analytics ID obtained from the Site Builder's settings. Also loads some media-related Javascript libraries and store-related Javascript only when appropriate.
void printBodyTag ([ array(string class[default null]) ])
Displays a <body> tag with classes describing the browser, its version, and the rendering engine. This provides a clean way to use CSS to handle browser incompatibilities without resorting to CSS or Javascript hacks. For a full explanation, see Paul Irish's article "Conditional stylesheets vs CSS hacks? Answer: Neither!"
void printBreadCrumbs( [ array( string delimiter[default ">>"]) ] )
Displays breadcrumbs in a series of <a> tags, with an optional delimiter override. '>>' is used by default.
void printCalendarSpanButtons ()
Displays the Calendar Day, Week, and Month buttons to toggle between views.
void printCallout (string callout name)
Displays the specified callout's content.
void printCommentsBlockForItem ( [ array(string/xml item[default null]) ] )
Displays the comments block for an item. If no item parameter (item XML) is passed to this method, the first (usually only) item will be used in the currently-displayed page's XML.
void printIEUpdate ( [string version] )
Displays code (in IE conditional comments) to generate an Active-X-style compatibility notice for visitors using Internet Explorer. Clicking on the notice will take users to Microsoft's Internet Explorer 8 site. By default, versions 6.0 and lower will que the notice. Feeling bold? Pass a "7" along to help eradicate Internet Explorer 7 too!
void printInitHTML ( [string DOCTYPE [default: XHTML 1.0 Strict] ] )
Prints the appropriate DOCTYPE and corresponding initial <html> tag. Includes references to other XML schemas, as necessary, depending on the type of content.
void printItemDateTime( [ array(...) ] )
void printItemImage( [ array(string/xml item[default null]) ] )
Displays the given item's image (and caption and copyright, if defined). If no item argument is passed, the first (or only) item will be used.
void printItemStatusIcons ( [ array(string/xml item[default null]) ] )
Displays the applicable status (new, updated) icons for the given item. If no item is given, the first item in the XML will be used.
void printItemTags ( [ array(string/xml item, string delimiter) ] )
Displays all tags assigned to the given item within a DIV with class "sm_tags" as a comma (or custom-defined) delimited list. If no item argument is passed, the first (or only) item will be used.
void printItemThumbnail ( [ array(string/xml item[default null]) ] )
Displays the given item's image thumbnail. If no item argument is passed, the first (or only) item will be used.
void printMedia ( [ array(string/xml item[default null]) ] )
Displays the attached audio/video file (and appropriate player) for the given item. If no item is given, the first item in the XML will be used.
void printNavAsList ( [ array(...) ] )
Displays the site's navigation in an unordered (and nested, if hierarchical) list with a class of "l[current level]", contained by a DIV with class "sm_nav".
void printPageHead ( [ array(bool should_include_css [default true], string ie_update [default null]) ] )
Displays the standard block contained in the HTML <HEAD> section, such as the Title tag, Javascript support for Sitemason components, the standard CSS expected by Sitemason templates, etc.
void printPageHeadTitle ( array(string delimiter [default " | "]) )
Deprecated - use printWindowTitleTag() instead.
Displays an SEO-friendly HTML <TITLE> tag based on the currently-displayed tool. This method is called by printPageHead() and is passed all parameters received by printPageHead().
void printPaginationNav ( [ array(bool display_page_summary [default true], bool display_page_numbers [default true]) ] )
Displays the pagination navigation (previous, next, page numbers) for the pages in the resulting list. The number of items per page is set in Sitemason.
void printRelatedArticles([array(int max_articles [default 5], string title [default null], string title_html_tag [default h2])])
Displays an unordered list of articles related to the currently displayed article, based on tags. Inside a DIV with class "sm_related_articles." Related articles will only display in Detail view within the News or Calendar tools.
void printSearchForm ( [ array(string target_url [default current page]) ] )
Displays the text (query) search form. This method adheres to the “Display Search” setting (under Display Settings).
void printSearchShareBlock ()
Displays the Search form and the Share Icons. This function calls printSearchForm() and printShareIcons() within the #sm_search_share DIV.
void printShareIcons ()
Displays the ICS, RSS, Print, Email, and Share This icons for the currently-displayed tool/item. Individual icons must be toggled via Display Settings in Sitemason.
void printTagCloud ( [ array(int tag_group_id [default first tag_group], string tag_group_name [default first tag_group], int min_px [default 10], int max_px [default 24], string header [default null]) ])
Generates and displays a tag cloud for the currently-displayed tool from the given tag_group ID or tag_group Name. Requires a Tag Group to be included in XML (see Tag Manager settings). If no tag_group Name or ID is given, the first tag_group present will be used. If no tag_group is present, printTagCloud() will return false. Other options are min_px and max_px, which sets the minimum and maximum size for the tag cloud links in pixels. The optional header will be displayed, if passed, as an H3.
void printToolTitle ()
Displays the currently-displayed tool's title as an <h1>. If the view is a listing of search results, the query summary will be displayed directly beneath as an <h2 class=”query”>.
These methods are not Sitemason-specific, but are included in the class to support other methods. They are listed here for convenience.
bool isMobileBrowser ()
Returns true if the content is being viewed from a mobile browser, false otherwise.
string makeShortTime (string timestamp)
Abbreviates the given Postgres-style timestamp for display purposes and returns the result in the most minimal form possible. This function is used to abbreviate times in the Calendar month (grid) view.
string truncateString (string, [int max], [string repeat])
Truncates the given input string to the “max” length (if applicable) and returns the result. “Max” and the repeat string can be customized.