#167

Product support

Visit this product's website for support.

Categories

  • Utility

This plugin allows end users to create, edit and submit forms in an easy-to-use front-end interface. It can therefore be used to implement an online application system, self-hosted surveys, or any other backend-like form in the frontend.

Features

  • Easy to use form manager
  • Renders OctoberCMS YAML forms in the frontend with support for relations and file uploads
  • Integrated passwordless email authentication
  • Other custom authentication methods possible, e.g. via Rainlab.User plugin
  • Option to restrict access to registered users only

User experience

To start a form submission, the user has to provide her email address and receives a link to sign into the form manager. The user can log out at any time and request another login link later.

The form manager displays available forms and instructions and allows the user to create and manage submissions. The user can fill the forms and save their work at any time. It is also possible to cancel and remove submissions. Once everything is filled and validated, the user can submit the form. At this point, modifications of the submitted content are not longer possible, but the user can still view the submitted data.

The manager supports opening and closing dates for forms. If activated, the user is only allowed to submit forms between the specified open to close time range. Furthermore, a countdown component can be used to display a countdown to the opening of a form.

Additional information

In future, the plugin might be extended to allow for

  • Developer API to render custom frontend forms
  • Upload improvements (e.g. file type validation)
  • link based access (like in Google Forms)
  • advanced submitter management
  • general user experience improvements
  • ...

If you find this plugin useful, please consider donating to support its further development.

The form configuration

The plugin currently includes two components: Manager and Countdown.

The Manager component

The manager component provides the main functionality and can be included in any CMS page that should serve as form manager. It is recommended to create a new CMS page since the page will be replaced with the form manager frontend once the user is logged in.

The Manager component has the following properties:

  • forms - [set] specifies the forms that users can manage
  • embedded - [checkbox] if activated the manager will be embedded into the page rather than replacing it
  • open_for_registration [checkbox] If disabled, only existing submitters can access the form
  • login_mail_template - [string] the email template of the login mail. Defaults to nocio.formstore::mail.login
  • save_warning - [checkbox] if enabled, the user will be reminded to save content regularly

The component will display the email login form and -- if the user is logged in -- displays the form manager. Note that if you activate embedded mode, only the form will be rendered. To provide a logout button, use the AJAX framework to query formManager::onLogout.

The Countdown component

The countdown provides information about the opening and closing time of a form. Its only property is the form and can be integrated into any CMS page. It provides the following information (accessible via __SELF__ in the plugin markup):

  • open - whether the form is currently open for submissions
  • closed - whether the closing date is past
  • opens - distance to the form's opening time with opens.days, opens.hours, opens.minutes and opens.date (Carbon instance)
  • closes - same as opens but for closing time
  • liftoff - contains the closing date if the form is open and the opening date otherwise

Configuring the forms

The available forms can be managed in the plugins backend under Stored forms.

It is important to understand that the plugin does not provide own form definitions or database models. Instead, existing models are used to define a form. To create your custom form, it is recommended to use the Builder plugin. Please refer to its documentation to learn how to create models and form definitions. Please note that not all backend widgets are supported. Moreover, the file upload widget has currently some limitations, i.e. insufficient validation.

Important: The model has to allow mass assignment for the fields that are present in the form. Refer to the model documentation for more information.

! WARNING ! Never specify any system models that could be used to compromise the system.

To create a form, the following fields are required:

  • Title - The form title
  • Model - The namespace path of the model that will be used to store the data, e.g. Rainlab\Blog\Models\Post.
  • Fields - Relative or absolute path to the fields YAML config file e.g. formstore_fields.yaml or $\Rainlab\Blog\Models\Post\fields.yaml

There are the following optional settings:

  • Maximum submissions per user - Allows restricting the number of submissions per user. Set to -1 for unlimited submissions.
  • Opening and closing time - Allows specifying a time range in which submissions will be allowed.
  • Introduction - An optional text with information or instructions for the form, that will be displayed to the user
  • Terms and conditions - An optional field to provide T&C the user has to agree to if starting a submission.
  • Validation - Optional OctoberCMS validation rules. If specified, the form cannot be submitted before the validation is passed.

Relations

If the form model defines relations, they can be activated under the Relations tab. To add a relation, another form with the related model has to be created. For example, if the specified form model is Rainlab\Blog\Models\Post that has a defined model relation comments there has to be another form, e.g. Comment form, with the related model, e.g. Vendor\MyRelatedModel\Comments. The relation can then be configured by selecting Comment form as form and comments as relation. Furthermore, a title and required minimum can be specified. As a result, the form manager will allow the user to add comments when working on a post and might require a minimum number of comments before the post can be submitted.

Activating forms in the manager

In order to work, the configured form has to be activated in a manager's forms option in a CMS page.

Viewing submissions and submitters

The backend also allows to view and manage submissions and submitters. Note that is only possible to view but not manipulate submissions. It is, however, very easy to add an edit functionality for the model using the mentioned Builder plugin.

