Skip to content
Sitemason - Build on Us

SMTool Class Reference

Overview

The SMTool class represents the data contained in a Sitemason Tool.  SMTool can represent a Page, Newsfeed, Gallery, Store, Calendar, other Sitemason Tools, or any custom Tool that may be in an account.

Each SMTool has a URL.  While each SMTool object can represent a page within your website, some SMTools will simply contain the data needed for one piece of a page within a website.

For example, many home pages consist of a image slider (Gallery Tool), highlights from the News page (News Tool), a few hero items (another News Tool), and perhaps a brief statement of some kind (Page Tool).  In this case, the home page is comprised of four separate SMTool objects, each with a full URL.  There is only one tool that is assigned the "Home" navigation item (perhaps with a path of "/index"), with the other three Tools being callouts.

Methods

describe

describe ()
see discussion
see discussion
6.0

Information

This method constructs a thorough description of the SMTool and all of its properties (and in the case a property is another SM class, that object's properties).  It is particularly useful during debugging, allowing the developer to quickly see the accessible properties of the Tool.

describe() accepts one parameter, a boolean that defaults to false.  If no parameter is given (the default), then the output description will be written to the browser's console.  This action assumes that the template in question is calling $smCurrentTool->printHTMLBodyLast(), which will inject the proper Javascript command into your template.

If you provide a parameter of "true," describe() will return the same data as a PHP array.  You can then print that to the screen for debugging purposes, as opposed to viewing it in your browser's console.

Here is an example, displaying the description of an SMTool object (with title "Presidents") in a browser console:

Screenshot of Safari Developer Tools Console

	

$smCurrentTool->describe(); // prints data to the browser console as shown above.

getCumulativeWindowTitle

(string) getCumulativeWindowTitle ()
A string containing an assembled window title
6.0

Information

Generates a cumulative window title, separated by pipes, and based on the Tool, the Tool's folder, any parent folder(s), then the site.  Priority is given to the Window Title setting of any node and, if not set, the node's title property will be used.

Note that this method takes into account viewing an individual Item within this Tool (the case where this Tool's getView() method will return "detail").  In such a scenario, SMTool->getCumulativeWindowTitle() will begin with the currently-displayed Item's title, then continue with the Tool's window title, the Folder's title, and so forth.

	

/*
Assume the following:
- You're looking at an item with the title "Deluxe Beach Chair"
- Tool's Title: "Store"
- Tool's Window Title: "Online Store"
- Site Window Title: "Al's Beach Front"
*/

$title = $tool->getCumulativeWindowTitle();
echo '<title>'. $title .'</title>';

// output:
// <title>Deluxe Beach Chair | Online Store | Al's Beach Front</title>

getCustomFieldWithKey

(string) getCustomFieldWithKey (string)
A string representing the key of the custom field to fetch
The custom field's value
6.0

Information

Returns the Tool's custom field value with the given key.  This method works with a custom interface, since the key is defined by your custom interface.

This method is flagged as "Intermediate" because currently a custom interface is required to set Tool-level custom fields.

getFolder

(SMFolder) getFolder ()
An SMFolder object
6.0

Information

Returns the SMFolder object for the Folder that contains this Tool.  Every Tool must reside in a folder, so an SMFolder object will always be returned.

getFolder() could return the SMFolder that is already represented by $smCurrentFolder or $smCurrentSite.  Alternatively, if you have fetched your Tool using getToolWithSlug(), getFolder() could return a Folder other than $smCurrentFolder or $smCurrentSite.

getFoxyCartAPIKey

(string) getFoxyCartAPIKey ()
The FoxyCart API Key
6.0.6

Information

Returns the FoxyCart API Key, as defined in FoxyCart (and set in the Store's FoxyCart settings panel).

getFoxyCartSubdomain

(string) getFoxyCartSubdomain ()
The FoxyCart Subdomain
6.0.6

Information

Returns the FoxyCart Subdomain ([your store's name].foxycart.com) as defined in FoxyCart and in your Store's FoxyCart settings panel.

getImportantItems

(array) getImportantItems ()
An array of SMItem objects
6.0.3

Information

Returns an array of the Items (SMItem objects) belonging to the Tool that have been flagged as "important" (the "isImportant" property is true).

getItem

(SMItem) getItem ()
An SMItem object
6.0

Information

This method returns an SMItem object, however the exact object returns depends on which view is being used.

"Detail" view behavior:

When visiting the detail view of an Item ($smCurrentTool->getView() is "detail"), this method will return the Item represented by that detail view.

List (or any other) view behavior:

When visiting any view other than the detail view, this method will return the first Item in the stack of Items belonging to the Tool.

	// Assume we're on a detail view:

$item0 = $newsTool->getItem();
$items = $newsTool->getItems();

// $item0 and $items[0] both refer to the same object

getItems

(array) getItems ()
An array of SMItem objects
6.0

Information

Returns an array of all SMItems belonging to the Tool.

Important Note: prior to Development Library v6.0.10, when calling this method from a detail view (when $smCurrentTool->getView() returns "detail") this method was functionally equivalent to getItem() and would simply return an array of one element (with that element being an SMItem object representing the Item for the detail view).

getItemsWithLimitAndOffset

(array) getItemsWithLimitAndOffset (int, int)
the limit, the offset
An array of SMItem objects
6.0

Information

Returns the subset of Items belonging to the tool corresponding to the given limit and offset.  The offset begins at zero.

As of version 6.0 there are some restrictions for large data sets that prevent this method from behaving as anticipated.  As a result, if your offset is over ~100 Items, alternate techniques should be employed.  See the Boilerplate template for an example, which is used in its list view pagination.

	

// Assume $tool has four Items with titles: "Title 1", "Title 2", "Title 3", "Title 4"

$items = $tool->getItemsWithlimitAndOffset(2,1);
foreach ($items as $item) {
   echo $item->getTitle() .'<br>';
}

/*
prints:

Title 2
Title 3

*/

getItemsWithTagInTagGroupWithTitle

(array) getItemsWithTagInTagGroupWithTitle (string)
A Tag Group's title
An array of SMItem objects
6.0

Information

Returns all of the Items in the Tool that have been tagged with any Tag contained in the Tag Group with the given title (the Tag Group's title).  

Another way to frame it: getItemsWithTagInTagGroupWithTitle() first looks for a Tag Group with the supplied title.  Assuming such a Tag Group exists, it next looks up all of the Tags contained in that Tag Group.  Finally, it looks up all Items that have been tagged with any of those Tags and returns the resulting set as an array of SMItem objects.

getItemsWithTagWithTitle

(array) getItemsWithTagWithTitle (string)
A Tag's title property
An array of SMItem objects
6.0

Information

Returns the subset of SMItem objects that have been assigned a tag (SMTag) with the given titleTitle (the Tag's "title" property).

getLayout

(string) getLayout ()
The layout of the Tool
6.0

Information

Returns the layout (string) as selected in the Settings tab.  Layouts are defined by the developer.

	

if ($smCurrentTool->getLayout() == '2 Column') {
    // use the two-column layout for this page
}

getMetaDescription

(string) getMetaDescription ()
The Tool's meta description value
6.0

Information

Returns the meta description property, as entered in the Tool's Settings panel.

getMetaKeywords

(string) getMetaKeywords ()
The Tool's meta keywords value
6.0

Information

Returns the Meta Keywords property, as defined in the Tool's settings panel.

getNavigationTools

(array) getNavigationTools ()
An empty array
6.0.5

Information

Always returns an empty array, since Tools do not have navigation.  This method is meant for convenience when building navigation structures, since without checking, you won't know whether an element of the array returned by SMFolder->getNavigationTools() is an SMTool or SMFolder object.

SMFolder has its own getNavigationTools() method.

getNumberOfItems

(int) getNumberOfItems
The total number of Items in the Tool
6.0

Information

Returns the total number of Items contained in the Tool (disregarding any parameters that could have been set to filter the resulting Items).

getRandomItem

(SMItem) getRandomItem ()
An SMItem object
6.0

Information

Returns a random Item from amongst all Items in the tool.

getRandomItems

(array) getRandomItems (int)
The number of Items to return (default 2)
An array of SMItem objects
6.0

Information

Returns an array of random SMItem objects belonging to the Tool.  The parameter, an integer, is the requested number of random Items to return.  The default is two.  If the requested number of Items is greater than the number of Items belonging to the Tool, the requested number will be replaced with the number of Items in the tool (this, getRandomItems will return all Items belonging to the Tool, in random order).

getSlug

(string) getSlug ()
The Tool's slug value
6.0

Information

Returns the slug value assigned to the Tool.

getTagGroups

(array) getTagGroups ()
An array of SMTagGroup objects

Information

Returns an array of all Tag Groups (SMTagGroup objects) belonging to this Tool.

getTagGroupWithTitle

(SMTagGroup) getTagGroupWithTitle (string)
The title property of a Tag Group
An SMTagGroup object
6.0.3

Information

Returns the Tag Group (SMTagGroup object) with the given title.

Rarely will you need to use the Tag Group itself, usually you're after the Tags within a Tag Group.  For that, see the getTagsInTagGroupWithTitle() method to save yourself a few lines of code.

getTags

(array) getTags ()
An array of SMTag objects
6.0

Information

Returns an array of SMTag objects representing every Tag used by active Items in the Tool.

	

// print the first five Tags' titles
$tags = $smCurrentTool->getTags();
for ($i = 0; $i < 5; $i++) {
   echo $tags[$i]->getTitle() .'<br>';
}

getTagsInTagGroupWithTitle

(array) getTagsInTagGroupWithTitle (string)
The title of a Tag Group
An array of SMTag objects
6.0

Information

Returns an array of SMTag objects representing all Tags in the Tag Group with the given title.

getTitle

(string) getTitle ()
The SMTool's title
6.0

Information

Returns the Tool's "title" value.

getTitlesOfTagsInTagGroupWithTitle

(array) getTitlesOfTagsInTagGroupWithTitle (string)
The "title" property of the Tag Group to query
An array of strings (Tag titles)
6.0.10

Information

This method returns the titles of the Tags (SMTag objects) that belong to the given Tag Group.  This is  an alternative to getTagsInTagGroupWithTitle(), which will return the actual SMTag objects.

getToolType

(string) getToolType ()
The Sitemason Tool's type
6.0

Information

Returns the type of Sitemason Tool the object defines (i.e. "page","gallery","newsfeed","store", etc.).

getURL

(string) getURL ()
The URL of the tool
6.0

Information

Returns the URL of the Tool.

getView

(string) getView ()
A string
6.0

Information

Returns a string with the currently-displayed view ("list", "detail", etc.) of the Tool being displayed.  This method is intended to be called only on $smCurrentTool.

hasNavigationTools

(bool) hasNavigationTools ()
False
6.0.5

Information

Always returns false, since Tools do not have navigation.  This method is meant for convenience when building navigation structures, since without checking, you won't know whether an element of the array returned by SMFolder->getNavigationTools() is an SMTool or SMFolder object.

SMFolder has its own hasNavigationTools() method, that will return true or false.

isCurrentlyDisplayed

(bool) isCurrentlyDisplayed ()
A boolean
6.0

Information

Returns a boolean depending on whether or not the current Tool (a page within the website) is being viewed by the site visitor.  Note: this property is only set as part of SMFolder's getNavigationTools() method, as it is intended for navigation purposes only.

printHTML

printHTML ()
6.0

Information

Renders HTML for the Tool using the layout defined in the Tool Template from the selected Tool Template Set from your configuration.

For details on Tool Template Sets (including what they are and how to modify them), see the documentation section on Tool Template Sets.



For details on how a Tool Template Set is selected in the configuration, see the section on File Organization and Configuration.

printHTMLBodyLast

printHTMLBodyLast ()
6.0

Information

This method loads any resources required by the Tool Template Set and should be called from your template, immediately before the closing BODY tag.  The Tool Template Set is responsible for all HTML output.  In addition to any CSS and Javascript required by the Tool Template Set, printHTMLBodyLast() could include other important scripts and settings.  It is therefore good practice to always call printHTMLHead() in your template and, if you require changes, alter the Tool Template Set accordingly.

For details on Tool Template Sets (including what they are and how to modify them), see the documentation section on Tool Template Sets.



For details on how a Tool Template Set is selected in the configuration, see the section on File Organization and Configuration.

printHTMLHead

printHTMLHead ()
6.0

Information

This method loads any resources required by the Tool Template Set and should be called from your template's HEAD section.  The Tool Template Set is responsible for all HTML output.  In addition to any CSS and Javascript required by the Tool Template Set, printHTMLHead() also constructs important tags, scripts, and settings.  Some example of these are:

  • Facebook Open Graph tags
  • Search Engine Optimization features, such as an SEO-optimized window title, META data, etc.
  • Google Analytics settings defined in your account

It is therefore good practice to always call printHTMLHead() in your template and, if you require changes, alter the Tool Template Set accordingly.

For details on Tool Template Sets (including what they are and how to modify them), see the documentation section on Tool Template Sets.



For details on how a Tool Template Set is selected in the configuration, see the section on File Organization and Configuration.

setItems

(null) setItems (array)
An array of SMItem objects
6.0.3

Information

Sets (resets) the Tool's Items to the given Items.  This is useful if your template needs to manipulate the Items before performing other tasks or rendering output.

shouldIncludeInNavigation

(bool) shouldIncludeInNavigation ()
A boolean
6.0

Information

Returns true/false depending on whether or not the Tool has been set to be included in the website's navigation structure.

shouldIncludeInSiteMap

(bool) shouldIncludeInSiteMap()
A boolean
6.0

Information

Returns true/false depending on whether or not the Tool has been flagged to be included in the website's site map.  This is set in the Tool's Settings panel.

sortItemsByKeyWithOrder

(void) sortItemsByKeyWithOrder (string, string)
(startTimestamp|title), (ascending|descending)
6.0

Information

Sorts the SMTool's array of Items based on the given key (one of the Item's properties) and the order in which to sort them.  Currently-supported keys are:

  • "startTimestamp": sorts the Items in chronological order based on their start time (default)
  • "title": sorts the items alphabetically based on their title.

The second parameter (order) is either:

  • "ascending"
  • "descending" (default)

The default values are set so that the most current (or future-most) Item is first in the array of Items.

If you need to sort by using this method, be sure to call it before calling getItems().