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):
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:
Control metadata for the markup to insert in the form
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:
Control metadata for the Control Settings dialog
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>.
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.