Extension:VisualData/Forms

Forms

VisualData's forms are automatically generated by the extension on the basis of the json-schema(s) created through the SchemaBuilder and they can be rendered on the page either using the parser function visualdataform or through the template "VisualDataForm" completed with TemplateData for an easy use through Extension:VisualEditor.

Technically (or at design level) a form is an envelope for one or more schemas (a form can contain multiple schemas, and they will be displayed using OOUI tab panels or BookletLayouts) determining the data to be edited, the target page, and additional options related to wiki articles like freetext, categories and so on.

(insert template button from the VisualEditor menu)

(list of available templates bundled with VisualData)

Alternatively a form can be added to an article using the following parser function:

{{#visualdataform: Book
|title = Book
|action = create
|edit-page = 
|return-page = 
|view = popup
|popup-size = medium
|css-class =
|pagename-formula =
|edit-freetext = true   
|edit-categories = false
|edit-content-model = false
|edit-target-slot = false
|target-slot = jsondata
|default-categories = 
|default-content-model = wikitext
|preload=
|preload-data=
|layout-align = top
|popup-help = false 
|layout = tabs
|submit-button-text =
|validate-button-text =
|callback=
|overwrite-existing-article-on-create = false
}}

This is an example of a popup form containing a schema created using the SchemaBuilder and rendered on the wikipage using the previous parser function.

A VisualData' form can have either one or two states, or steps: validate, submit, or validate & submit. A form has 2 states when it also allows to edit the article's freetext, categories, and/or content model, so that in the first step the user fills the schema(s) data and in the second step the article-related data.

In both cases the form is validated through ajv-validator, on the basis of the provided schema(s) and error messages are displayed directly on the form. This way the entered data are guaranteed to comply with the schema definition, that in turn allows a wide variety of settings related to validation, like minimum and maximum items for lists (arrays), validation patterns using regex and of course required fields.

(example of validation error using a validate pattern)

Available parameters

Here are the available parameters for the visualdataform parser function and their default values.

parameter	description	default
`(unnamed parameter)`	one more schema name, comma separated	(user defined)
`action`	form action, can be `create` or `edit`	`create`
`edit-page`	title of the page holding the data to edit (with `edit` action)
`return-page`	return page	where not set, with action `edit` the form will return on the page holding the form, with action `create` the form will return to the target page
`return-url`	return url	specify an url instead of a return page. To be only used for external pages or urls with queries (in this case is supposedly used with the QueryLink parser function)
`title`	title of the form (or the panel if a form containing multiple schemas)	(the schema name)
`view`	display mode of the form, can be `inline` or `popup`	`inline`
`popup-size`	popup-size, possible values: `small`, `medium`, `large`, `larger` `full`	`medium`
`css-class`	css-class to be attached to the form	`VisualDataForm`
`pagename-formula`	formula used to create a new article through the form with the entered data, in the form contacts/<first_name> <last_name>, where "first_name" and "last_name" are the property names of the related schema
`edit-freetext`	whether the form allows to edit freetext	`false`
`edit-categories`	whether the form allows to edit categories	`false`
`edit-content-model`	whether the form allows to edit the content model	`false`
`edit-target-slot`	whether the form allows to edit the target slot	`false`
`target-slot`	target slot for the semantic data, could be `jsondata` or `main` (use main to register json data in the main slot)	`jsondata`
`default-categories`	default categories (comma separated)
`default-content-model`	default content model (default are: css, json, javascript, html, text, wikitext)	`wikitext`
`preload`	preload freetext content
`preload-data`	preload json-data (expects an article title with json data)
`preload-data?[json pointer]`	overrides specific properties / property paths of json data (the json pointer must contain the schema name if multiple schemas are included in form). Since version 1.0.7 accepts the modifier "+base64" to accept base64 encoded arguments (see also Additional parser functions Base64encode)
`layout-align`	default align for the OO.ui.FieldLayout, possible values are `left` `right` `top` `inline`	`top`
`popup-help`	corresponds to `helpinline` set to `false` in the OO.ui.FieldLayout	`false`
`submit-button-text`	text of the submit button	`Submit`
`validate-button-text`	text of the validate button	`Validate`
`layout`	form layout with multiple schemas, can be `tabs` or `booklet`	`tabs`
`callback`	callback Javascript function called on form submission with form data (used by the extension Extension:ContactManager)
`overwrite-existing-article-on-create`	overwrite existing article with action equals to create if the target article exists. This is used by Extension:ContactManager to compose an email whose content will be saved in a fixed article and taking advantage of Mediawiki's version history	`false`
`selected-schema`	selected schema (when using form with multiple schemas)

Example of a VisualData's form with various available inputs and content-block with an image rendered using wikitext:

Forms

Available parameters

See also