Template talk:FormParameters-DragonBox

Audience

This page is intended for Bureaucrats, Administrators, and Interface Administrators etc., that deal with and have privileges for template creation. And those that have privileges to add pages to the Form_Values namespace to add new options forms.

Introduction

Templates allow users to template content and call that content in other pages. An example of a simple, named template:

{{TemplateExample}}

.
Templates may also have input parameters:

{{TemplateExample
|parameter1=
|parameter2=
}}

Users can then input values to generate certain content, however users must know all of the allowed values (not visible) in order to do this easily or efficiently. The MediaWiki extension Page Forms allows forms to be created that draw a set of parameters from a template. This allows any user to easily fill out the data required to make a dragon page without having to know all of the parameters and values, or copying them from other dragon pages. Users can simply select the appropriate items from notated fields and drop-downs. The form can also provide descriptions of when to use each parameter, as well as help text, tips and images to fill out the information.

To learn more about templates see Help:Templates.

Special Pages

Page Forms adds several pages to Special Pages:

Create a category Create a class Create a form Create a template

Edit multiple pages (disabled) Run query Start of form

Implementation

There are 2 ways to create forms, but the comprehensive way (one item at a time) needs to be used on the DML wiki. Since templates, pages and category for DragonBox already exist, don't modify them by creating a class, this can overwrite existing templates without warning (though only users with privileges can edit templates). Instead, create a template then a form.

Overview

1. Create a template in the Template namespace (with no parser junk or calculations in it, just all applicable parameters and nothing else).
2. Create pages under the subcategory whose titles are the values for each parameter
   1. For example, I have a field named Element for the first element, so I need the values: fire, wind, earth, water, Fire is the value for Element)
3. Create a form (by attaching the template to import all parameters then adding labels and values lists).
4. Enable link to the form (associate a form to a category so whenever an item is added/changed it uses the form).
5. Add data (test the form).
6. Customize forms (add features forms that help make them more usable).
7. Configure the Edit and Edit with form tab (see this).

Create a template

This template is used strictly to import the parameters directly into a form any time the form needs to be recreated without importing a bunch of unneeded parameters or template calculations, so it should only contain parameters and labels. There is no documentation to do this without Cargo or Semantic Mediawiki (unfortunately) but the process is much the same as used in Cargo except that properties don't apply.