Events

It is possible to hook into the submission cycle at the following events:

  • nocio.formstore.withdraw($submission) - when a submission is withdrawed
  • nocio.formstore.submit($submission): - when a submission is submitted
  • events to override the authentication method - see below

The events can, for instance, be used to send an email notification when a user submits a form:

Event::listen('nocio.formstore.submit', function($submission) {
    Mail::sendTo('[email protected]', 'nocio.blog::mail.submission_notice', [
        'submission' => $submission
    ]);
});

Custom authentication methods

It is possible to override the default authentication mechanism and use other options instead. In the following example, the Rainlab.User plugin will be used to authenticate the user.

First it is necessary to provide a custom submitter object with the following (duck-typed) properties:

  • email property - The email of the submitter
  • submissions relation - hasMany model relation to Nocio\FormStore\Models\Submission

In the case of the User plugin, we can simply extend the User model, which already provides the email field

\Rainlab\User\Models\User::extend(function($model) {
    $model->hasMany = [
        'submissions' => [
            'Nocio\FormStore\Models\Submission',
            'key' => 'submitter_id'
        ]
    ];
});

Next, we have to override the authentication methods, that return the current submitter/user object and its state. The event has to return an array with the user object and the current authentication state (true for logged-in), e.g.

/**
 * Authenticates the user
 * @return array[ (object) submitter, (boolean) authenticated ]
 */
Event::listen('nocio.formstore.authenticate', function($alias) {
    if ($user = Auth::getUser()) {
        return [$user, true];
    } else {
        return [$user, false];
    }
});

Finally, it is possible to adjust the logout function ...

/**
 * Log the user out
 */
Event::listen('nocio.formstore.logout', function($alias) {
    Auth::logout();
    return true;
});

... and the behaviour when the authentication was unsuccessful, e.g. redirect the user to the login page:

Event::listen('nocio.formstore.not_authenticated', function($alias) {
        return Redirect::to('/login');
});

Note, that the events take the alias of the formManager component as a parameter, allowing you to override the authentication for specific manager instances.

Support & Contribution

I can only offer limited support but will try to answer questions and feature requests on GitHub. I am also happy to accept pull requests, especially for the missing features list on the Plugin details page.

Please consider donating to support the ongoing development if you find this plugin useful.

Acknowledgements

Thanks to the Uploader plugin which code base was adapted to implement the file upload of the form manager.

  • Found the plugin useful on 13 Nov, 2017

    Hi, please I love your work, am a newbie. If a user is logged in will they still need links to access forms.

    And can I use the form to manage users posts and even profile.

  • author

    Replied on 17 Nov, 2017

    Hi Ernest,

    I'm glad that you like my work.

    If a user is logged in will they still need links to access forms?

    Once the user is logged in, the link is not needed any longer, as the authentication is stored in a cookie. Whenever the user navigates to the URL of the FormStore portal he will be recognised without the need to request and follow a login link again.

    And can I use the form to manage users posts and even profile?

    You can use FormStore to manage any backend model; that includes posts and profile as long as there is a model (i.e. the post and profile information is actually stored in the database).

    I hope that helps, if you have more question or run into trouble feel free to open an issue on GitHub where I'm generally more responsive.

1.1.9

Hide menu item from users with insufficient permissions

Oct 24, 2017

1.1.8

Minor UI improvements

Jul 08, 2017

1.1.7

Read-only filelist improvements

Jun 20, 2017

1.1.6

belongsTo relation support and UI improvements

Jun 10, 2017

1.1.5

Adding support for relation dropdown

Jun 09, 2017

1.1.4

Adding submitter email export

Jun 09, 2017

1.1.3

Adding countdown.closed state

Jun 09, 2017

1.1.2

Added not_authenticated event

May 18, 2017

1.1.1

New option to restrict submission to existing submitters only

May 18, 2017

1.1.0

!!! New embedding option might require adjustments of the manager component markup. Refer to the upgrade guide for more information.

May 18, 2017

1.0.6

Fix incorrect redirection of login email validation

May 17, 2017

1.0.5

Created table nocio_formstore_relations

May 12, 2017

1.0.4

Created table nocio_formstore_submitters

May 12, 2017

1.0.3

Created table nocio_formstore_submissions

May 12, 2017

1.0.2

Created table nocio_formstore_forms

May 12, 2017

1.0.1

Initialize plugin.

May 12, 2017

Upgrade guide

<a name="upgrade-1.1"></a>

Upgrading To 1.1

In order to allow for embedding of forms in existing pages the default markup of the manager component slightly changed.

If you customized the markup (and only then), you have to adjust it after the upgrade by wrapping it with the following code:

{% if not formstoreManager.authenticated %}

    ... your adjusted markup goes here ...

{% else %}

    {{ formstoreManager.app | raw }}

{% endif %}

In this way, the form manager formstoreManager.app will be embedded into the page if the component property embedded is enabled.

Refer to the documentation to learn more about the new features.