# XBL components

## Children pages

* [FAQ](/xforms/xbl/faq.md)
* Guide
  * [Tutorial](/xforms/xbl/guide/tutorial.md)
  * [Bindings](/xforms/xbl/guide/bindings.md)
  * [XForms models](/xforms/xbl/guide/xforms-models.md)
  * [Including content](/xforms/xbl/guide/including-content.md)
  * [Event handling](/xforms/xbl/guide/event-handling.md)
  * [Conventions](/xforms/xbl/guide/conventions.md)
  * [Map XBL example](/xforms/xbl/guide/example-map.md)
  * [Learning from existing components](/xforms/xbl/guide/learning-from-existing-components.md)
* Advanced topics
  * [Modes](/xforms/xbl/advanced-topics/modes.md)
  * [JavaScript companion classes](/xforms/xbl/advanced-topics/javascript.md)
  * [XBL library](/xforms/xbl/advanced-topics/library.md)
  * [Extensions](/xforms/xbl/advanced-topics/extensions.md)
  * [Attachment controls](/xforms/xbl/advanced-topics/attachments.md)

## Why are components needed?

The Orbeon Forms XForms engine proposes out of the box a set of controls, including input fields, radio buttons, etc. Those are typically implemented natively within the XForms engine.

Beyond the basic set of controls, there is an obvious need for creating new reusable controls. It would be difficult to modify the XForms engine itself each time a new control is needed. Orbeon Forms therefore supports a complete framework inspired by the [XBL 2](http://www.w3.org/TR/xbl/) specification to address this need.

*NOTE: The XBL 2 specification is no longer under development at W3C, but as of 2015* [*Web Components*](http://webcomponents.org/) *embody most of the ideas of XBL 2, including custom elements, the shadow DOM, and strong encapsulation.*

## Use cases

You can use components to implement:

* Controls for datatypes which have a native implementation, but where a custom appearance is required
  * Example: A custom control for entering a date with dropdown menus rather than a date picker
* Controls for datatypes which do not have a native implementation
  * Example: A control to capture the `xs:duration` type
* Controls which do not have a standard XML type
  * Example: A phone number control
* Controls which wrap existing controls
  * Example: A [character counter component](/form-runner/component/character-counter.md)
* Higher-level components
  * Examples:
    * A [form grid component](/form-runner/component/grid.md)
    * A [wizard component](/form-runner/component/wizard.md)
* Components which implement a completely new control based on a JavaScript library
  * Example: A [map component](https://github.com/orbeon/orbeon-forms-doc/blob/master/form-runner/component/map.md)

This is not an exhaustive list. Your imagination is the limit!

You might want to also check the [components](/form-runner/component.md) provided out of the box by Orbeon Forms.

## Terminology

* **Component or custom control:** a piece of software which provides reusable behavior and presentation.
* **Component instance:** a particular use of a component within an XForms document. A component might have multiple instances in a given page.
  * *NOTE: This should not be confused with XForms instances.*
* **Component implementation:** the code which constitutes the inner workings of a particular component.
* **Component author:** the person who writes a component.
* **Component user:** the person who uses a component.
  * In general, *writing* a component will be harder than *using* one.
  * Obviously the user can be the same as the author!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/xforms/xbl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.