Context lets you filter and sort items from a content set.

Note   If you haven’t yet learned about hooking up content sets, check out Separate Content and Design.

Basically, context is a list of parameters that looks something like:

You can set how items are sorted. For example, give each item (in the content set) an order field with a number in it. (Learn more about adding fields.) And then sort the items by that field:

And you can set which items should be shown. For example, give each item a tags field, and display only items with a particular tag:

We’ll talk more about which parameters you can add, and how to add them next.

You can break context parameters into two categories:

• Sort parameters
• Filter parameters

Sort parameters

You can use certain parameters to sort items:

• sort
• size
• page

sort

The sort parameter lets you set how items are sorted. You can set the direction that items are sorted in.

To sort items in ascending order, use:

sort=asc

To sort in descending order, use:

sort=desc

And you can set what field is used for the sorting. For example, you can add a field used only for sorting to your a content set:

And then sort the items by that field name (which in this case is item-order):

sort=item-order:desc

To learn more about adding fields, check out Manage Your Content.

size

Some widgets display only one item (the Heading widget). Other widgets display several items from a content set (like the Menu widget).

Some widgets, like the Menu widget, will display multiple items when you use them with content sets.

Using the size parameter, you can set how many items to return. To return 15 items, use:

size=15

size=10 is the default. So if you want to display all items in the content set, then set size to a high number:

size=9999

Note   Some widgets, like Feature Grid, have a separate setting that let’s you set the number of items to display. In that case, just use the widget’s setting.

page

If size is less than the number of items in your content set, then you’ll have multiple pages. Like with the DevKit blog.

On the Blog page, you can see the latest 10 blog posts. Click Page 2 at the bottom of the blog, and you’ll see posts 11 – 20. Notice that the URL ends in ?page=2.

So using the page parameter, you set which page to return:

page=3

Also page works with size. And if you remember, size=10 by default. So by default, page=3 returns items 31 – 40.

