# Modules Modules allow developers to create encapsulated module bundles that alter the behavior of the Form.io Builder and Renderer. The Form Module is located within your Stage settings.
Modules were introduced in formio.js v4.5.0. You need a version later than that to utilize modules. The Form.io Renderer allows for a number of plugins, which allows for external libraries the ability to alter the behavior of this library. Each plugin is defined in a module using a simple key-pair map like the following illustrates. ``` { components: {...}, templates: {...}, providers: {...}, displays: {...} } ``` The following plugins can be provided within a module. | Plugin | Description | | ---------- | ----------------------------------------------------------------------------------------------- | | components | Allows for Custom Components to be introduced into the renderer. | | templates | Allows for you to introduce new templates and CSS frameworks (such as Bootstrap, Semantic, etc) | | providers | Allows for custom storage providers for file components | | displays | Provides a way to provide new and override the form renderer displays. | | builders | Provides a way to provide new and override the form builders | | options | Allows a way to override options passed into the renderer and the builder. | | fetch | Provides a way to intercept all API requests made into the Form.io renderer. | | framework | Allows for the CSS framework to be forced when loaded. | ## Creating a module New modules can be created by including an external Library within your application that has exports the following structure. ``` export default { framework: 'semantic', // Sets the default template to a specific framework. components: { /* List of custom components */ }, templates: { semantic: { /* List of templates found @ https://github.com/formio/formio.js/blob/master/src/templates/bootstrap/index.js */ } }, fetch: { fetchname: CustomFetchPluginClass } } ``` Each of the keys within this object are called Plugins and they each have their own object definitions as follows ## Using a Module Once you have a module created, it is very easy to use the module within the Form.io renderer. You simply import the module, and then use the `Formio.use` method to use it. The following is an example of how a module is used. ``` import { CustomModule } from './modules/custom'; Formio.use(CustomModule); ``` ## Module plugins A module consists of a bunch of plugins that are provided to the module via the "name" of the plugin. The following plugins are available for modules. ### framework This sets the default "style" framework. ***Example*** ``` { framework: 'semantic' } ``` ### components Provides a way to override existing components, or introduce new components to the renderer/builder. Here is a simple of example of adding a new component. #### components/CustomButton.js ``` import { Components } from 'formiojs'; const ButtonComponent = (Components as any).components.button; class CustomButton extends ButtonComponent { get inputInfo() { const inputInfo = super.inputInfo; inputInfo.attr.class += ' custom-button'; return inputInfo; } } ``` #### module.js ``` import { CustomButton } from './components/CustomButton.js'; export default { components: { button: CustomButton } } ``` For an example of a custom component module, take a look at the [**Contrib Module**](https://github.com/formio/contrib) ### templates Introduces new templates to the renderer for use with custom components or for overriding existing templates. See [**Form Templates**](https://help.form.io/developers/form-development/form-templates) section for more details. ### fetch Allows a custom "fetch" plugin to be utilized for this renderer. All API requests will then be sent through this fetch plugin instead of the default Formio.fetch interface (which is the standard Web fetch interface). For detailed documentation, please see the [**Fetch Plugin API**](https://help.form.io/developers/fetch-plugin-api) documentation. ### providers Allows the introduction of different providers as follows. | Provider | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | storage | Storage providers allow file upload interfaces. Such as Azure Blob, Dropbox, etc. For examples, go to [**https://github.com/formio/formio.js/tree/master/src/providers/storage**](https://github.com/formio/formio.js/tree/master/src/providers/storage) | | auth | Authentication providers such as Okta, OAuth, SAML, etc. For examples, go to [**https://github.com/formio/formio.js/tree/master/src/providers/auth**](https://github.com/formio/formio.js/tree/master/src/providers/auth) | | address | Address providers such as Google Maps, Open Street Maps, etc. For examples, go to [**https://github.com/formio/formio.js/tree/master/src/providers/address**](https://github.com/formio/formio.js/tree/master/src/providers/address) | ### displays Introduces new or overrides existing Display interfaces, such as Wizard, Form, or PDF ### rules Introduces new or overrides existing validation rules. Coming soon. ### options Allows the overriding of Form and Builder options. Must be in the following format. ``` { options: { form: {}, /* Provides the default options for Formio.createForm */ builder: {} /* Provides the default options for Formio.builder */ } } ``` See [Form Options](https://help.form.io/form-development/form-renderer#form-renderer-options) and [Builder Options](https://help.form.io/form-development/form-builder#form-builder-options). ### Register a module To register the module into the renderer, you must use the `use` method, whereas you will pass the Module definition into this method. **Example** ``` import MyModule from './MyModule'; import { Formio } from 'formiojs'; Formio.use(MyModule); ``` ### Existing Modules * [**Contrib Components**](https://github.com/formio/contrib) * [**United States Web Design System**](https://github.com/formio/uswds) * [**Bootstrap 3 Template**](https://github.com/formio/bootstrap3) * [**Semantic UI Template**](https://github.com/formio/semantic) * [**Bulma Template**](https://github.com/formio/bulma)