Toolbox component metadata
Last updated
Last updated
XBL components can be loaded by the Form Builder toolbox. In order for Form Builder to have information about those components, metadata can be added to each XBL binding.
The Form Builder specific extensions are in an namespace::
URI: http://orbeon.org/oxf/xml/form-builder
Usual prefix: fb
Example: xmlns:fb="xmlns="http://orbeon.org/oxf/xml/form-builder"
In XBL, each component is defined in an <xbl:binding> element and multiple <xbl:binding> can be grouped under an <xbl:xbl> element. The Form Builder toolbox shows components, grouped by "types of components", e.g. "Text Controls", as shown at the right of this text. To instruct Form Builder that multiple component should be grouped together in the toolbar, place then inside the same <xbl:xbl>. Then, as a child element of <xbl:xbl>, you provide the title for the group inside an <fb:metadata>, as in (see the full source as of Orbeon Forms 2018.1):
To be used in Form Builder, your XBL component must have an additional <fb:metadata> section inside the <xbl:binding> of your component. That <fb:metadata> provides to Form Builder the localized display name for the component, an icon, and the markup to be inserted by Form Builder into the form when the component is used. For instance, the <metadata> section for the Explanatory Text component look like (see the full source as of Orbeon Forms 2018.1):
Prior to Orbeon Forms 2018.1, you would use <fb:small-icon> to point to an image file:
NOTE: <fb:large-icon> was present in a number of XBL components but never used by Form Builder. We recommend, starting with Orbeon Forms 2018.1, using <fb:icon-class> which allows for scalable icons.
[SINCE Orbeon Forms 2018.1]
The new <fb:icon-class> element allows you to specify a set of CSS classes used in the toolbox to show a scalable font icon. This is useful with icons from Font Awesome and similar. In that case, don't use <fb:small-icon>. For example:
When form authors add an instance of your component from Form Builder, Form Builder needs to… well, add the component to the form. For this, inside the <fb:templates> for your component you declare:
Inside <fb:view>, the markup that goes in the view, e.g. <xf:input> for a plain XForms input.
Optionally, on <fb:bind>, attributes you might want to add to the <xf:bind> Form Builder adds for your component.
Optionally, and this is rare, inside <fb:resources>, additional resource elements the component might use, in addition to the label, help, hint, and alert. E.g. this is used in explanation.xbl.
If your component only needs a template for the view, which is maybe the most frequent use case, instead of nesting an <fb:view> inside an <fb:templates>, you can just use an <fb:template> element, as in:
All the controls share certain properties, like the control name. However, some XBL components take additional properties, set at design time in Form Builder. For instance the Dynamic Data Dropdown takes:
the HTTP URI of a service returning an XML document with the items shown in the drop-down,
an XPath expression extracting the items from the XML document,
and two XPath expressions returning the label and value for each item.
You can create a custom user interface within Form Builder for XBL component that require such additional properties by adding XForms controls under the the <fb:control-details> element, which you add under <fb:metadata>.
See also Custom control settings.
<fb:control-details> can contain any XForms control. This allows for more flexible layouts:
In addition, you can place an <xf:model>, which can be used for:
additional local instances
validation
event handlers
The content of <xf:model> is available to the control specified.
Example:
Implicitly, there is always a default instance accessible with instance(), which contains the control being edited.
The <fb:control-details> only supports <xf:input> controls. These are bound to attributes or elements inside the template you provided inside <fb:template>.
Example:
The text for control <xf:label>, <xf:hint>, <xf:help>, and <xf:alert>, can either be:
Inline, with a lang attribute indicating the language. This is what the author of the Dynamic Data Dropdown control did for the first <xf:input> above.
Taken from the Form Builder resource file, which is typically useful when your control uses resources that already exists elsewhere in Form Builder. In this case, you don't need to worry about what the current language is: Form Builder will automatically select the subset of the resource file that applies for the current language. This is what the author of the Dynamic Data Dropdown control did for the second <xf:input> above.
