The Sitemason® Development Library is a set of PHP scripts that translate your site's data (residing in Sitemason) into PHP objects for use in your Site Template. The Development Library is loaded before the server loads your Site Template, so its objects are automatically available and ready to use in your Site Template.
If you aren't familiar with Object Oriented PHP, you can learn more about it on the PHP website, or you can dig into the Boilerplate Template to learn the basics of the syntax.
The Sitemason Development Library consists of a handful of classes. Each class has a variety of methods that make presenting and manipulating your website's data easy.
The Data Structure
If you recall, the section "Folders, Tools, and Items" discussed how Sitemason® websites are organized using those three things. If you did not read that section and are new to Sitemason, please take a moment and read it, then jump back here.
The data model used by the Development Library implements the same Folder, Tool, and Item organization concept via the SMFolder, SMTool, and SMItem classes, respectively. The SMFolder class implements methods and properties appropriate for handling a Folder, the SMTool class implements methods and properties appropriate for a Tool, and the SMItem class implements methods and properties for an Item. The Development Library contains more than just these three classes, but these are the cornerstones.
A Folder is a collection of Tools, so naturally you're likely to need to access the Tools stored in that Folder. For this task, SMFolder has a getTools() method, which returns an array of SMTool objects (and possibly SMFolder objects for hierarchical sites), with each SMTool object representing a Sitemason Tool contained in that Folder. Each Tool has one or more Items, so following the same convention, SMTool has a getItems() method to return an array of SMItem objects. And finally, you've reached an Item. Commonly, you'll want to get the Item's title (stored in the "title" property), so you'd use SMItem's getTitle() method.
You'll find the documentation for each class and each class' methods in the Development Library Reference.
There are three fundamental objects that get created by Sitemason and are stored in three variables, which are automatically made available to your Site Template: $smCurrentSite, $smCurrentFolder, and $smCurrentTool. These three objects are based on the page of your website that you (or your site visitor) are currently viewing. It's helpful to look at these in reverse order:
$smCurrentPage: this is an SMTool object representing the page that you're currently viewing. For example, if your website includes a news page (a News tool in Sitemason) at /news and you're viewing that page, $smCurrentPage would be an SMTool object representing that News tool. It would contain multiple articles (SMItem objects) and each of those might contain images (SMImage objects), tags (SMTag objects), and other objects and properties.
$smCurrentFolder: this is the SMFolder containing $smCurrentPage. If your website has no folders or the $smCurrentPage in question is at the root level, then $smCurrentFolder is identical to $smCurrentSite (and you'll notice that SMFolder is a subclass of SMSite). $smCurrentFolder is probably the least-used of the big three objects.
$smCurrentSite: this is an SMFolder object representing the entire website. You would call methods on this object for navigation and/or to access any of the website's properties.
Software is never finished, so neither is Sitemason® nor its Development Library. We're constantly improving our product. Except for major releases, such as Sitemason 6, Sitemason CMS gets automatically updated (and even then it is often a trivial upgrade). However, the Development Library resides in your website's file space and does not get automatically updated. You can always load the latest version of the Development Library, though!
The Development Library's versioning scheme is:
[major version].[minor version].[revision]
The Major version is intended to correlate to the major version of Sitemason CMS that this library was written for ("6" in this case). The minor version signifies the release of this library. Minor version updates could incorporate backwards-incompatible changes that will require Site Template code updates in order to use that version of this library. Please refer to the library's README file for any such notices and details.
Revisions will indicate backwards-compatible updates made from time to time to further improve the library or provide bug fixes.
Complete documentation for each Sitemason® Development Library class and its methods can be found in the Sitemason Developer Library Reference.