1. Click Create a Template.
2. Fill in the Template name (start the template name with "FormParameters-")
3. Leave Category defined by template blank.
4. Under Template fields, for each parameter:
   1. Put a parameter name under Field name (convention on the wiki is generally lowercase)
   2. Put a descriptive label under Display label. For example, "breeding" doesn't tell the user what the property is for, but "breeding time" does. Descriptions can be entered for each parameter in the form creation, so longer descriptions of when to use are not necessary here.
   3. Be sure to select Field holds a list of values for any field where you will allow the user to select from a list of values, or the option to specify a category for those values will not appear on the Create a form screen. Allowing a list of values adds the following Page Forms parser function so the form knows to provide a category field for the array:

      {{#arraymap:{{{listofvalues|}}}|,|x|[[x]]}}

5. Rinse and repeat until all possible parameters are in the template with descriptions and "Field holds a list of values" for all but manual entry items like text, text area and number entry.
6. Save the template

• • Note: This creates the template in the Template namespace automatically.

Create a category

There are two types of categories of importance related to page forms:

1. The category where the pages end up (after the form is assigned to that category).
2. The categories the form uses to draw values from using page names (to populate drop-downs).

Categories where the pages end up mostly already exist. For example, the destination for a dragons page is the Dragons category. Once the form is later assigned to the Dragons category page (form link enabled), all pages created using the form will appear under that category automatically. If a new category is needed for a new form you can easily create one. This should be pretty self explanatory, if it isn't see Creating a category page.

Create a form

The form is generated by the Create a form function but after creation can be edited in plain text view like any page. This allows changes or customization to be made later on such as images, tabs, to help users. Forms can also be styled or have tables and other regular content added as needed for usability.

1. Click Create a form
2. Enter a name for the form in the Form name field. If the form is for an existing template, name it the same as the template name so it is easy to determine what form belongs to what template. Templates created will live in the Form namespace and result in a URL like the following: Form:FormName
3. In the Add template drop-down, select the FormParameters-(name) template you just created and then click Add
   1. Note: Doing this off of a form that has parser functions in it will result in an unusable form cluttered with temporary parser parameter junk.
   2. Some items may appear at the top out of place (bug), but can easily be moved later
4. For each field, select an input type then unfold the Other parameters section. Specify a FormValues category to draw the drop-down or other input values from. Note: Not all data types will work without Cargo or Semantic media wiki unfortunately. Each defined data type, when using either Cargo or Semantic MediaWiki, has a default input type, and, when applicable, a default input size as well. Additionally, some data types have special handling if the field holds a delimited list of values, instead of just a single value. The only input type that will auto-populate from a category for example is the Tree input type. That means that other input types must have their options added by editing the form itself. From a maintenance standpoint, adding a category to add an item is preferable but from a usability standpoint of using the form, not ideal. See Input Types for more information. There are also some usability guidelines for how to select the right input type.
5. Edit the template page and copy and paste the Form labels over (unfortunately these don't currently import for some reason but you have them ready before starting the form which is good).

A few notes:

• Don't make fields mandatory if they don't apply to all dragons (including boss and clan dragons).
• Don't use restricted fields (bugs currently)
• Make sure to add help text to explain to the user when they should use each value (or not).

Field layouts

Field layout is something to consider for usablity. The same layout for all fields may not work well depending on the height of the input.

For smaller lines (text, dropdown, regexp):

Input Label
[field]	image
Description

{| class="wikitable"
! colspan="2" | Input Label
|-
| [field] || rowspan="2" | image
|-
| Description
|}

For larger controls (textarea):

Input Label
field	Text	image

{| class="wikitable"
! colspan="4" | Input Label
|-
| style="width:35%;"|field
| style="width:45%;"|Text
| style="width:20%;"|image
|-
| colspan="4"|<p class="pfFieldDescription">Field help</p>
|}

For narrow forms:

Input Label
field
Text
image

{| class="wikitable"
! Input Label
|-
| field
|-
| Text
|-
| image
|}

Common allowed parameters

See Input Types for more information about input types and all allowed parameters. For ease of use, below is a list provided of the most common allowed parameters for forms (excluding stuff that doesn't apply without Cargo or SMW. Unfortunately the documentation pages don't contain a complete list of parameters in one place, this need to be pieced together over multiple pages.

Image	Input Name	When to use	Accepted parameters
File:Pageforms-checkboxjpg	checkbox	When a user needs to select confirm a single item like consent or rules read.	|restricted |class= |default=
File:Pageforms-checkboxjpg (Same as above only with multiple)	checkboxes	When multiple values potentially need to be selected and images or other formatting needs to be added (still testing to confirm).	|mandatory |restricted |class= |default= |values= |values from category= |values from namespace= |show on select=
File:Pageforms-comboboxjpg	combobox	When there is a combination of both list and a selection field needed (and there is a large number of items to be chosen from or when the selection may be made easier by entering the first few letters). Combo box contains a text box field, so choices not on the list can be typed in. This can also be restricted to existing items only, so the text field is used for easier search and selection such as from a category like "Dragons."	|mandatory |restricted |class= |default= |size= |values= |values from category= |values from namespace= |existing values only |placeholder= |namespace=
File:Pageforms-datejpg	date	When just a date needs to be entered without picker assistance or the user is already familiar with the date format.	|mandatory |restricted |class= |default=
File:Pageforms-datepickerjpg	datepicker	When just a date needs to be added and made easy with a date picker.	Info coming soon...
File:Pageforms-datetimepickerjpg	datetimepicker	when both date and time need to be specified and made with a date/time picker.	|mandatory |restricted |class= |default= |dateformat= |weekstart= |first date=(e.g., 2019/08/01) |last date=e.g., 2019/08/01) |disable days of week=(e.g., 6,0) |highlight days of week=(e.g., comma separated or range with dash) |disable dates=(e.g., comma separated with dash) |mintime= |maxtime= |interval=
File:Pageforms-datetimejpg	datetime	When both date and time need to be specified.	|mandatory |restricted |class= |default= |include timezone=
File:Pageforms-dropdownjpg	dropdown	When a single item needs to be selected from a list (or none).	|mandatory |restricted |class= |default= |values= |values from category= |values from namespace= |show on select=
File:Pageforms-listboxjpg	listbox	When a list of items (exceeding 10-15) is needed and the space for the list needs to be limited. Listbox can also have a single or multiple selections depending on the settings.	|mandatory |restricted |class= |default= |values= |values from category= |values from namespace= |show on select= |size=
File:Pageforms-radiobuttonsjpg	radiobutton	When a single item needs to be selected from a list (or none) and images need to be added (still testing to confirm).
File:Pageforms-ratingjpg	rating	When you want users to be able to rate an item on a scale specified in the settings using stars to indicate rating. Can be set to have any number of rating items 1-5 1-8 etc. Can also be set to allow for half-stars.	|mandatory |restricted |class= |default= |star width= |num stars= |allow half stars
File:Pageforms-regexpjpg	regexp	When only certain values need to be permitted such as 0-9 a-z A-Z , (space). All allowed values occur between the square brackets. Important note: Regexp doesn't use the equals = symbol, rather regexp parameters end in a colon : instead or they will not work. Example: |regexp:/^[0-9]+$/ or |regexp:/^[0-9,]+$/ .	|mandatory |restricted |class= |default= |regexp: |base type= |base prefix= |or char= |inverse= |message=
File:Pageforms-textjpg	text	When a single line of text is needed with no data validation.	|mandatory |restricted |class= |default= |size= |maxlength= |placeholder= |uploadable |image preview |default filename=
File:Pageforms-test with autocompletejpg	text with autocomplete	*Same as above but with suggestions from auto complete.	*Same as above with <!-- Autocomplete --> |values= |values from category= |values from namespace=
File:Pageforms-textareajpg	textarea	When a larger box is needed for text, such as multiple lines or a paragraph (no data validation rules).	|mandatory |restricted |class= |default= |rows= |cols= |maxlength= |placeholder= |autogrow |editor= |values=
File:Pageforms-textareajpg	textarea with autocomplete	*Same as above but with suggestions from auto complete.	*Same as above with the addition of: <!-- Autocomplete --> |values from category= |values from namespace=
File:Pageforms-treejpg	tree	When an organized structure is beneficial for the user to find a an item.	|mandatory |restricted |class= |default= |top category= |structure= |hideroot |depth= |height= |width=
File:Pageforms-tokensjpg	tokens	When a user needs to be able to search for, select or delete multiple items using a combobox-like interface.	|mandatory |restricted |size= |max values= |existing values only |placeholder= |namespace= <!-- Autocomplete --> |values= |values from category= |values from namespace=
n/a	(Hidden)	Used to preserve values in edited pages.	(None)
File:Pageforms-yearjpg	year	When only year needs to be specified.	|mandatory |restricted |class= |default= |size=

Other Common Elements

There are lots of other form elements available, for a full list see: Defining Forms, Page Forms and templates, and Input types.

There are also some common bottom of form elements such as:

{{{standard input|free text}}}


{{{standard input|summary}}}

{{{standard input|minor edit}}} {{{standard input|watch}}}

{{{standard input|save}}} {{{standard input|preview}}} {{{standard input|changes}}} {{{standard input|cancel}}}

Enable form links

To enable a form link, navigate to the category you wish it to appear in (e.g., ), edit the category and add:

{{#default_form:YourFormName}}

To associate the category with the form, edit the form and add:

{{#forminput:form=YourFormName|autocomplete on category=YourCategoryName}}

Also make sure to associate it with the correct template to use to populate the values:

{{{for template|TemplateName}}}

Add data

Info coming soon

Customize forms

Info coming soon

Configure the Edit and Edit with form tabs

Info coming soon

Configuration Settings

When creating new forms, it is a good idea to have the Page Forms plugin configured to only load forms when Edit with Form is clicked. This is the default config and will only pop up the option on pages in categories that have a form associated with it and enabled. After forms are refined and set it is a good idea to change the plugin settings to:

• $wgPageFormsRenameEditTabs = true; - renames the "edit with form" tab to "edit", and the "edit" tab to "edit source" (in whatever language the wiki is being viewed in)

OR

• $wgPageFormsRenameMainEditTab = true; - renames only the "edit" tab to "edit source" (in whatever language the wiki is being viewed in)

It is also important to ensure the general public cannot multi-page edit (this only applies to templates and forms created using the Create a class feature), but best to have it turned off just in case.

$wgGroupPermissions['*']['multipageedit'] = false; // Set all users multipage edit to false $wgGroupPermissions['sysop']['multipageedit'] = true; // Set sysop permision to multipageedit only

(These are the current settings on this wiki)

Also a good idea to restrict editing in the Form_Values namespace so only authorized users can create, edit and add values (page names in the Form_Values namespace) to the forms automatically by adding a new page.

Updating forms

For ease of use adding values to forms has been simplified, just find the corresponding sub-category in the FormValues subcategories and add a page under that subcategory. Once a form is reloaded, the page title will appear in the applicable drop-down list in all forms! Populating data by this method can save a tremendous amount of time and effort so forms only need to be edited when the page layout changes (new sections added etc.).

Otherwise pages can be edited in the regular, plain text mode. They cannot be edited using the initial form however, rather re-creating a form via the Create a form feature with a different name and renaming later is the only option provided.

More info coming