Skip to content

Github mirror of MediaWiki extension Form - our actual code is hosted with Gerrit (please see https://www.mediawiki.org/wiki/Developer_access for contributing)

Notifications You must be signed in to change notification settings

wikimedia/mediawiki-extensions-Form

Repository files navigation

MediaWiki Form extension

version 0.6
12 November 2017

This is the README file for the Form extension for MediaWiki
software. The extension is only useful if you've got a MediaWiki
installation; it can only be installed by the administrator of the site.

The extension lets users create new articles with a form interface.
Administrators configure a "form definition" in the MediaWiki namespace,
and the form can be used to create a new article using a particular
template.

Typical uses:

* "New X" interfaces for wiki newbies.

This is a testing version of the extension and it's almost sure to
have bugs. See the BUGS section below for info on how to report
problems.

== License ==

Copyright 2007 Vinismo, Inc. (http://vinismo.com/)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

== Author ==

Evan Prodromou <evan@vinismo.com>

== Pre-requisites ==

This software was tested with MediaWiki 1.29.0.

It may or may not work with earlier or later versions, but please test it.

== Installation ==

To install, copy all the files in the archive you downloaded to the
Form subdirectory of the extensions subdirectory of your
MediaWiki installation. Note that the software depends on having its
code all in the "Form" sub-directory; naming it
"Form-Test" or "newextension1" or whatever won't work.

In your MediaWiki LocalSettings.php, add the following line some place
towards the bottom of the file:

	wfLoadExtension( 'Form' );

Theoretically it should work out of the box.

== Preparing forms ==

To create a new form, you need to do two things:

* Create a "form definition" in the MediaWiki namespace.
* Create an output template that describes the structure of the
  resulting articles.

Form definitions use a special idiosyncratic syntax that may change in
the future.

Output templates are just regular ol' MediaWiki templates. They should
use ''named'' parameters rather than numbered parameters.

There is a sample form definition article in
"MediaWiki-Sample-form.wiki" that came with this package, and a
corresponding output template in "Template-Sample.wiki".

== Form definitions ==

A form definition article must be named "MediaWiki:nameofform-form",
where "nameofform" is the name you're going to use for the form. (You
can change this pattern by changing MediaWiki:Formpattern, but note
that this will affect all of your forms.)

Each line in the form definition file is either a form attribute or a
form field definition. Each is described below.

=== Form attributes ===

Form attributes define information for the form as a whole. Each
attribute line looks like:

  name=value

Note that no whitespace is tolerated before and after the name.
Typically form attributes appear at the beginning of an article, but
they are tolerated anywhere in the article, if you need things that way.

Valid names for form attributes are as follows:

* template: name of the output template (without the namespace prefix)
  that will be used for creating new articles. If this is not defined,
  the default name will be "Template:Name", where "name" is the name
  of the form.
* title: title that's shown on the form. By default, this is "Add New
  $1", where $1 is the name of the form. You can change the
  default title pattern with by changing MediaWiki:Formtemplatepattern.
* namePattern: the pattern for new article names. This is based on the
  fields in the form, and uses MediaWiki template-substitution syntax
  (badly... only the simplest syntax is now supported). For example,
  if you are creating articles about sporting events results, and
  there are two form fields "year" and "event", the name pattern might
  be "{{{year}}} {{{event}}} Results". If the user fills in "2004" and
  "World Series", the resulting article will be "2004 World Series
  Results".
* instructions: plain text (no wikitext or HTML... yet) instructions
  for users of the form. Will be shown at the top of the form before
  any fields.

=== Form field definitions ===

Each field in the form has a line defining it in the form definition
file. The structure of the field definition lines is:

  name|label|type|description|options

The parts of the field definition are separated by pipe ("|")
characters and cannot include pipes themselves (even with "escape"
characters). The parts of the definition are defined below:

* name: name of the field. It must be unique, and contain only
  alphabetic or numeric characters or the underscore ("_"). This will
  be the parameter name used for the output template.
* label: readable name for the field, used for labels. No
  restrictions, except for the lack of a pipe. No HTML or wikitext
  allowed (yet).
* type: type of the form field (see below).
* description: a user-readable description of the purpose and
  restrictions on the form field. Only shown for 'textarea' fields
  right now, but will eventually be shown for all fields once I figure
  out the layout correctly.
* options: optional parameters for the field, mostly dependent on the
  field type. options always take the form "name=value", and are
  separated by commas (",").

The description and options parts are optional.

=== Form field types ===

The following types of form fields can be created.

* textarea: an HTML textarea, e.g. a big multi-line entry area. These
  are usually used for lots of paragraphs. The following options are
  supported:
** rows: number of rows; defaults to 6.
** cols: number of columns; defaults to 80.
* text: a one-line text input. Takes these options:
** size: length of the text input; defaults to 30.
* checkbox: a yes-no, on-off choice for the user. Takes no options.
* radio: a group of radio buttons; exclusive choices. Radion button
  groups take the following options:
** items: semicolon-separated (";") list of choices for the user. For
   example, "Blue;Green;Red" will give the user three radio buttons
   labeled "Blue", "Green", and "Red".
* select: a drop-down box showing multiple exclusive choices for the
  user. Select boxes take the following options:
** items: semicolon-separated (";") list of choices for the user. For
   example, "Blue;Green;Red" will give the user a drop-down box with
   three choices, "Blue", "Green", and "Red".

All field types support the option 'required'. If this option is 'on',
'true', 'yes', or '1', saving the form without that field filled in
will result in an error (and the user is given a chance to enter the
data again).

== Using forms ==

To show a user a form, use the following special-page format:

   Special:Form/Name

Where "name" is the name of the form. This will load the form
definition from "MediaWiki:Name-form", and by default use
Template:Name for the output template.

The user can fill in the form fields and hit "save" to save the
article. Note that currently no validation is performed; if the user
fails to complete a required field, it will be rendered empty.

== Translation ==

The user interface strings for this extension are configurable through
the same Special:AllMessages page as MediaWiki itself. They all start
with "form-", and they're no more or less cryptic than MediaWiki's.

Translations to other languages besides English are welcome; please
send them along.

== Bugs and enhancements ==
Bugs and issues should be reported on the MediaWiki Phabricator:

https://phabricator.wikimedia.org/maniphest/task/create/?projects=MediaWiki-extensions-Form

The TODO file in this distribution has stuff I
think needs to be to done; + marks show things I've already done, and -
shows things that are yet to be done.


About

Github mirror of MediaWiki extension Form - our actual code is hosted with Gerrit (please see https://www.mediawiki.org/wiki/Developer_access for contributing)

Resources

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published