# Custom Forms ## Introduction
Example Custom Form with Validation
{% hint style="warning" %} A form will only ever display in a **modal window**. You have control over the max width of the form but you can't control its position on the page. It always be displayed in the center of the page. {% endhint %} Although you can capture any input via dialog through the course of conversation it can be more familiar and user friendly to display a traditional form to a user at a key point of a conversation. Having this option in Leopard doesn't force the use or display of custom forms in any solution but rather provides flexibility in confirming or capturing information outside of lengthy conversations. You have great control of the form structure, appearance, behavior, initial values and validation rules. {% hint style="success" %} `ExtensionHelper` is **NOT** currently used to provide helper functions to generate the JSON structure needed by Leopard to render forms. **You are more than welcome to create and contribute some if you're up for it.** It should however be straight forward to construct your necessary JSON based form config using the guidance and examples provided. Sensible defaults are set for the bulk of the form config options so the final JSON can be very slim if you are happy with the defaults. It's worth while to use a online [JSON validator](https://jsonformatter.org/) before committing your final **`formConfig`** JSON in Teneo. {% endhint %} ## Behavior A custom form is currently tied directly to the respective output node that returned the "formConfig" as an output parameter. This means that the form button against that response will be displayed in the chat dialog until the user completes the form and submits it back to Teneo. At that point the form button in the chat UI is removed from that particular response. {% hint style="info" %} Current configuration is that the same form and button can be displayed in new responses if new dialog takes you there. If you want to prevent the offer of a custom form that has already been submitted then that logic needs to be engineered server side in Teneo around the "postback" data that is posted back to Teneo on a successful submission. {% endhint %} The form button can remain visible in the dialog until it's completed and submitted back. Therefore you should configure the "postback" information of the form to align with your flow strategy for capturing and responding to the data posted back Teneo. At present a user isn't forced to complete a form in the current turn of the active conversation. Therefore you should plan accordingly in Teneo. {% hint style="warning" %} Custom Forms will operate both in "**Demo**" mode as well as "**Production**" embedded mode. Due to the current implementation of Leopard in production the form will only be overlaid over the chat UI area of the chat client. It will not be centered and wide as it is in development mode. Therefore if you plan to use custom forms in a production install of Leopard you should expect your form to render in a smaller and narrower area. {% endhint %} ## Output Parameter ```javascript formConfig = { "title" : "My Custom Form", "fields" : [ { "header" : { "label" : "Please enter in your email address" } }, { "textInput" : { "name" : "username", "label" : "Email", "hint" : "Just the username part please", "initialValue" : "jolzee", "placeHolder" : "username", "style" : { "solo":true }, "clearable" : true, "persistentHint" : true, "icons" : { "appendOuter":"email-edit" }, "suffix" : "@gmail.com", "validations" : "required" } }, { // ... other fields } ] } ``` {% hint style="info" %} A more comprehensive example can be [found here](https://jolzee.gitbook.io/leopard/components/forms-1/forms/example-config) {% endhint %} ## Form Config Component Configuration | Element | Required/Optional | Default Value | Type | Notes | | ---------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | `required` | | String | The form's title | | validationFailedMessage | optional | Please complete all required fields | String | A custom message to be displayed once a user submits the form and there are validation errors | | openAutomatically | optional | false | Boolean | Controls if the form should automatically open for the Teneo response that contains the formConfig | | openFormButtonText | optional | Form | String | Set the button text to open the form. Seen just below the answer text. | | [postback](https://jolzee.gitbook.io/leopard/components/forms-1/forms/postback) | optional | [Postback Object](https://jolzee.gitbook.io/leopard/components/forms-1/forms/postback) | Object | Controls what is send back to Teneo on a successful submission of the form | | [button](https://jolzee.gitbook.io/leopard/components/forms-1/forms/button) | optional | [Button Object](https://jolzee.gitbook.io/leopard/components/forms-1/forms/button) | Object | Controls the display of the button used in the form to complete the form submission | | [`fields`](https://jolzee.gitbook.io/leopard/components/forms-1/forms/field-types) | `required` | [Field Objects](https://jolzee.gitbook.io/leopard/components/forms-1/forms/field-types) | Array of Field Type Objects | Allows you to add as many of the available [fields](https://jolzee.gitbook.io/leopard/components/forms-1/forms/field-types) in a specific order | {% content-ref url="forms/example-config" %} [example-config](https://jolzee.gitbook.io/leopard/components/forms-1/forms/example-config) {% endcontent-ref %} {% content-ref url="forms/postback" %} [postback](https://jolzee.gitbook.io/leopard/components/forms-1/forms/postback) {% endcontent-ref %} {% content-ref url="forms/button" %} [button](https://jolzee.gitbook.io/leopard/components/forms-1/forms/button) {% endcontent-ref %} {% content-ref url="forms/field-types" %} [field-types](https://jolzee.gitbook.io/leopard/components/forms-1/forms/field-types) {% endcontent-ref %} {% content-ref url="forms/style" %} [style](https://jolzee.gitbook.io/leopard/components/forms-1/forms/style) {% endcontent-ref %} {% content-ref url="forms/icons-object" %} [icons-object](https://jolzee.gitbook.io/leopard/components/forms-1/forms/icons-object) {% endcontent-ref %} {% content-ref url="forms/masks" %} [masks](https://jolzee.gitbook.io/leopard/components/forms-1/forms/masks) {% endcontent-ref %} {% content-ref url="forms/validation" %} [validation](https://jolzee.gitbook.io/leopard/components/forms-1/forms/validation) {% endcontent-ref %} ## --- # 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://jolzee.gitbook.io/leopard/components/forms-1/forms.md?ask= ``` 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.