Patterns Library

Includes

itemsByProp.settings(id,opts)

itemsByProp.widget(opts)

callback addRemoveItems(additems,removeitems)

The patterns library contains functions that make it easy to create a number of common widget types.

If one's widget follows one of the patterns that the patterns library is designed for then using the patterns library is likely to make widget development much easier, since it avoids the need to write boilerplate code that would otherwise be common to many widgets.

See the Simple Image example to see the patterns library in action.

If you are interested in understanding how the patterns library is implemented in terms of the Widget API then you can have a look at the source for the patterns library:

http://mashmaker.intel.com/v13/mashmaker_patterns.js.

Includes

To use the patterns library, make sure you include the following in the head section of your web page:

<script type="text/javascript" src="http://mashmaker.intel.com/v13/mashmaker_api.js"></script>
<script type="text/javascript" src="http://mashmaker.intel.com/v13/mashmaker_settings.js"></script>
<script type="text/javascript" src="http://mashmaker.intel.com/v13/mashmaker_patterns.js"></script>
<link rel="stylesheet" href="http://mashmaker.intel.com/style/settingstyle.css"/>

itemsByProp

A widget follows the itemsByProp pattern if it wants to be given a set of items with a particular set of properties. For example, all items with images, all items with phone numbers, or all items with addresses. The Simple Image widget is an instance of this pattern.

The patterns library deals with providing the following functionality:

Create a settings panel that allows a user to specify which items the widget should be applied to, and which properties should be used
Guess default settings based on the data currently on the page
Share settings between the widget panel and the settings panel
Simplify the implementatino of Entry Point and mashmaker_widget_removeProp.

itemsByProp.settings(id,opts)

Creates a settings panel automatically, given a description of the properties that we want.

id is the id of a table that should have rows added to it for settings.

opts has the following fields:

path	true if the settings should include the ability for the user to control which elements the widget is applied to.
slots	A list of slot names that the widget is interested in obtaining from the elements.

A slot is something that the widget wants to know about an item. For example image, address, phone. The settings panel allows the user to match slots to actual properties of elements. E.g. should address be work address or home address. It is these concrete properties that will be passed to the main widget frame.

See Simple Image for an example of this function in use.

itemsByProp.widget(opts)

This function simplifies the implementaton of a widget that follows the itemsByProp pattern.

opts has the following fields:

path	as for settings
slots	as for settings
addRemoveItems	function to be called whenever data of interest to the widget is added to or removed from the page. Described in the following section.

If the widget does not yet have any settings (it was added to the page as-is, rather than as part of a mashup) then this function will try to guess the initial settings based on the data on the page.

callback addRemoveItems(additems,removeitems)

This function is provided by the widget and is called whenever items matching the widget's criteria are added to or removed from the page.

The arguments are as follows:

additems: an array of items that have been added to the page removeitems: an array of ids of items that have been removed from the page

Each item in the additems array contains an id filed that identifies it. This is the same id used for this item in the Widget Data Format for the data on the page.

Each item also contains an associative array called slots. This matches each of the slot names passed to itemsByProp.widget to an array of text values that have been assigned to that slot for that item. In many cases there will be only one element in this array (e.g. in item usually has only one address).

See Simple Image for an example of this function in use.