Skip to content
Sitemason - Build on Us

Overview

This section introduces the two commands for registering customizations and provides examples of modifying labels and removing tabs.

Panels are created each time they are opened and are destroyed after they close. Therefore, your customizations need to run every time a panel is opened. There are two commands available to make your customizations available to panels when they open:

  • modifyLabels()
  • modifyConf()

This section will explore these commands in further detail.

Modifying Labels

The easiest and fastest way to customize a Tool's interface is using modifyLabels(). This command alters an existing Tool's interface, replacing the predefined labels for Items, help text, and the Tool's itself (the Tool's name). As an argument, modifyLabels() takes a Javascript object to map new labels. There are currently five settings that you can change:

  • toolLabel: the label for the type of Tool (normally "News", "Calendar", "Gallery", etc.)
  • toolLabelPlural: the plural version of toolLabel
  • itemLabel: the label for the type of item in the Tool (normally "Article", "Event", "Photo", etc.)
  • itemLabelPlural: the plural version of itemLabel
  • itemTitle: the label for the title of the Item (normally, "Headline", "Title", etc.)

For example, to re-label a News tool and turn it into a "Blog," use the following command:

modifyLabels( {
    toolLabel:       'Blog',
    toolLabelPlural: 'Blogs',
    itemLabel:       'Post',
    itemLabelPlural: 'Posts',
    itemTitle:       'Title'
} );

Customization Functions

Extensive customization can be achieved by writing a customization function. The modifyConf() command ties your function to a particular type of panel, specifically, a toolPanel, toolSettingsPanel, itemPanel, tagPanel, tagGroupPanel, or subscriptionPanel.

Customization functions run in the context of the panel they are modifying, so the "this" variable represents the current panel. As an example, let's print out the tabs within a panel using the getTabNames() method. getTabNames takes no arguments and returns an array of tab names.

modifyConf('toolPanel', function() {
    var tabNames = this.getTabNames();
    console.dir(tabNames);
} );

In this case, we tied it to the toolPanel, so we should get a response like this in the browser console:

0: "itemsTab"
1: "tagsTab"
2: "tagGroupsTab"
3: "subscriptionsTab"

A variety of methods are available for modifying tabs and their contents, but first you'll need to get a reference to the tab you want. The getTab() method is passed a tab's name as an argument and returns a reference to the tab.

A common customization is to remove unused tabs in a panel.  To illustrate this, we'll use the panel's getTab() method to return the specific tab to remove, then use the tab's remove() method. Since getTab() returns a reference to the tab, we can chain the commands.

The following command will remove the "tagGroupsTab" and "subscriptionsTab" from the tool panel:

modifyConf('toolPanel', function() {
    this.getTab('tagGroupsTab').remove();
    this.getTab('subscriptionsTab').remove();
} );

Note: If more than one function is tied to the same panel, only the first function will be applied.

Examples

A thorough example of interface customization can be found in the Boilerplate template's "Presidents" Tool.  The Boilerplate template (and website) is automatically created with every new Sitemason account.