EachScape

Each field needed by the block is defined on a separate line. For example,

Count: 1-4
Background Image: url
 Sections: text(optional)

In every case, you need to start the name of a field with an uppercase letter. It may contain letters, numbers, dashes and spaces. In the above lines, the data type restricts input for the Count field to numeric values between 1 and 4 inclusive, the Background Image field will only allow a field that's a URL, and the Sections field accept any text, which may be left blank. If you need multiple occurrences of a field, you can include a line like this:

Button Image: url(4)

The value in the parentheses indicates how many input fields are allowed. It can be a fixed value as shown above, or it can refer to another input field, provided that input field is defined to accept a range of values. For example

Count: 1-4
 Button Image: url(Count)

Sometimes you may have a collection of fields that occur a certain number of times. For example, each button in a block might require two images, one shown when it is unpressed and another to be displayed while it is being touched/pressed. Assuming that the number of buttons varies according to how many the designer selects, you can define a set of fields and associate a count with them.

 

       How Many: 1-6
 [Inactive Image: url, Active Image: url](How Many)

Again it is possible to use a number rather than field name if there are fixed number of occurrences.

       [Inactive Image: url, Active Image: url](6)

And finally, if some of the elements are optional, this is an example with the full syntax.
 

       How Many: 1-6
 [Inactive Image: url(optional), Active Image: url](How Many)

Most of the data types are pre-defined constants, such as color, url, text, etc. As illustrated above, numeric types can be specified by giving a range of non-negative numbers, such as 0-99999 or 2-8. There are special data types for accessing data sources and pre-defined list of values. These are described below.

Accessing Data Sources

There are 3 distinct data types are associated with data sources: feed, feed_field andfield_or_expr. In the case a single field from a feed is needed by a block, the easiest way to do this is to use a feed_field definition. This creates a select list that lets a data source, table and specific field all be selected in a single selection.
 

       Image Source: feed_field

The feed_field suffers from the problem that if multiple fields are needed and the block wants to constrain a user to a single data source, it isn't possible to keep the user from selecting two fields from different data sources using the feed_field alone. Using the feed andfeed_field data types together solves this problem. The feed data type shows a list of all the data sources accessible to the application. When the feed is selected, eachfeed_field in the definition is forced to allow only selections from the fields defined in that particular feed. Implied in this rule is limitation that only one feed data type is meaningful in each block's definition. In other circumstances, you may want to have a templated expression that supports literal text and field(s) from any data source(s) associated with the app. Usingfield_or_expr will allow the user to select a single field from a select list, or switch to a mode where a template expression can be created.

Values from a List

These are entered as a series of values inside a quoted string. The values are entered in a series, separated by semi-colons. If the display value and the return value are the same, one value can be entered (e.g., IBM, below). If the display value and the return value differ, a colon separates them. There is no way to enter a colon or semicolon in a display or return value.

 

Symbols: "IBM; Microsoft: MSFT; Dell Computers, Inc: DELL; Exxon Mobil:XOM"(6)

In this example, the display values will be IBM, Microsoft, Dell Computers, Inc. and Exxon Mobil. The return values will be IBM, MSFT, DELL and XOM. The following characters are not allowed in the quoted list of values: "[", "]" and quote marks. Lists of values may be used when defining sets of fields. See the following example.

 

Count: 1-5
[Symbols: "IBM; Microsoft: MSFT; Dell Computers, Inc: DELL;
              Exxon Mobil:XOM", Site: url](Count)

One other consideration when working with series of choices. Normally series will let the user select a "(edit)" choice that appears at the bottom of the selection list. You can inhibit this by using the noedit option. It's used like this:

       Symbols: "IBM; Microsoft: MSFT; Dell Computers, Inc: DELL;
             Exxon Mobil:XOM"(noedit)

Divider

Long lists may be split into sections by a visual divider. To indicate you want a divider, insert a line that contains only equal signs (a minimum of two is required).