Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[UX] Change how the ways to implement a form are called #258

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions docs/components/forms.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ To create a new Form:
#. Go to Components > Forms and click New
#. Select the type of Form you wish to create
* **Campaign Form** - Mautic allows you to trigger a Campaign with the submission of this type of Form. Campaign Forms have less actions directly associated with the Form submit actions - which happen immediately after Form submission - as most actions trigger as part of a Campaign workflow.
* **Standalone Form** - A more commonly used Form, this allows the execution of many submit actions immediately at the point of Form submission.
* **Standalone Form** - A more commonly used Form, this allows the execution of many submit actions immediately at the point of Form submission.

.. warning::
.. warning::
Forms with a lot of submit actions - particularly when submitting to third party systems such as a Customer Relationship Management system - can have an impact on the Form submission time. This is especially the case if there are a lot of fields. Consider using a Campaign Form if you can wait for the cron job to trigger the actions.

The following fields are available:
Expand All @@ -42,7 +42,7 @@ The following fields are available:

- **Theme** - Select a Mautic Theme which has styling for a Form. This dictates the styling of the Form when added to an external website or Application if 'Render style' is Yes.

.. note::
.. note::
Not all Themes include Form styling. Check the Features column on your Themes listing in the Theme Manager to see which Themes include styling for Forms.

.. vale off
Expand Down Expand Up @@ -85,7 +85,7 @@ To add a new field to your Form:

- **Checkbox Group** - This field allows a visitor to select one or more options from a list using checkboxes. This field type can also provide a single checkbox - for example to gain consent to use cookies and send marketing Emails or other messages to the Contact.

.. note::
.. note::
You can associate checkbox group fields with *boolean* and *select - multiple* fields, but not *select* fields.

- **Date** - This field allows the visitor to select a date with a calendar picker. The formatting of the date applies the default setting in your Configuration.
Expand All @@ -98,7 +98,7 @@ To add a new field to your Form:

- **File** - This allows visitors to upload a file on the Form.

.. warning::
.. warning::
When using the file upload field there is a limit of 1,000 submissions using the same filename. Note that you can attach the submitted files in the "Send Form result" action.

- **HTML area** - This field allows marketers to add custom HTML to their Form.
Expand Down Expand Up @@ -186,9 +186,9 @@ CAPTCHA
:width: 600
:alt: Screenshot showing CAPTCHA Form properties

With a CAPTCHA field, the answer field should be blank if you are using this as a honeypot to trap spam submissions. This hides the field, and spambots try to populate the field with data.
With a CAPTCHA field, the answer field should be blank if you are using this as a honeypot to trap spam submissions. This hides the field, and spambots try to populate the field with data.

Mautic recognizes if there's data in a honeypot CAPTCHA field and understands that it can't be a human submitting the Form.
Mautic recognizes if there's data in a honeypot CAPTCHA field and understands that it can't be a human submitting the Form.

To have a human answer a basic question or statement - for example ``What's 2+2`` or ``Enter 'CAPTCHA' here`` - you would enter the expected input in the answer field, in this case, ``4`` or ``CAPTCHA``. The field's label should be the question, or you can use the label CAPTCHA and then have the question as the input placeholder.

Expand Down Expand Up @@ -233,16 +233,16 @@ When uploading a file within a Form there are several options under the properti
Attributes
~~~~~~~~~~

Attributes are CSS tags which change the styling of a particular Form.
Attributes are CSS tags which change the styling of a particular Form.

.. note::
.. note::
Setting the Render Style to No on the Form means that Mautic ignores the styling in these fields.

.. image:: images/forms/checkbox_group_attributes.png
:width: 600
:alt: Screenshot showing the attributes for a checkbox group

- **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Manual Copy function to manually add the Form to your website or app.
- **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Self-hosted function to manually add the Form to your website or app.
- **Label attributes**: this field changes the way the label text appears. You should use the format ``style="attribute: descriptor"`` to change the style. For example, to change the label to red, use ``style="color: red"`` or ``style="color: #ff0000"``.
- **Input attributes**: changes the way any text inside the Form Field appears. This applies to the input placeholder text, text entered by the visitor submitting the Form, and the options for the select fields when Allow Multiple is Yes - including List - Country.
- **Field container attributes**: this changes the Form Field. Use this to change the size of the box, fill color, rounded edges, or any other properties of the actual field.
Expand Down Expand Up @@ -319,7 +319,7 @@ Form actions

You may want to trigger certain actions to happen immediately after Form submission - this is what Form actions are for. This might include communications with the Contact, tracking, internal notifications, or other Contact management tasks.

.. note::
.. note::
The Form actions available in Mautic are also available in Standalone Forms, which include more options as they're not associated with Campaigns. Campaigns tend to trigger most actions through Campaign actions so Forms associated with Campaigns only have a basic set of Form actions.

- **Add to Company's Score**: if a Contact associated with a Company record in Mautic has submitted the Form, you can add or subtract Points to the Company's overall score. Company scoring in Mautic doesn't aggregate Points for all its associated Contacts. Any actions that you want to contribute to a Company's score must be explicitly set. Negative numbers are valid if you want to subtract from a Company's score based on a Contact submitting a Form. If the Contact isn't tracked and the Form doesn't include a field mapped to Company or Company Name - on the Company object - the Company has no Points awarded.
Expand All @@ -334,7 +334,7 @@ You may want to trigger certain actions to happen immediately after Form submiss
:width: 600
:alt: Screenshot showing the adjust Contact score Form action.

