Download the PHP package xpertbot/craft-wheelform without Composer
On this page you can find all versions of the php package xpertbot/craft-wheelform. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download xpertbot/craft-wheelform
More information about xpertbot/craft-wheelform
Files in xpertbot/craft-wheelform
Package craft-wheelform
Short Description Craft CMS 5 Form administrator with Database integration
License MIT
Informations about the package craft-wheelform
Wheel Form plugin for Craft CMS 5.x
Free Form Builder with Database Integration, successor of Free Contact Form Plugin featured on Straight Up Craft
Craft CMS 4.x
Use composer require xpertbot/craft-wheelform "^3.2"
Craft CMS 3.x
Use composer require xpertbot/craft-wheelform "^2.7"
Requirements
This plugin requires Craft CMS 5.0.0 or later
Installation
To install the plugin, follow these instructions.
-
Open your terminal and go to your Craft project:
cd /path/to/project
-
Then tell Composer to load the plugin:
composer require xpertbot/craft-wheelform
- In the Control Panel, go to Settings → Plugins and click the “Install” button for Wheel Form.
Features
- reCaptcha Validation
- Export CSV File
- Custom Email HTML Template
- Template variables for easy development
- Email Validation based on field type selected
- Form Field Type for sections
- Required Fields
- Checkbox options
- File extension restriction
- Honeypot Field
- Ajax and Redirect friendly
- Send Form submissions to multiple emails
- Advanced Permissions per form
- Reordering of fields
- Save Uploaded files to Asset Manager
- Multiple Translations
- Export / Import Fields between different websites
- Dynamic email notifications
Usage
After successful installation go to Plugin Settings and add the email you would like the forms to send FROM
. As well as set other useful settings.
Forms are administered at the forms panel main settings. Set where this form should be submitting TO
as well as name of the form.
Field Settings can be set as Required or not, for validation purposes.
Current Field types supported are:
- Text
- Textarea
- Number
- Checkboxes
- Radio
- Select
- Hidden
- File
- List
- HTML
Template Variables
-
wheelform
- settings
- form
- recaptcha
- open()
- close()
- fields
- type
- name
- label
- items
- fieldClass
- containerClass
- required
- order
- value
- options
- displayLabel
- entries
- id
- formId
- fields
- name
- label
- value
- type
- date
- getErrors()
- lastSubmission
- id
- formId
- fields
- name
- label
- value
- type
-
wheelformErrors (Array of errors based on field name, form, recaptcha, honeypot).
- values (Array of User submitted values based on field name).
Form Configuration Options
These are configuration opens you can pass to wheelform.form
to configure your form.
id
: Required ID of the form being used.redirect
: URL where form will redirect to after a successful submission.registerScripts
: Boolean to load Scripts beforewheelform.open
call (This is useful for caching forms and templates). Defaults to False.refreshCsrf
: Boolean to load Javascript that will refresh the CSRF token for the form on the current page (This is useful for caching forms and templates). In order for this to workform.open()
needs to be outside the{% cache %}
block.submitForm
: Configuration options for the submitButton. Example:
Form.open() parameter options
action
: String to overwritte where the form submits to. This is useful if you need to overwrite it with Javascript. Defaults to empty string.-
attributes
: {Key: Value} Array of Attributes for the current form. Defaults to empty array. Note: Form attributes take presedence over default values. Example: method
: String to overwritte the form HTMLmethod
attribute. Defaults to "POST"
Field Service options
getFileExtensions
If current Field Type is "file" you can retrieve the current "File Extension Restrictions" set on that field.
Dynamic Email notifications
- "Email Subject", "Submit Message", "User Notification Subject" and "User Notification Message" form settings can use dynamic field values by referencing the field "name" between square brackets. e.g. "You received a form submission from
[email]
" whereemail
is thename
of a field in your form.
Template Structure
Your form template can look something like this:
Advanced templating:
If you want to stick to HTML and not use the variables:
Redirecting after submit
If you have a ‘redirect’ hidden input, the user will get redirected to it upon successfully sending the email.
Note that if you don’t include a redirect
input, the current page will get reloaded.
Displaying flash messages
When a contact form is submitted, the plugin will set a success
flash message on the user session. This is so, you can have a success message after the form has been submitted and can be displayed on redirected page.
The available flash variables are:
wheelformSubmittedForm
- ID of submitted form
wheelformSuccess
- message to display
You can display it in your template like this:
Form Field Type
You can assign a Field Type to your sections where Users can select which form to display based on a Dropdown. This field will return a wheelform.form
template service (same as other examples) that belongs to the form selected on the Admin Panel. if you need to customize it you can use the setConfig
variable to modify the default behaviour.
Displaying the last/current submission
Similar to the flash message (will only be available after submission), when a contact form is submitted the plugin will store the values of the submitted form in the session and make it available (once) through the wheelform.lastSubmission
variable. You can use this in the template (typically in your re-direct page) like this:
You also have available submission.id
, submission.formId
and submission.date
(Note: submission.date
is a DateTime object run it through date()
filter).
Recaptcha V3
Displaying existing form submissions
You can access existing submitted form entries on a form through the form.entries
property:
Displaying specific Form Submission
You can access specific form entry by loading the form and requesting it by ID:
File attachments
If you would like your form to accept file attachments, follow these steps:
- Make sure your opening HTML
<form>
tag containsenctype="multipart/form-data"
. - Add a
<input type="file" name="{field_name}">
to your form.
File saving to asset Folder
On Plugin Settings select the Folder you would like to save files. Make sure Allow public URLs
option is turned on.
Ajax form submissions
You can optionally post contact form submissions over Ajax if you’d like. Just send a POST request to your site with all of the same data that would normally be sent:
JQuery
Basic Javascript using Axios and Babel with Webpack
If using getCrsfInput() make sure you are submitting it with the rest of your form.
Recaptcha with Ajax
If implementing Recaptcha with Ajax, keep in mind that it is necessary after each Ajax request to refresh the recaptcha token to avoid an invalid recaptcha validation error (see issue 242).
Example using Fetch API:
CSRF Meta Tags
If submitting Ajax request and need Meta Tags inside head
element you can use {{ wheelform.metaTags() }}
to generate the appropriate CSRF values.
Permissions
There are 4 different type of permissions ({Form Name} permissions are repeated per form on your website):
- Create new Form - Allows User / Group to see the "New Form" button and create new forms.
- Edit {Form Name} - Allows User / Group to see the form on the list of forms.
- {Form Name} Entries - Allows User / Group to view the Entries list.
- {Form Name} Settings - Allows User / Group to Edit the form settings.
Form Tools
- CSV Exporter can be based on entry date, under Admin > Utilities > Form Tools.
- Form Fields can be exported as a JSON file.
- Form Fields can be imported from a valid JSON file.
Delete Messages Cron Job
You can schedule a Cron Job on your server to run daily an check to Delete any old Messages values saved on your database. The cron Job Command is:
php var/www/yourwebsite/craft wheelform/message/purge
where var\www\yourwebsite\craft
is the path to the craft executable package.
The only configuration needed inside config\wheelform.php
is:
Note: This action cannot be reverted.
Custom "From" Address per Form
Change the "From" Address based on each form, this will overwritte the General email set on the form settings.
- Create
wheelform.php
file inside Craft's configuration folder. - Add and
array
with the keyforms
with theID
of the form you would like to overwrite as the key followed by an array with the keyfrom
. Example below:
Custom Email Template
Email Templates are Optional. Custom Twig templates can be used using these steps:
- Create
wheelform.php
file inside Craft's config folder. -
wheelform.php
expects an array of configuration settings to be returned. The options are:template
: default template to use for all emails.notification
: default notification template overwrite.forms
: is an array that overwrites any settings specific to the form. The key on each array is the ID of the form to modify. (These settings take priority over anything else) (Note: Thisforms
key is the same as above for custom "From" Address)
- Inside your templates you will have access to a
fields
array andnotification_message
with the message set on the Form Administration Panel. Example:
Skip attaching files to email
Inside wheelform.php
each form can have a flag to skip attaching email:
Honeypot Field
Honeypot field is a field that is meant to be left blank by humans. Usually hidden by CSS. More information about Honeypot fields.
If not using {{ form.close() }}
helper tag make sure you add a text field with the name you used when creating the form. Then, hide it from the user using CSS or Javascript.
Render Honeypot (Optional)
If you need complete control of how the Honeypot field should behave. You can call {{ form.honeypot($type, $attributes = [], $returnString = false) }}
where:
$type
: can be 1 of 3 types;text
,password
,hidden
.$attributes
: (Optional) an array of options for the field. E.G.{'autocomplete': 'none', 'class': 'comments-field'}
.$returnString
: (Optional) This will return the field HTML string for further manipulation, instead of template ready entities.
Events
(Note: this is mostly for developers that know basic PHP and Composer Packages)
beforeValidate
Event, this allows developers to validate the values and add custom errors. skipping the plugin validation altogether, this happens before the basic plugin vaidation.
afterValidate
Event, this allows developers to validate the Message and adjust the values and errors, this happens after the basic plugin vaidation, these changes cascade into the other Events and Mailers.
beforeSave
Event, this allows developers to modify the value Active Records objects before being saved to the database, these changes cascade into the other Events and Mailers.
beforeSend
Event, this allows developers to modify the fields being sent in an email, this event does not modify the values entered in the database. Only the fields being sent to the client.
afterSend
Event, Final Values sent to the user email, perfect for Third Party integrations and libraries.
beforeResponse
Event, event that modifies the response of the submission, good place to add Custom headers, dynamic success messages, or custom data to consume on the frontend.
You can also trigger other custom functionality such as gathering custom field values to add to a Third party service such as a Mailing list.
beforeSend
and afterSend
object is as follows:
Event
class properties:
form_id
- Current ID of form being submitted, This allows developers some way to check what fields are being sent.subject
- Subject of the currnet form. This can be modified to make it customizable.message
- Associative Array of different fields with the values submitted.from
- Email Address message is being send From.to
- Email Address message is being send To (This can be an array of multiple emails).reply_to
- Email Address message can be Reply To.email_html
- Full HTML String that will be sent in the email. This overwrites other email templates.saveMessage
- Allow the message to be saved on the database (Default: True).sendMessage
- Allow the message to be sent (Default: True).
Example Plugin to handle these events. wheelformhelper
Translations
New translations can be submitted using the format inside the translations folder. (I will keep "es" translations up to date as much as possible, that can be a good starting point for your translations)