You can combine page and size. For example, this context string (we'll talk more about context strings later):

size=3&page=2

Will return items 4 – 6.

Note   By default page=1. So if you don't set page, you'll just get the first page.

Filter parameters

While you can sort items, you can also filter them with these parameters:

• q
• id
• size (which we talked about earlier)

q

Using the q parameter, you can search through items in content set. For example, to search the DevKit blog for bootstrap, you would use the URL:

trydevkit.com/blog?q=bootstrap

That will search through every field in the blog content set, and return only the matching items.

To search through a particular field, use the field name:

q=title:bootstrap

For example:

• DevKit blog
• DevKit blog with q=bootstrap
• DevKit blog with q=title:bootstrap

id

Using the id parameter, you can return only a particular item. Every item has an id (which you learned in Separate Content and Design).

Use id to return a single item:

id=b796241d-c0a2-cb1a-b526-535fe7c8d4c2

The most common scenario for id is links. For example, to link to A Beginner's Guide to Usability Testing on the Devkit blog, use:

/blog-post?id=81da0af5-fb17-fd8e-016b-536948e32ced

Okay, now you know what parameters do. The next step is to create a context string with one or more parameters.

To add multiple parameters:

• Use the & symbol.

So to build a context string with sort=item-order:asc, size=3, and page=2, use:

sort=item-order:asc&size=3&page=2

Also, the order of the parameters is not important.

Once you’ve built a context string, you can add it in a few different places:

• URL
• Page Settings
• Widget Settings
• Content set

Add context to a URL

Context works when added to the end of a URL (like you saw earlier). To add context to a URL, just preface the string with a ?:

trydevkit.com/blog?q=bootstrap

So a quick way to test a context string is just to add it in the address bar. Or if you like, you can link to a page using the context string.

For example, you could create multiple links to the same page using different context strings:

/courses?q=cat:prerequisite

/courses?q=cat:site-development

/courses?q=cat:design

Note   If you add context to the URL, the context string will be applied to every widget. If you want to apply different context to various widgets on the same page, you can instead add the context in the Widget Settings.

Add context to Page Settings

If you want a friendlier URL, you can add context to the Page Settings:

1. First, click Page Settings in the upper right.
2. On the Settings tab, add your context string to the Context box, and then click Apply.

Add context to Widget Settings

If you want to use different context for different widgets, add context to the widget’s Settings:

1. Click a widget to open its Settings on the right.
2. In the Settings, add your context string in the Context box on the right.

Note   Context will work only with fields that the widget uses. So if you want to sort by the title field, you first have to add that field to the widget’s Settings. Learn more about configuring widgets.

Add context to a content set

You can also set the default context for a managed content set, which you’ll see if you don’t add context anywhere else.

To set the default context for a content set:

1. On the left, click the content set to open it.
2. Then click the Settings tab to see the options for setting the context.

Here, on the Settings tab, you can set the default:

• Size
• Sort field and direction

Default size

The number that you enter here is the default number of items that will be returned for widgets that display more than one item (like the Menu widget). This basically sets the size parameter for the content set, which we talked about earlier.

Default sort field and direction

You can also set the field to sort on and the direction: ascending or descending. These fields basically set the sort parameter for the content set, which we talked about earlier.

Talking about default context brings up the issue of inheritance. Specifically, since you can add context in several different ways, what overrides what?

If you set content in multiple places, you’ll want to know what the final context will be.

For example, if you set the size in the Page Settings and you set a different size in the Widget Settings, which value is used? (The answer is the widget value, but we’ll talk more about that next.)

The order of priority, from lowest to highest, is:

1. Default. If no values are set, the content set will use the default context: size=10, page=1, and sort=date_created:desc.
2. Content set. The values that you set at the content set level will override the default values. Although, at this level, you can only set size and sort.
3. Page Settings. Any context in the Page Settings will override the values you set for the content set.
4. URL. If you add context directly to the URL, it will override values set in the Page Settings.
5. Widget Settings. Context that you add to in the Widget Settings take priority over all other all other context.

For example, if you set:

• Content set: size=20
• Page: size=15&sort=date_created:asc
• URL: page=2
• Widget: sort=title:asc

The final context will be: size=15 (from the page), page=2 (from the URL), and sort=title:asc (from the widget).

You can use context in a variety of ways to display only the specific content you want. While the possibilities are numerous, here are some of the most common ways that people use context:

• Returning more than 10 items
• Creating a friendly URL
• Creating a category page
• Sorting blog posts

Returning more than 10 items

Often you may have a scenario where only 10 items are displayed. You can fix this problem easily with the size parameter. Remember, the default context is size=10.

To display every item:

• Set size to a large number like: size=9999.

If you’re using a managed content set, you can set the default size for the content set.

Otherwise, set size in the Page Settings or Widget Settings.

Creating a friendly URL

The ?id=incredibly-long-string-of-numbers-and-letters isn’t that descriptive. Plus it confuses Google. A friendly URL, generally refers to a URL that is human readable and doesn’t use parameters (like id).

For example, blog posts and product pages have a URL that looks:

http://example.com/blog-post?id=4bffa20d-a74c-9559-4709-5231fc8b0be8

In the Page Settings, you can incorporate the title to create a URL that looks like:

http://example.com/blog-post/why-peppermint-tea-is-great/4bffa20d-a74c-9559-4709-5231fc8b0be8

Learn more about friendly URLs & page slugs.

Creating a category page

You can search a content set using the q parameter. So if, for example, you have a field in your content set that you use for categories, use this feature to return only items that match a particular category.

For example:

q=category:nature

Try this on the All courses page:

/courses?q=cat:prerequisite

/courses?q=cat:site-development

/courses?q=cat:design

Sorting blog posts

When using the Blog Roll widget, blot posts are sorted from newest to oldest. If you want to change that order, use the sort parameter.

For example, to sort by oldest created post first , use the context string:

sort=date_created:asc

Try it out sort the DevKit blog:

/blog?sort=pub_date:asc