pageMaker

To assert influence over the evolving structure of the pages and their XObjects within a wiki one can use pageMaker.

1. Copy pageMaker to /assets/pagemaker on your wiki.
2. In the space where you want to use pageMaker (e.g. MySpace) you create another space with “Code” added to the end (e.g. MySpaceCode). In this space you can create the class, the sheet, the template and the translation file. The easiest way to create these files is by using App Within Minutes.
3. Create the spaces you would like to see newly created pages to be stored in.

By using the examples above, your wiki should have the following spaces added:

• assets.pagemaker
• MySpace and all child spaces thereof (i.e. MySpace.ChildSpace1, MySpace.ChildSpace2, MySpace.ChildSpace3, ... etc.)
• MySpaceCode.MySpaceSheet
• MySpaceCode.MySpaceTemplate
• MySpaceCode.MySpaceClass
• MySpaceCode.Translations

Required attributes for all input elements

There are four basic attributes needed to create input elements: id, type, required and label. These attributes must be provided for each call to the #createFormElement macro.

Attributes

id
Every input element must have its own id. The value of the id attribute must be unique within the HTML document.

type
The type attribute defines the type of input element that is to be created. The value of this attribute is limited to:

• text
• number
• email
• range
• select
• checkbox and radio
• textarea
• date
• color
• url
• tel

required
The required attribute specifies if this input element is required or not and can correspondingly be set to true or false. This is not a boolean value but a string, one must therefore make sure to put the value of this attribute between quotes.

label
The label attribute specifies the primary description for the input element. The value of this label is also used for the description of the error message.
The label should be seen as a short reference to the subject that is being asked for, without the leading article or possessive adjective.

Define a label for an input element that asks for the type of car you own.

Required attributes for specific elements

value
The value attribute is required for input elements where the value is predetermined, which are the select, checkbox and radio input elements.
The select input element however has its values created from the pages queried or from the JSON provided. These values are added to the option HTML tags within the select HTML tag. The value attribute is therefore not applicable in the select input element.
The ones that do require a value attribute are checkbox and radio input elements.

Optional common attributes

Some attributes are not necessary or even proper to bestow upon every type of input element.
For example, the placeholder attribute has no place in a checkbox input element but for a select input element its use is strongly advised in the call to the #createFormElement macro.

Attributes

placeholder
The placeholder attribute specifies a short hint that describes the expected value of an input field. This can be in the form of a sample value or a short description of the expected format. The short hint is displayed in the input field before the user enters a value.
All input elements in formMaker can (and should) be provided with a placeholder, except for the following input elements:

• Checkbox and radio
• Date
• Color
• Range

aria-label
The aria-label attribute is used to give the input element a description of its purpose in the form of a full sentence. The value of this attribute is used by screen readers only and therefore improves accessibility of the formʼs presentation.

Define an aria-label for an input element that asks for the type of car you own.

help-block
The help-block is a separate block of text, displayed below the input element. It is meant for a complete description of the inputʼs purpose, the format that is expected and eventual examples. The value of this input can be given in the form of plain text or a translation rendering. As such, please remind yourself not to forget the punctuation. It is advised to always use this attribute, except for the odd exception where the use of this attribute is truly superfluous.

data-error-response-type
The data-error-response-type attribute is used for the grammatical makeup by which the error is being displayed. The error response is generated with help from the label, which is why the label should be very concise and without pronoun or article. The main groups of response types are responses based on possessive adjectives (i.e. “your”), definite articles (i.e. “the”) and indefinite articles (i.e. “a” or “an”). All languages have their own articles and sometimes these can add up, the German language for example has 6 different possessive pronouns, 6 different definite and 6 different indefinite articles. These different pronouns and articles can be defined in the pageMaker translation document.
The different responses are:

• use_label_possessive_1, up to use_label_possessive_8
• use_label_definite_1, up to use_label_definite_8
• use_label_indefinite_1, up to use_label_indefinite_8

When this attribute is not used, the hint falls back on a non-descript default message.

Optional specific attributes

Some attributes are beholden to one specific type of input element only. For example, the range-step attribute is meant only for the range input element, it cannot be used in any other type of input element.

The text input element

data-pattern
The data-pattern attribute is used to test the input against the regular expression found in the value of this attribute.
For example the following code can be used if the user is only allowed to enter letters (case insensitive), numbers and underscores, with a minimum of four characters.

The number input element

data-decimals
The data-decimals attribute refers to the number of decimals the input should have. This attribute can only be used when the type attribute is set to number. When this attribute is not used it defaults to 0.

decimal-step
The decimal-step attribute is used together with the data-decimals attribute and refers to the size of the inclination of the number when the input has the focus and the mouse wheel or keyboard arrows (up and down) is used. This attribute can only be used when the type attribute is set to number. When this attribute is not used it defaults to 1.

The date input element

date-min
The date-min attribute stands for the minimum date that can be chosen from the calendar. The value of this attribute should be a date, in the format yyyy-mm-dd. This is an optional attribute.

date-max
The date-min attribute stands for the maximum date that can be chosen from the calendar. The value of this attribute should be a date, in the format yyyy-mm-dd. This is an optional attribute.

The range input element

range-minmax
The range-minmax attribute stands for the range in which the slider of the range input element operates. The value of this attribute should be two numbers, separated by a dash, i.e. 20-80. When this attribute is not used it defaults to 0-100.

range-step
The range-step attribute stands for the size of the interval with which the slider moves. In a range of 0-100 with a step of 5 there are 20 different possible positions to set as value for the slider. When this attribute is not used it defaults to 1.

The checkbox or radio input element

data-opener
The predetermined input elements can also serve the purpose of opening up a new section in the form. This is done by adding the attribute data-opener with the value true.

The section that is controlled by this predetermined input can be added with the Velocity macro #createExpandStart and #createExpandend.

The select input element

One of the ways to create options for the select input element is to have pageMaker search for all first-level decendants in a given parent space. The other way is to provide a map of values (the keys) and descriptions (the values) for each option, it creates child spaces if the key is a an XWiki reference. One of these attributes must be provided because without it, no options are created.

select-space-reference
The select-space-reference attribute references the parent space which will be queried for all direct descendant spaces it has. The value of this attribute is formatted like an XWiki reference but without the .WebHome ending. This query results in an HTML list of option elements where the values of the option elements are the page reference (including the parent space, without .WebHome) and the contents of the option elements is the title of the page which is referenced.

select-spaces-json
By using the select-spaces-json attribute, pageMaker creates a json object from all the direct descendants, which will be logged in the console (in the browser's development tools). This JSON object can be copied from the console and used in the select-json attribute.

select-json
The select-json attribute contains a map which lists the values and contents of each HTML option tag. When the keys in the map represent an XWiki reference, XWiki pages will be created at the locations referenced if they do not yet exist. The title of these pages are formed from the values in the map if they do not yet exist or if they deviate from the values in the map.
If you do not yet have any structure of child spaces set up, this is an easy way of doing so. Not only will all child spaces be created on the fly, the order of the map is also maintained in the options (the order of the map is the order of the options).

select-json-spaces
By using the select-json-spaces attribute, pageMaker creates spaces from the json object properties, where the key will serve as the XWiki reference and the value will be the title of the space. The select-json-spaces attribute will also make sure that each of these newly created spaces will be provided with an XObject based on the “pagemaker.pagemakerClass” XWiki class which makes it possible to customize the order of these spaces in the select element (when swithing back to the select-space-reference attribute).

Later on it is possible to switch back to the select-space-reference attribute if there is a wish to do so. Using the previous example, this would look like:

data-opener
With the use of the data-opener attribute, the select input element can also serve the purpose of opening up a new section in the form, just as is described in the checkbox or radio input element. The procedure and logic is also the same as in the checkbox or radio input element.

The textarea input element

textarea-rows
The textarea-rows attribute refers to the number of rows the textarea input field should get. When this attribute is not used it defaults to 8.

Create an active suggestion list for the input

It is very helpful for the user when he or she gets suggestions of what needs to be typed (or should not be typed) in the input field. This is also very helpful in maintaining the logic and integrity of the wiki contents. As the formMaker tool is meant to create wiki pages, a suggestion list is something a user cannot do without.

To create an active suggestion list for the input, certain information is necessary to define in the macro call for a new input.

• FormMaker needs to know where to find the JSON file from which it can build up the suggestion list and how this JSON file is created, namely as the result of an XWQL query or just a static JSON file. This is made known to formMaker by the attribute data-query-type.
• If the JSON file will be the result of an XWQL query, formMaker needs to know where it needs to perform this query, which is done so by using the attribute data-query-scope.
• Usually an active suggestion list is regarded as a list of suggestions that correspond with the partial input of the user, from which the user can then select the most appropriate item. In formMaker this is called a “suggest-select” list. It can also be the other way around, a list of suggestions of what the user should avoid to type, which is called a “suggest-negate” list. This is defined in the attribute data-query-list-type.
• FormMaker also needs to be told what needs to be shown in the suggestion list, the value, the key or both, and in which order. This is defined by the attribute data-query-list-contents.
• The active suggestion list can be provided with a header which can inform the user about what to expect from these suggestions. This is defined by the attribute data-query-list-header.
• Is the user able to type in new, original input or is the input explicitly beholden to the suggestions given? This can be defined by the attribute data-query-list-editable.

Attributes

data-query-type
The data-query-type attribute identifies the type and name of the file that is requested through XMLHttpRequest. The value of this attribute is defined in the form of a XWiki reference. Beside the difference in the necessity of also defining the data-query-scope attribute, this distinction is made to keep ready made JSON files and XWQL made JSON files seperate from each other in two different spaces. These spaces are:

• /assets/formMaker/JSON
• /assets/formMaker/XWQL

Define an XWQL query which is created in the XWiki page “matchObject” that produces a JSON object which can be used as a basis for specific results in this form element.

data-query-scope
The data-query-scope attribute identifies the space (or child space) in which a query is performed. In other words, if the data-query-type is defined as XWQL, the data-query-scope attribute should always be provided. The space in this attribute can also be a nested space, which can be defined by separating the spaces with a circumflex (^). For example: ParentSpace^ChildSpace.

Define the space on which the XWQL query is being perfomed.

data-query-list-type
The data-query-list-type attribute identifies which function the list has, suggest-negate or suggest-select.

• suggest-negate checks if the input value is unique and gives a list of similar values that the user should avoid.
• suggest-select gives a list of values similar to the input, from which the user can or should choose the right one.

When this attribute is not being used or has no value or a non existent value it defaults to suggest-select.

Create a text input that after input of one character, generates a list with clickable suggestions that will be set as the value of the input when clicked.

data-query-list-contents
The data-query-list-contents attribute identifies how the suggest list will be displayed and what part of the JSON will be queried. The possibilities are:

• key: Perform a query on the JSON keys and show only the found key(s).
• key/value: Perform a query on the JSON keys and show the found key(s) with the value(s) beside it in parenthesis.
• value: Perform a query on the JSON values and show only the found value(s).
• value/key: Perform a query on the JSON values and show the found value(s) with the key(s) beside it in parenthesis.

Create a text input with a suggestion list that displays the similar keys from the JSON file and the values in parenthesis next to it.

data-query-list-header
The data-query-list-header attribute defines the text to be displayed as the header of the suggestion list. This can be a line of text or an XWiki translation rendering. The translation file standardly used for formMaker is located at assets/formMaker/translations.

Create a suggestion list header that can be translated in the available languages on your wiki.

data-query-list-editable
The data-query-list-editable attribute identifies if the suggestions are explicit or not. Set to false is making a selection from the suggestions the only possible input. It cannot be altered in the input afterwards. If set to true, random input is possible but the suggestions make the input more easy and helps keeping the stored object property values cleaner or more neato.
When this attribute is left out this option will default to false.

Create a suggestion list that does not have to be followed explicitly so input that differs from the suggestions displayed is allowed.

Full example

Create a text input element that offers a list of choices to select the value from. Other values (that differ from the ones suggested in the list) are not allowed.

The result:

The creation of XWiki pages

As stated in the introduction, this application creates XWiki pages. The construct of this component is fairly straightforward and consists of two different input elements, one for the selection of the space and one for the name of the page.

Attributes

data-set-space
The data-set-space attribute must be set to true if this input is used to select the name of the (child) space in which you want to create the wiki page. If set to true the value of the input that is set by the user will be used as the space in which to create the new wiki page.

Changes to the element that has a data-set-space attribute will affect the element with the data-create-page attribute. Specifically, it appends the (child space part of the) value of the 'space setting' element to the (parent space part of the) value of the data-query-scope attribute from the 'page input' element, thus creating an XWiki reference to the space where the page should be saved.

Create a select input with which a user can select a space where the page that is to be created will reside.

data-create-page
The data-create-page attribute should be set to true if this input is used for the creation of a page. The value of the input will be used as the document name and the title of the newly created wiki page. In all but the odd exeption this attribute is used in conjunction with the text input type.

The input that has this attribute must also have a data-query-scope attribute.

Create a text input in which a user can type the name of the page that will be created.

Adding XObjects to the new XWiki page

Limited to 100 objects per page.

Attributes

data-create-xobj
The data-create-xobj attribute identifies if an XObject property should be created. When this attribute exists (regardless of the value), the input element that has this attribute will be used to create the XObject property. If the XObject does not exist yet, it will be created. For the purpose of writing correct HTML, set the attribute value to true.
This attribute should be used together with the attributes data-xobj-classname and data-xobj-fieldname. The value the user puts into the text input will be used as the value for the XObject.

data-xobj-classname
The data-xobj-classname attribute refers to the name of the class object that you have created at an earlier point. It should have the fields you need for this purpose.

data-xobj-fieldname
The data-xobj-fieldname attribute identifies the name of the XObject property that should be created. The value of the XObject property is added by using the value of the input. The value should be the name of the XObject property that you want to create.

Create a text input that adds a Class XObject to the wiki page you are creating and adds the value of the user input to the remedy field of this Class XObject.