- **Modify Contact's Segments**: this action allows you to change a Contact's Segment membership when they submit a Form. Type in the name of the Segment to add the Contact to or remove the Contact from. You can use both fields at the same time, and can include multiple Segments in either or both fields.
- **Modify Contact's Segments**: this action allows you to change a Contact's Segment membership when they submit a Form. Type in the name of the Segment to add the Contact to or remove the Contact from. You can use both fields at the same time, and can include multiple Segments in either or both fields.

Dynamic Segments based on filters update based on information in the Contact record automatically - you don't need add them to the Segment in a Form action.

Expand Down Expand Up @@ -406,7 +406,7 @@ You can style the message itself as you like, and you can click to insert the su

.. image:: images/forms/send_form_results.png
:width: 600
:alt: Screenshot showing the send Form results action.
:alt: Screenshot showing the send Form results action.

.. vale off

Expand All @@ -429,20 +429,20 @@ When working with Mautic Landing Pages or common Content Management Systems (CMS
- **Mautic Landing Page**: ``{form= ID#}``
- **Drupal 7.x**: ``{mauticform id =ID# width=300 px height=300 px}`` - be sure to change the width and height to the appropriate size for your website.

.. warning::
This shortcode doesn't work for Drupal 8.x - it's recommended to use the Automatic Copy option instead.
.. warning::
This shortcode doesn't work for Drupal 8.x - it's recommended to use the Embedded option instead.

- **Joomla!**: ``{mauticform ID#}``
- **WordPress**: ``[mautic type="form" id=ID#]``

Automatic copy
Embedded
==============

.. image:: images/forms/embed_form.png
:width: 600
:alt: Screenshot showing the options for embedding a Mautic Form.
:alt: Screenshot showing the options for embedding a Mautic Form.

The Automatic option for embedding Mautic Forms uses JavaScript and ensures that the Forms on your website are always up to date with what you have set in Mautic. If you make changes to the Form in Mautic, you don't have to worry about re-copying the Form code everywhere you use the Form. Features including auto-fill and progressive profiling **only** works with the Automatic option.
The Embedded option for embedding Mautic Forms uses JavaScript and ensures that the Forms on your website are always up to date with what you have set in Mautic. If you make changes to the Form in Mautic, you don't have to worry about re-copying the Form code everywhere you use the Form. Features including auto-fill and progressive profiling **only** works with the Embedded option.

.. note::
Before copying the code to embed your Mautic Forms, ensure that you are on the correct domain name - not a staging area or internal reference for example - as the Form embed code references the URL.
Expand All @@ -461,16 +461,16 @@ Via IFrame

IFrames can be more difficult to use, and blocking by browsers is more likely, however there are sometimes where using an IFrame is preferable. Be sure to adjust the width and height for the space required to fit the Form. The visitor may need to scroll within the IFrame depending on the resolution of their browser. It's possible to display an error message in the event that the visitor's browser doesn't support IFrames, by editing the text between the ``<p>`` and ``</p>`` tags before copying the code and pasting it into your website.

Manual copy
Self-hosted
===========

.. image:: images/forms/embed_form_manual.png
:width: 600
:alt: Screenshot showing the options for manually embedding a Mautic Form.
:alt: Screenshot showing the options for manually embedding a Mautic Form.

The manual copy option does provide more flexibility to extend Forms with JavaScript snippets and custom styling, however it's a manual process and any changes made within Mautic after copying the code won't be automatically reflected on your website unless you re-copy and paste the new HTML code.
The Self-hosted option does provide more flexibility to extend Forms with JavaScript snippets and custom styling, however it's a manual process and any changes made within Mautic after copying the code won't be automatically reflected on your website unless you re-copy and paste the new HTML code.

.. note::
.. note::
Before copying the code to embed your Mautic Forms, ensure that you are on the correct domain name - not a staging area or internal reference for example - as the Form embed code references the URL.

#. Copy the JavaScript code in the first box, and paste it into the head or body of your page. If you have multiple Mautic Forms on the same page, add this once only.
Expand Down Expand Up @@ -505,7 +505,7 @@ Adding conditional fields to a Mautic Form

Once you have created the required Custom Fields, add the parent field to the Form as detailed previously, and add the relevant information in the tabs.

.. note::
.. note::
When using conditional fields, only ``Select``, ``Select - Multiple`` and ``Boolean`` field types are valid as the parent field.

.. image:: images/forms/conditional_fields_1.png
Expand All @@ -530,7 +530,7 @@ In this example, select the ``Checkbox Group`` option, and under the Condition t
:width: 600
:alt: Screenshot showing selection of parent field

This means that when the visitor selects Ford, the Form displays this field.
This means that when the visitor selects Ford, the Form displays this field.

There are two options:

Expand Down
Binary file modified docs/components/images/forms/embed_form.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/components/images/forms/embed_form_manual.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading