Extension:CIForms
 Release status: stable |
|
|---|---|
| Implementation | Parser function, Hook |
| Description | Forms with auto-validation, multiple choice questions and cloze tests, emailed as pdf |
| Author(s) | (thomas-topway-ittalk) |
| Latest version | 1.1.0 (2021-08-12) |
| MediaWiki | |
| License | GNU General Public License 2.0 or later |
| Download | github |
| Example | culturaitaliana.org |
| Translate the CIForms extension if it is available at translatewiki.net | |
The CIForms extension allows for rapid creation of forms, either standard forms with input fields aimed at receiving data from visitors, or forms with multiple choice questions or even complex Cloze tests to be used as teaching tools for current students or to engage prospective ones.
All forms include automatic validation, are protected by the latest version of Google recaptcha (if enabled) and have been inspired by this extension at Wikiversity and they diverge from it mainly because the submitted data are sent to the provided email address, rather than used to compute a score. Please check Help:Extension:CIForms for detailed examples.
FeaturesEdit
- forms with input of various format (with placeholders, responsive, mandatory fields, different input types, like 'text', 'email', 'password', 'textarea', 'email', 'tel', etc.)
- multiple choice questions (with optional inputs within choices)
- cloze tests, multiline, and with arbitrary number of inputs per line
- forms can be nested/grouped together (see picture below)
- native validation and optional captcha verification
- complex forms with html and wikitext, like tests with sentences, tables, dialogues, and more! (see here for the related examples)
- submitted forms are converted to pdf and then sent by email using phpmailer
- all css' standard list style types are supported, plus some shortcuts like "letters", "ordered", "numbers", "unordered" (see below, sections "Parameters")
Installation/DownloadEdit
Download the repository from here inside the folder mediawiki/extensions and then install the dependencies (phpmailer and dompdf) running
composer update
(in the folder mediawiki/extensions/CIForms)
UsageEdit
- See How it works on culturaitaliana.org
ExamplesEdit
This is the simplest example of a form with inputs
{{#CI form:
title = Contact form
| submit = abc@test.org
| first and last name [] *
| email [email] *
| your message [textarea] *
}}
which produces the following
Multiple choice with arbitrary input fields within choices
{{#CI form: title = Why do you want to learn Italian?
| type = multiple choice | list-type = letters | max answers = 2
| I want to work using Italian language
| I want to study using Italian language
| Cultural interest / personal knowledge
| interpersonal relationships [] *
| prospective stay in Italy
}}
and much more! see the complete list of examples here
List of parametersEdit
| attribute | scope | description |
|---|---|---|
| type | CI form or CI section | type of form or section: "inputs", "inputs responsive", "multiple choice" or "cloze test" |
| title | CI form or CI section | form or section title |
| submit | CI form | email address to which the filled-in form will be dispatched (can be a list, comma separated) |
| success message | CI form | the message displayed after submission of the form if the form has been correctly sent |
| error message | CI form | the message displayed after submission of the form if there was any issue sending the form |
| suggestions | CI form or CI section with type "cloze test" | list of comma separated words to be used as a reference to complete the various answers and shown in a box above the answers |
| list-type | CI form or CI section with type "multiple choice questions" | the list type of the answers, can be "none", "ordered", "unordered", "letters", "number", or whatever value listed here |
| max answers | CI form or CI section with type "multiple choice questions" | maximum number of answers (used for validation) |
| form class | CI form | additional class to be applied to the form (for styling) |
Please visit this page Help:Extension:CIForms for additional examples and here for their visualization.
ConfigurationEdit
First ensure that the parameter $wgEnableEmail of your wiki is set to true, and that either $wgPasswordSender is set to some value, or $wgCIFormsSenderEmail (all of them are typically located/placed in the file LocalSettings.php) contains the sender email address of your forms.
Conversely, $wgCIFormsSubmitEmail contains the email address to which the form data will be dispatched once submitted by the visitor, which will be used where the submit parameter is missing from the form's template. (precisely a parser function).
The same applies to $wgCIFormsSuccessMessage and $wgCIFormsErrorMessage, they will be used as long as success message and error message are not specified within the form.
$wgCIFormsSenderEmail = $wgPasswordSender;
$wgCIFormsSubmitEmail = '[your email]';
$wgCIFormsGoogleRecaptchaSecret = '[google recaptcha secret]' ; //(or leave blank to disable this feature)
$wgCIFormsGoogleRecaptchaSiteKey = '[google site key]'; //(or leave blank to disable this feature)
$wgCIFormsSuccessMessage = 'The form has been sent, thank you!';
$wgCIFormsErrorMessage = 'We couldn\'t send your form, please try again or contact the support at ' . $wgCIFormsSubmitEmail;
OutputEdit
CIForms produces a pdf with a form virtually identical to the original, with filled-in fields, which is sent to the provided email address upon form submission!
Known issuesEdit
- Due to this Visual Editor's bug, if the 1st parameter after the function name is separated by a new line, Visual Editor will not recognize the template/parser function and will surround it with unwanted 'nowiki' tags. Therefore use always the following
{{#CI form: title = Completa con i tempi dati al futuro semplice
|...
}}
rather than the following
{{#CI form:
title = Completa con i tempi dati al futuro semplice
|...
}}
- the template is interpreted rigorously and the parser function does not try to fix little mistakes in the parameters, like missing pipes (|) or wrong parameters. This might be updated in future