| Table of contents |
There are two parts to a Sitemason URL. The first part identifies what tool to display, like http://www.sitemason.com/form/gOiHHq or http://pirate.monkeyness.com/pirate_fight/apply. Everything after that in the URL is passed as parameters to the tool being called. Parameters in the path of the URL determine the layout that is used and how XML data is formatted. They also define the constraints for how many items are retrieved and what offset to use when retrieving those items. Parameters in the query string specify searches that narrow down the results that are displayed.
In old Sitemason, the non-vhost address started with the tool's name and a six character id. In new Sitemason, all non-vhost addresses start with "/element" followed by a seven character id, specially designed to not have confusing characters. You will not find a one (1) or lowercase L (l) and since no uppercase characters are used, you will not have a capital O to conflict with a zero (0).
In old Sitemason, each tool used different notation and different parameters; There was no consistency. Many of the parameters were passed in the query string, the part after the ?, making it difficult to cache content and making it less appealing to search engines. In new Sitemason, all the tools use the same notation and same parameters and most parameters are specified in the path. Only search parameters are in the query string.
The first parameter is the "view". It determines the tool template and the format of the XML. Everything following the view and before the query string is the "span". The span determines the range of items to display.
/element/{id}/{view}/{span}
Views are designated by using the words, "cal_grid", "cal_list", "list", etc. in the URL as listed below. The valid "spans" are listed for each view.
Spans come after the view and come in a variety of formats. There is a name for each format, but it doesn't necessarily show up in the URL.
/{year}/{month}/{day}/{title}.{id}/{page}
/2007/8/20/some-article.53 - shows item "Some Article" with id 53, page 1
/2007/8/20/some-article.53/2 - shows item "Some Article" with id 53, page 2
/id/{id}/{page}
/id/53 - shows item 53, page 1
/id/53/2 - shows item 53, page 2
/time_id/{time_id}/{page}
/time_id/134 - shows item 134, page 1
/time_id/134/2 - shows item 134, page 2
/set/{limit}/{offset}
/set/30 - shows 30 items starting from the start.
/set/30/60 - shows 30 items starting at the 60th.
/days/{days}/{offset}
/days/3 - shows 3 days worth of items starting from the start.
/days/3/6 - shows 3 days worth of items starting at the 6 day from the start.
/{year}/{month}/{week|day}
/2007 - shows all of 2007
/2007/8 - shows all of August 2007
/2007/8/2nd - shows the second week of August 2007
/2007/8/20 - shows August 20th, 2007
In new Sitemason, the query string, the part of the URL after the ?, is used for search parameters. There are two types of searching. There is a general search that intelligently parses a search field, much like using the search field in Google and there are specific searches that let you search individually on most of the fields of data.
The general search attempts to parse search text passed to Sitemason as a single string of text. Sitemason tries to recognize formatted information in the search string in the following order.
The general search may be passed in a field named "q" and for compatibility with older Sitemason tools, "search" or "search_string". Any of the three will work, but "q" takes precedence if more than one of the fields is present. To search for "pirate", use a query string of "?q=pirate" or submit a form with a field named "q" and a value of "pirate".
Example for grabbing the a time range from "yesterday" through the "next 2 days":
http://www.domain.com/page_name/?q=yesterday to next 2 days
Specific searches allow you to be very selective about what results are returned. The following are some of the fields available for specific searches. Unless specified otherwise, these searches are inclusive, using "OR".
Example
thing 1 - hat, blue
thing 2 - hat, red
thing 3 - scarf, blue
product 4 - scarf, red
thing 5 - socks
tags=hat&tags=blue&q=thing
Any hats, blue items, or items matching "thing": all but 4
xtags=hat&xtags=blue&q=thing
Any hats or blue items that also match "thing": 1, 2, 3
xatags=hat&xatags=blue&q=thing
Any hats that are blue and match "thing": only 1
Sorting can be defined by using one or more "sort" arguments in the form of "sort={field}". Additionally, you can specify the sort order by adding "asc" for ascending or "desc" for descending separated by a comma, as in "sort=title,desc". "asc" is the default for any field. An example of multiple sort criteria is "sort=is_lead_item,desc&sort=title,asc".
There are two specialty sorts, popularity and random. Popularity has some extra requirements to enable it since every time an article/event is requested it makes a separate call to increment a counter for that article/event. Contact support for more info.
The random sort preempts any other sorts you define. Simply use "sort=random" to get a random list of articles or events. You can use any of the view/span combinations aside from detail. For instance, "/list/set/5?sort=random" will give you 5 random items. "/2010/07?sort=random" will give you all events from July 2010 in random order. This is an especially useful feature for sidebar content where you need to pull a random item, like a quote, out of a set of hundreds, because you don't have to grab everything and then pick one at random. For slideshows, you could pull enough random items to display for a reasonable amount of time, like 50, out of a list of thousands.
The following is a list of sortable fields.