A masthead is a placard-like layout for a header. It only supports the card and simple layouts. The card layout allows 0..2 images and 1..n blocks. It lays out the first image to the left and any second image to the right. The blocks are laid out top-to-bottom in the center. The simple layout allows an optional image and 1 block. It lays out the image on the left and the block immediately to its right. You should use a 'small' image for this type of layout. A module is a basic building block of a widget. It is used to group like pieces of data into one container. It also typically has a header. Headers are used for sections, modules, and submodules. You can include one optional ui-command in your header. You currently only need to supply a title (no icon). The card layout allows 0..2 images and 1..5 blocks. It lays out the first image to the left and any second image to the right. The blocks are laid out top-to-bottom in the center. The simple layout allows an optional image and 1 block. It lays out the image on the left and the block immediately to its right. You should use a 'small' image for this type of layout. The goto element is used to add items to the Options menu (in Yahoo! Go). Under XHTML, the goto items are displayed in a section at the bottom of the page as a series of links. Please note this element should be used sparingly as devices may go so far as to ignore this element. It should be considered optional, and you should never use it as part of the core functionality of your application. The method attribute is used to control how data is sent to the resource identified by the resource attribute. Each of the different methods has a serialization method associated with it. The get and urlencoded-post methods use application/x-www-form-urlencoded. The post method sends the data as application/xml. A ui command is a simple action that can be expressed in the UI with either a title and an optional icon. When activated, any are executed. It is similar to a trigger, but more restrictive in what can be displayed. The label element is used by many of the controls as their label. For example, it serves as the title of a trigger (button), or as the name of an item in a select or select1 control. The option element is used to build a contextual options menu that can be accessed by the user either by the left-soft key on Yahoo! Go, or as a series of links in XHTML. For example, you might have options that related to an email you are currently viewing for commands such as 'reply' or even 'compose'. You can put option elements in many different places, and the most appropriate options will be displayed in the menu. For example, in an email application 'compose' might be in the top-level of a section element, whereas 'reply' or 'delete' might be an option inside a placard. When the placard is selected, the options inside of the item are added to the options menu. This makes it behave like a contextual menu in Mac OS or Windows. The option element is also used by the goto menu. The block element is much like the paragraph element of HTML. It is a container for inline content. InnerContent represents those things that can live in any container (basically, controls). The item element is used in select and select1 controls. The input element is a simple one-line text input box. The image-list type is a generic control which shows a given list of images, each of which can have an action associated with it when clicked. It currently tries to show one row of as many images the current device's screen width can accomodate. There is no guarantee that each image you include will be rendered on screen. It is typically used as a preview of a photostream, etc. You can specify a link to jump to for a 'more' link. An unordered set of links as inline-triggers. Display of this set is renderer-dependent. On iPhone it might simply be a list of placards, on XHTML it might be a bullet-separated list of links. The location chooser control allows the user to choose a location which is returned to your widget. The navigation-bar element is used primarily as a paging control. In its simplest form, it could be used as a more button. If you want to use it to navigate between multiple pages, you can specify both the next and prev elements. If you desire some sort of 'back' link, you can supply the back element. If you supply an element, but do not supply any actions, the element will be displayed inactive (grayed out). You can use this technique if you are at the first or last page, for example. The placard element is probably the most commonly used element. It allows you to specify text and icons in various different pre-defined layouts. It supports a class of "link" which will give the placard a right-pointing arrow over on the right. The card layout allows 0..2 images and 1..n blocks. It lays out the first image to the left and any second image to the right. The blocks are laid out top-to-bottom in the center. The simple layout allows an optional image and 1 block. It lays out the image on the left and the block immediately to its right. You should use a 'small' image for this type of layout. If the template layout is chosen, the content of the placard must be a template-items element instead of a layout-items element. Templates enforce a specific layout and provide named 'slots' to put data. These slots get pre-defined styling based on the template chosen. This means that the layout-items would be extended to allow 0..2 image-trigger element. Note that image-trigger only appears on the right, whereas an image will appear on the left. The layout-items type is used as a container of those items needed for a layout for a placard or a header. While this element as defined here allows any number of image or block elements, the type of layout might only allow a certain number. Also, the interpretation of those elements is up to the layout type of the placard. See the different layout types in placard and header for specifics. The rating element allows you to specify a rating and an optional number of reviews that the rating is an average of. Currently it uses a fixed 5-star rating scale. The secret element is a simple one-line edit field that obscures the user's input. It is used for passwords. The select element allows the user to select one or more items from the list of items presented. Currently, the only presentation types supported for this element are 'checkboxes' and 'toggle'. The latter is used to get the "on/off" look on the iPhone. If a renderer cannot render toggle, it will use checkboxes instead. The select1 element allows the user to select only one item from the list of items presented. Currently, the presentation types supported for this element are 'popup' and 'radio-group'. The submit element is much like a trigger and is generally displayed as a simple button. It's purpose is to submit the current form data as specified by the submission element. The textarea element is a multi-line input area. The trigger element is always visualized as a button in Blueprint. We allow various styles however via the appearance attribute. 'button' and 'normal' are synonyms. Certain renderers may ignore the appearances as far as visualizations. These appearances are also clues to allow renderers to treat cancel and default buttons specially in forms. Tables allow display of tabular data. They might be used for data such as sports scores or financial data. The table implementation in Blueprint is somewhat limited, and lays out a bit different that what you might be used to in HTML. First, cells in a table can only contain text at present. Second, the table structure is somewhat fixed in that the 'title' of a row (e.g. the team name for a sports score) is always the leftmost column, and in fact is not counted as a column at all. The columns are only the set of data to display, and each column or row can have a title associated with it. A table also has the notion of bias, which can affect display and layout (see the bias attribute for more). To fit into tight spaces, columns are dropped in a left-to-right order, with the assumption that your most important data is on the right. If you wish for columns to not be dropped, you can mark them required via an attribute. It is imperative you do not mark too many columns required, or else on certain devices your table might not be displayed because the required columns cannot fit. Bias controls how a table looks as well as how it is laid out. The idea stems around how data is to be viewed. Some types of data might be best viewed horizontally and some might be best viewed vertically. For those situations, we have 'row' and 'column' bias, respectively. These generally give the rows/columns alternating bands of color to help readability where it can be supported. The bias affects layout by essentially stating that horizontally biased tables can split into two lines, where the title of the row is on one line and the tabular data is on the next. This is shown in the pictures. A bias of 'none' does no visual treatment, however it uses horizontal bias layout rules by default. The drop-optional attribute tells the table how it should drop optional columns in order to fit on the current device. If set to 'to-fit', columns not marked 'required' are dropped in a left-to-right order on devices that can support this. If set to 'all-at-once', all optional columns are dropped and only required columns are rendered. The columns element holds a non-empty set of columns. There must be one column element for each column you wish to display. The numeric-emphasis attribute is a boolean which tells the table to effectively colorize anything that parses as a number and is preceded with a - or + sign. This is useful when displaying financial data. The required attribute tells the table that this column is required and should not be dropped if there is not enough room to display all columns. Is is imperative that you do not mark too many columns required or else your table will not be displayed if the required columns cannot fit (or it might be displayed in a very broken manner). The align attribute simply controls whether the data in the column should be left, right, or center aligned. The 'default' value means do whatever is appropriate for the current locale (though at present, this equates to left for all locales until Blueprint supports right-to-left). The row element contains the a required title followed by a cell element which contains the data for each column. If there are not enough cells for the number of columns, the table will render the remaining columns as empty. If there are more cells than the number of columns, the extra cells are dropped. The emphasized attribute tells the table that this cell should be displayed in an emphasized manner. Typically, this is rendered as bold. The emphasized attribute tells the table that this cell should be displayed in an emphasized manner. Typically, this is rendered as bold. The map element and show-map action can be used to show a particular location. It supports the various map modes (hybrid, satellite, etc.) as well as zoom levels and traffic. It can also show points of interest. The resource attribute specifies the URI to the video. Only Adobe Flash Video (video/x-flv) format is supported. This is a hint to the renderer to choose an actual bitrate appropriate to the device, network and purpose. There is no guarantee that all values do not map to the lowest supported rate! The size attribute is used to specify the size of the image canvas your image will be drawn into. In general the image resource you specify should be at the size that is appropriate for the current screen at the current size. The image cannot be drawn outside the canvas bounds. The size attribute, if present, overrides any width or height attributes. The width and height attributes allow you to specify the separate dimensions of an image. If the size attribute is present, width/height are ignored. The width and height attributes allow you to specify the separate dimensions of an image. If the size attribute is present, width/height are ignored. The fill-style attribute tells the engine how to fit images that are not the same size as the canvas size you are using as specified by 'size'. There are three options: crop (the default), fit, and fill. Crop just centers the image onto the canvas and crops it. Fit scales the image so that the entire image fits into the canvas. Fill scales the image so that the entire canvas is filled by the image. Any part of the image that might extend past the canvas after stretching is cropped. See the reference manual for examples of each. The resource attribute specifies the URI of the image. Relative URIs are considered relative to a widget's submission package. For example, "warp.jpg" would reference a file of the same name inside your widget's resources/images/ directory. Technically though, you need only specify the name of the file, e.g. "warp", as for bundled Widgets we will look up the best size to use based on what images are in your images directory. See the Blueprint Developer's Guide for more information on how images should be named in your widget so that the engine can deal with multiple screen sizes. The inline-trigger element is typically used as a link. The activate event is sent when a control is 'clicked' or, in some cases, when the enter key is pressed. A page has loaded and is ready to run. Somewhat equivalent to the 'onload' handler on a page body in HTML.