Extension:CIForms
Release status: stable |
|
---|---|
Implementation | Parser function , Hook , Special page |
Description | Forms and multi-step forms with auto-validation, multiple choice questions and cloze tests |
Author(s) | thomas-topway-it (thomas-topway-ittalk) |
Latest version | 1.3.2 (2024-07-28) |
Compatibility policy | Master maintains backward compatibility. |
MediaWiki | >= 1.35.0 |
License | GNU General Public License 2.0 or later |
Download | |
Help | Help:Extension:CIForms |
Example | CIForms_examples |
|
|
Quarterly downloads | 25 (Ranked 115th) |
Translate the CIForms extension if it is available at translatewiki.net | |
CIForms is a complete solution to quickly create input forms to immediately retrieve data from visitors, and they include a wide range of features, like native validation, nested sections, multi-step, multiple choice questions with arbitrary inputs within lines and supporting all standard list style types, cloze tests, Google recaptcha, select & combobox, textarea with maxlength, data access (used to restrict the access to forms' submissions), and much more!
Forms submissions are both optionally sent as a pdf document to the provided email address(es), and stored in a dedicated table which can be accessed by permitted users through a Special Page. (from which each submission can be individually downloaded as a pdf document as well)
Installation
[edit]- Download and place the file(s) in a directory called
CIForms
in yourextensions/
folder. - Run
composer update --no-dev
inside the folderextensions/CIForms
(this will install the dependencies phpmailer and dompdf required to send the pdf with form results to a given email address, or to download the form results as pdf) - Add the following code at the bottom of your LocalSettings.php
wfLoadExtension( 'CIForms' );
- Run
php maintenance/update.php
(this will install the required tables) Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
New features
[edit]1.3.2
[edit]- supports recent versions of MW
- adds SMTP support (see Extension:CIForms#Configuration)
- implements a number of suggestions in the Extension's talk page
1.3.1
[edit]- xlsx/excel export of form data
- fixed js module loading
- better support for WIKIs localized in other languages than English
- adaptive visualization of required symbols when no labels or placeholders are set
- form data headings now match the field/label names rather than generic input names (see this picture for a reference)
- more robust processing of form data following changes on the form descriptor (i.e. in previous versions a change of a label of a field could have made the data entered with the old label not accessible, this is now solved provided that the input type remains the same)
- new api to ensure that the extension is updated to the latest available version
1.3
[edit]- csv export of form data
- support for multi-step & pagination
- new local and global parameters
success page
anderror page
(in order to redirect the user on a page of the wiki once submission) - updated list of global and local parameters, with back-compatibility
- support for postgres and table prefix
- username always saved in form data
- editable labels for buttons (submit, navigation back and next)
Examples
[edit]Basic, one column
[edit]This is the simplest form (type "inputs" by default, one column)
The square brackets represent an input, the square brackets optionally contain the input type, the asterisk indicates a mandatory field
{{#CI form: title = Contact form | type = inputs | first and last name [] * | email [email] * | your message [textarea] * }}
which produces the following
Placeholders
[edit]Form with placeholders. The square brackets contain the placeholder and optionally the input type after the equal symbol:
{{#CI form: title = Contact form | [first and last name] * | [email=email] * | [phone=tel] | [your message=textarea] * }}
which produces the following:
Two columns
[edit]Inputs responsive (two columns), the square brackets contain the input type, the form rows can contain html (the label of the email input is bold)
{{#CI form: title = Contact form | type = inputs responsive | email-to = [email protected] | first name [] * | last name [] * | <b>email</b> [email] * | phone [tel] | your message [textarea] * }}
Multiple choice
[edit]Multiple choice with arbitrary text inputs between answers (on the last line in the example).
By default the input will be rendered as radio buttons (only one answer allowed).
In order to display checkboxes allowing multiple answers, set the parameter max answers
to a value greater than 1.
{{#CI form: title = Why are you applying to this job? | type = multiple choice | I send bulk applications, even if I will be selected I'm not sure to confirm | I ran out of money, I have to find whatever job quickly | I want to learn something new | The job fits my background and I'm very skilled, I look forward to join your team! | Let me explain [] }}
Select
[edit]Select with placeholder and hardcoded options. Options contain commas? Just escape them!
{{#CI form: title = Select your preferred IT course | type = inputs | [Please chose one=select=PHP and Mysql, Node.js\, Vue.js\, React, Mediawiki and Gerrit ] * }}
Select with combobox
[edit]Select populated by wikitext (if the select contains more than 20 options CIForms will automatically display it as a select2 combobox)
{{#CI form: title = Country and city | type = inputs | country [select={{#replace:{{Template:Countries}}|*|,}}] * | city [] * }}
attention: in order for this example to work, $wgPFEnableStringFunctions
and
$wgPFStringLengthLimit
must be set respectively to true
and to an high value (for instance 10000) in your LocalSettings.php, and Template:Countries must exist
Nested sections
[edit]Form with nested sections. The multiple choice accepts up to 3 answers ("max answers=3") The textarea has a maxlength attribute ("[textarea=1000]")
{{#CI form: title = Job application | data-access = sysop | {{#CI form section: type = inputs | name [] * | email [] * }} | {{#CI form section: type = inputs | title = What about your motivation? | type = multiple choice | I send bulk application, even if I will be selected I'm not sure to confirm | I ran out of money, I have to find whatever job quickly | I want to learn something new | The job fits my background and I'm very skilled, I look forward to join your team! | Let me explain [] }} {{#CI form section: type = multiple choice | title = If you will be selected (on the basis of the answer above), how will you undertake your work? (up to 3 answers allowed) | type = multiple choice | max answers=3 | I will work scrupulously | I will work meticulously | I will pretend to work | I will delegate all my work to my sister | I will work seriously }} {{#CI form section: type = inputs |title = Please describe yourself (1000 characters max) | [textarea=1000] * }} }}
Multi-step & pagination
[edit]Since version 1.3 (July 2022) CIForms supports the creation of multi-step forms, simply by splitting form sections in steps or pages, rather than displaying them, as by default, altogether. In order to have a form consisting of several steps, use the paging
parameter combined with form sections (see above).
In order to convert the previous form in a multi-step form, add
| paging = 2
to the form descriptor. Each step will contain 2 sections. You can set the number of sections for each step using a value like the following: 1, 1, 2
(this will display 1 section in the first 2 steps, and 2 in the last one)
Here is a complete working example https://wikisphere.org/wiki/CIForms_multi-step
the demo tries to emulate the full list of inputs offered by LimeSurvey however, although CIForms provides native validation whenever possible, it currently misses some input types, specifically the QArray* inputs and conditional display.
Cloze test
[edit]Cloze tests are mainly used to administer quizzes and tests.
Square brackets represent an input, a square bracket with text inside represents a suggestion. The asterisk represents an example sentence. Each row can contain an arbitrary number of inputs.
{{#CI form: type = cloze test | title = Put the verbs between parentheses in the proper tense | * I (to be) [have been] proud to win the match | I (to do) [] a wonderful work | I (to drink) [] too much at the last party | I (to eat) [] 3 pizzas and 4 portions of french fries, and now I don't perform really well in intimate situations | (to make) We are such stuff as dreams are [] on; and our little life ... }}
Cloze test with suggestions
[edit]The list of suggestions is automatically shuffled and the inline suggestion is automatically canceled from the list. (line-through)
{{#CI form: type = cloze test | title = Put the right word in each sentence | suggestions = pencils, cats, dogs, car, house, pizzas | * There are three [pencils] on my table | My [] is pretty fast | My [] barks a lot but welcomes thieves equipped with sausages | I love [] because they say "meeeooow" | I'm able to eat 4 [] at any time | My [] has 3 swimming pools and a bowling lane, are you envious? }}
... and more! check here for more examples!!
Special Page/Output
[edit]CIForms stores all the submissions in a table and all the available forms can be viewed and navigated through a special page, and even downloaded as pdf. Additionally, form results can be sent to a provided email address, as explained below.
This is a screenshot of the special page Submissions, with the list of form's submissions, grouped by title and the page where the form is placed, throughout the Wiki:
This is the list of submissions to a given form.
The list can be navigated, and if the relevant dependencies are installed (see above, #Installation), the form data can be immediately downloaded as pdf.
Pdf output
[edit]This is an example pdf output of the form above "Job application", either received by email if the parameter email-to
is used (see section below for more detail) or clicking the download button in the submissions table.
Configuration
[edit]Note that in order to be able to send email to the provided email address (usually the system administrator) on form submissions, $wgEnableEmail
must be enabled, and PHPMailer must be installed as per #Installation istructions.
Insert the following code after wfLoadExtension( 'CIForms' );
in LocalSettings.php (this facilitates setting the global variables listed below)
define( 'CIFORMS_VALUE_IF_NULL', 0 );
define( 'CIFORMS_VALUE_OVERRIDE', 1 );
define( 'CIFORMS_VALUE_APPEND', 2 );
The constants above indicate the "merging strategy" of the global variable in relation to the corresponding parameter set within the form. CIFORMS_VALUE_IF_NULL
means that the global variable will be used only if the corresponding local variable (placed in the form descriptor) is null, CIFORMS_VALUE_OVERRIDE
means the global variable will override the local, and CIFORMS_VALUE_APPEND
means that the two will be merged together.
Global parameters
None of the following options are required, if $wgCIFormsDataAccess
(global) or data-access
(local) are null, form data will be accessible only to sysops. If $wgCIFormsEmailTo
(global) or email-to
(local) are null, form data will not be dispatched by email.
variable | description |
---|---|
$wgCIFormsSenderEmail |
The sender in the "From" field when sending the form submission to the provided email address(es) |
$wgCIFormsSenderName |
Sender name of the "From" field mentioned above |
$wgCIFormsMailer |
"smtp" or "sendmail" |
$wgCIFormsSMTPHost |
smtp host (e.g. 'smtp.example.com') |
$wgCIFormsSMTPUsername |
smpt username (e.g. '[email protected]') |
$wgCIFormsSMTPPassword |
smpt password |
$wgCIFormsSMTPPort |
smpt port (e.g. 465) |
$wgCIFormsEmailTo |
default email address(es) to which optionally send form submissions |
$wgCIFormsEmailToGlobalMode |
merge strategy for $wgCIFormsEmailTo , one of the constants above (CIFORMS_VALUE_IF_NULL or CIFORMS_VALUE_OVERRIDE or CIFORMS_VALUE_APPEND)
|
$wgCIFormsDataAccess |
default groups or users who can access form submissions (comma separated) |
$wgCIFormsDataAccessGlobalMode |
merge strategy for $wgCIFormsDataAccess
|
$wgCIFormsSuccessPage |
default success page on form submission |
$wgCIFormsSuccessPageGlobalMode |
merge strategy for $wgCIFormsSuccessPage
|
$wgCIFormsSuccessMessage |
default success message on form submission |
$wgCIFormsSuccessMessageGlobalMode |
merge strategy for $wgCIFormsSuccessMessage
|
$wgCIFormsErrorPage |
default error message on form submission |
$wgCIFormsErrorPageGlobalMode |
merge strategy for $wgCIFormsErrorPage
|
$wgCIFormsErrorMessage |
default error message on form submission |
$wgCIFormsErrorMessageGlobalMode |
merge strategy for $wgCIFormsErrorMessage
|
$wgCIFormsGoogleRecaptchaSiteKey |
GoogleRecaptchaSiteKey to secure validation with Google Recaptcha |
$wgCIFormsGoogleRecaptchaSecret |
GoogleRecaptchaSecret to secure validation with Google Recaptcha |
Global to local parameters
global | local |
---|---|
$wgCIFormsEmailTo |
email-to |
$wgCIFormsDataAccess |
data-access |
$wgCIFormsSuccessPage |
success-page |
$wgCIFormsErrorPage |
error-page |
$wgCIFormsSuccessMessage |
success-message |
$wgCIFormsErrorMessage |
error-message |
Example configuration
[edit]$wgEnableUserEmail = true; $wgEnableEmail = true; $wgPasswordSender = $wgCIFormsSenderEmail = [your wiki email address]; $wgCIFormsGoogleRecaptchaSecret = [your google recaptcha secret]; $wgCIFormsGoogleRecaptchaSiteKey = [your google recaptcha site key]; $wgCIFormsSuccessMessage = 'The form has been sent, thank you!'; $wgCIFormsErrorMessage = 'We couldn\'t send your form, please try again or contact the support at <span class="ci_text_highlight">' . $wgCIFormsSenderEmail . '</span>';
To prevent sending email notifications of form submissions throughout all the Wiki, set $wgCIFormsEmailTo to null and $wgCIFormsEmailToGlobalMode to CIFORMS_VALUE_OVERRIDE ! |
Parameters
[edit]The following parameters can be used in the parser function {{#CI form: }}
or {{#CI form section: }}
attribute | values | description | {{#CI form: }} |
{{#CI form section: }} |
version |
---|---|---|---|---|---|
type | inputs, inputs responsive, multiple choice, or cloze test | sets the form type. Default is "inputs" | v |
x |
1.1
|
data-access | list with groups and usernames | overrides the global variable $wgCIFormsDataAccess in the given form | v |
x |
1.3 |
email-to | list of email addresses | overrides the global variable $wgCIFormsEmailTo in the given form | v |
x |
1.3 |
title | any string, can contain html and wikitext | the title of the form or form section | v |
v |
1.1
|
paging | false or list of number of sections for each page | paginate form sections, eg. 4, 4, 2, to display 4 sections in the first 2 steps, and 2 form sections in the last one | v |
x |
1.3 |
list-type | "none", "ordered", "unordered", "letters", "number", or whatever value listed here | the list style of multiple choice questions or cloze test | v |
v |
1.1
|
suggestions | comma separated list of words | suggestions for cloze tests, as shown in the examples above | v |
v |
1.1
|
min-answers | number | minimum number of answers in multiple choice questions or cloze tests | v |
v |
1.3 |
max-answers | number | maximum number of answers in multiple choice questions | v |
v |
1.1
|
submit text | string | replacement string for the submit button | v |
v |
1.3 |
navigation next | string | replacement string for go forward button (only if paging is set) | x |
v |
1.3 |
navigation back | string | replacement string for go back button (only if paging is set) | x |
v |
1.3 |
css class | string | additional css class applied to the form or form section (for alternate styling or skin) | v |
v |
1.2
|
success page | string | landing page on successful form submission, overrides the global variable $wgCIFormsSuccessPage for a given form | v |
x |
1.3 |
error page | string | landing page on form submission error, overrides the global variable $wgCIFormsErrorPage for a given form | v |
x |
1.3 |
success message | string | overrides the global variable $wgCIFormsSuccessMessage for a given form | v |
x |
1.1
|
error message | string | overrides the global variable $wgCIFormsErrorMessage for a given form | v |
x |
1.1
|
Support & bugs
[edit]Please report the error messages on the Talk page of the extension. Updates will be posted on the main MediaWiki mailing list mediawiki-l so we advice you to subscribe to the list to stay tuned with them.
For professional support please write at the email address posted here
See also
[edit]- Stable extensions
- Parser function extensions
- Hook extensions
- Special page extensions
- GPL licensed extensions
- Extensions in Wikimedia version control
- BeforeInitialize extensions
- LoadExtensionSchemaUpdates extensions
- OutputPageParserOutput extensions
- ParserFirstCallInit extensions
- All extensions
- Form extensions
- Contact form extensions