finanalyst / grav-plugin-tingle-form

Grav plugin to create a popup form

Tingle Form Plugin

The Tingle Form Plugin is for Grav CMS. A standard GRAV form is included inside a tingle modal popup. Click on a button (created with a shortcode) and the form pops up. If a submit button is pressed on the form, it will be processed and the form disappears.

Installation

Installing the Tingle Form plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.

GPM Installation (Preferred)

The simplest way to install this plugin is via the Grav Package Manager (GPM) through your system's terminal (also called the command line). From the root of your Grav install type:

bin/gpm install tingle-form

This will install the Tingle Form plugin into your /user/plugins directory within Grav. Its files can be found under /your/site/grav/user/plugins/tingle-form.

Manual Installation

To install this plugin, just download the zip version of this repository and unzip it under /your/site/grav/user/plugins. Then, rename the folder to tingle-form. You can find these files on GitHub or via GetGrav.org.

You should now have all the plugin files under

/your/site/grav/user/plugins/tingle-form

NOTE: This plugin is a modular component for Grav which requires Grav and the Error, Form and Problems plugins to operate.

Admin Plugin

If you use the admin plugin, you can install directly through the admin plugin by browsing the Plugins tab and clicking on the Add button.

Configuration

Before configuring this plugin, you should copy the user/plugins/tingle-form/tingle-form.yaml to user/config/plugins/tingle-form.yaml and only edit that copy.

Here is the default configuration and an explanation of available options:

enabled: true

Note that if you use the admin plugin, a file with your configuration, and named tingle-form.yaml will be saved in the user/config/plugins/ folder once the configuration is saved in the admin.

Usage

A standard default.md file (eg., as defined for the Quark theme) can be used. A form is defined in the page header (or elsewhere, see Form plugin documentation). The [popup-form] shortcode is placed in the content file, which creates a button that when clicked pops up the form content in a modal window.

Shortcode and options

[popup-form form=<formname> <other options>]<Button text>[/popup-form]
The parameter and options are:

1. Button text is the label to be placed on the popup button. It defaults to 'Click for form'.
2. form - This is mandatory and is the name of the form to be wrapped in the modal. If no form option is present, an error div is generated.
3. closeText - an option for the Tingle code. It labels the close button for a mobile. On a PC the value is 'x'. Defaults to 'Close'.
4. classes - a string containing a comma delimited sequence of strings. Each sub-string is a class that will be added to the div wrapping the modal. It offers a way of customising the css.
5. btnClass - This string is added to the class attribute of the button calling the popup. It defaults to 'btn', which is the generic button class for the Quark theme.

The form is defined as given by the Form plugin documentation. It should contain at least one Submit button. When a Submit button is clicked, the form action is initiated and the form is removed.

Example

This is the content of user/pages/10.tingleform/default.md file with a Button to popup a form defined in the file.

---
title: TingleForm
forms:
    APopupForm:
        action: /tingleform
        fields:
            - name: subject
              type: text
              label: Subject of message
              placeholder: Write your subject here
            - name: return
              type: email
              label: Return email address
              validate:
                required: true
                message: Please include a return address
            - name: content
              label: Content of the message
              type: textarea
              placeholder: Say something nice
              validate:
                required: true
                message: You have not sent a message
        buttons:
            - type: Submit
              value: Send this Email
            - type: Reset
              value: Reset the form
        process:
            - save:
                fileprefix: contact-
                dateformat: Ymd-His
                extension: txt
                body: "{% include 'forms/data.txt.twig' %}"
            - reset: true
---
# A page with a button

[popup-form form=APopupForm classes=" 'myclass1', 'myclass2' "]Click on Me[/popup-form]

Notes

1. This example contains functionality described in the Form plugin. If an email is required, then the Email plugin needs to be installed.
2. The form parameter is mandatory and is the name of the Form defined in the frontmatter.
3. The optional classes parameter contains a string that is provided without filtering to the tingle cssClass parameter, which expects comma deliminated sequence of strings. Consequently it must be in the from " 'class1' [ , 'class2'] ". These classes are added to the tingle div.
4. If validation is required, and GRAV returns the form with a <div class="toast-error"> containing validation error messaging, then the tingle form will be popped up automatically.

Modular pages.

This plugin works with modular pages. The following is the content of user/pages/08.modular/05._tingleitem/text.md (using the Quark theme)

---
title: TingleItem
forms:
    APopupForm:
        action: /modular#tingleitem
        fields:
            - name: subject
              type: text
              label: Subject of message
              placeholder: Write your subject here
            - name: return
              type: email
              label: Return email address
              validate:
                required: true
                message: Please include a return address
            - name: content
              label: Content of the message
              type: textarea
              placeholder: Say something nice
              validate:
                required: true
                message: You have not sent a message
        buttons:
            - type: Submit
              value: Send this Email
            - type: Reset
              value: Reset the form
        process:
            - save:
                fileprefix: contact-
                dateformat: Ymd-His
                extension: txt
                body: "{% include 'forms/data.txt.twig' %}"
            - reset: true
---
# A page with a button

[popup-form form=APopupForm]Click on Me[/popup-form]

Notes

1. The action field in the form is critical. It is 'modular' because that is the name of the route.
2. #tingleitem may be omitted, in which case after the form has been processed and disappears, the focus will return to the top of the modular page. By including #tingleitem, which is defined by the route associated with the text.md file, the focus returns to the position of the tingle-form on the page.

Credits

• Robin Parisi, the tingle developer.
• krzysztofgal, who wrote the GravGdprPrivacySetupPlugin, for inspiration.
• Martin Zbinden (http://riedackerhof.ch/), for dependency check.

To Do

grav-plugin-tingle-form's Issues

popCont needs setting to raw

Hi, this wasn't working for me until I set popCont to raw in the template.

{{ tform }}_Modal.setContent('{{ popCont|raw }}');

instead of

{{ tform }}_Modal.setContent('{{ popCont }}');

New parameter(s) for shortcode

Add a parameters with calculated value (or better, an arbitrary number of parameters with a wildcarded name pattern like <NAME>*) to pass additional data from the page context to the popup form for post-processing it it

Use case: I have tingleform, called more than 1 time on single page and want to see directly in received message (without GTM on top of site), which button from a set was clicked. I can detect it in page's DOM, but can't now pass calculated on the fly value to form

strange rendering for button

Something went wrong with the button rendering.
In Markdown page (Quark default.md) I use Open [popup-form form="APopupForm"]a modal form[/popup-form] but the output in HTML is: </temporary-tag> (see screenshot).

Shortcode Core v5.1.1
Grav 1.7.31

400 - Display page not found. Please check the page exists.

Plugin seem to work great, but getting this error on submit. Do we need to tell the form to return to the current route?

Sorry for the newbie questions. Just started playing around with Grav.

Custom HTML not processed in button label

[popup-form...]Contact Us[/popup-form] with plain-text only work as expected, but even bits of HTML like [popup-form...]<span class="fa fa-envelope"></span> Contact Us[/popup-form] will output HTML-code "as is", without converting to FA-icons

Success alert

Is there any way to show a "Your message has been sent" response?

Missing dependency: grav-plugin-shortcode-core

This plugin should be installed automatically for shortcode to work.

Is it possible to place a modal popup without shortcode? As a url per example?