Handbook

• List all 254 pages (en)

• Wikidot for beginners
• Editing for beginners
• Site creation for beginners

Advanced users:

• Advanced Wikidot usage
• Advanced editing
• Advanced site management

Third level:

• User and community control
• Content control
• Site promotion

I Moduli per dati rendono possibile la costruzione di semplici applicazioni in siti Wikidot. Una normale pagina wiki contiene il testo non strutturato. Una pagina wiki con un modulo dati contiene dati strutturati ("campi"). I dati strutturati, in molti casi, sono più facili da modificare, da capire, e da lavorare.

Il sistema di invio dati è nuovo e in rapida evoluzione. Se avete feedback su di essa, venire a discutere con noi questo forum in inglese.

Esempi di utilizzo dei moduli dati

Ecco alcuni esempi in cui i moduli dati potrebbero funzionare meglio di semplici pagine wiki:

• Sto raccogliendo i riferimenti per la mia tesi, e per ogni riferimento voglio registrare il suo titolo, autore, ISBN, data di rilascio, editore, e la lingua. Se uso un modulo dati con un campo per ogni porzione di dati, posso facilmente produrre elenchi di riferimento in qualsiasi formato.

• Sto organizzando la mia appartenenza al club e per ogni membro voglio una pagina con il nome, indirizzo email e così via. Utilizzando un modulo dati posso estrarre i campi come l'indirizzo email di inviare a tutti una newsletter.

• Sto catalogando la mia collezione di videogiochi e l'utilizzo di un modulo dati mi consente la ricerca dei giochi per console, per editore, e così via.

Come creare un nuovo modulo dati

Wikidot salva le pagine in categorie e quando si utilizzano i moduli di dati, ogni pagina è uno "oggetto". Quindi una categoria può avere un modulo dati, che si applica a tutte le pagine in quella categoria.

Per creare un nuovo modulo dati, modificare la pagina _template nella categoria e aggiungere una sezione [[form]] .
Ecco un semplice modulo che mostra alcuni campi:

[[form]]
fields:
 name:
 label: Member name
 email:
 label: Email address
 get-newsletter:
 label: Get newsletter?
 values:
 0: "No"
 1: "Yes"
 default: 1
[[/form]]

Quando si definisce una sezione [[form]], tutte le pagine della categoria, come per magia, mostrano il modulo anzichè il solito editor di pagina.

Come usare il modulo dati

Il modo più semplice per utilizzare un modulo dati è quello di permettere alle persone di entrare, esplorare e migliorarlo, così come per le normali pagine wiki.
È possibile configurare le autorizzazioni di categoria esattamente come per le pagine normali, in modo che, per esempio, solo l'autore di una pagina possa modificarla. Se si guarda il sorgente della pagina si noterà che i moduli dati sono archiviati in un formato che sembra un po 'come la definizione del modulo stesso.

È inoltre possibile utilizzare i dati dei moduli in elenchi e relazioni, usando
ListPages module:

Queste prprietà possono essere utilizzate in live templates per avere un maggior controllo sulla presentazione del modulo dati sulla pagina.

Is %%form_data{member-name}%% subscribed to the newsletter? %%form_data{newsletter}%%
====
[[form]]
fields:
 member-name:
 label: Member name
 newsletter:
 label: Subscribe to newsletter?
 type: select
 values:
 1: "Yes"
 2: "No"
[[/form]]

The Pagepath concept

Wikidot data forms have a unique concept, the Page Tree and pagepath, which is a way of organizing data. Imagine your video games collection, and you want to store for each game the genre of game. Game genres form a tree:

• _root
  • Adventure
  • Action
    • Simulation
      • Driving
      • Other
    • Combat
  • Sports
    • Football
    • Racing

where each part of the tree is a wiki page. Imagine this tree is held in a category called genre:. Now we can use parent links to attach Racing to Sports, and Driving to Simulation to Action.

The Wikidot data form system makes it easy to navigate, and edit such a tree. You define a 'pagepath' field and tell it to use the genre: category. Then users can chose any genre, making the tree more precise (if the genre: category lets them create and edit pages) over time:

[[form]]
fields:
 genre:
 label: Game genre
 type: pagepath
 category: genre
[[/form]]

A page tree is always anchored to a page called _root that Wikidot creates automatically when you start using a page tree in forms.

Deleting a form

If you wish to remove a form from the _template, do not simply comment it out. Either delete it completely or change [[form]] to something like [[x-form]]. Otherwise the form will continue to be used.

Reference

The form definition is made in YAML, which is a simple structured markup language. A _template may have a single form. The form starts and ends with [[form]] and [[/form]] as for code blocks. Within those tags, we describe the form using YAML:

[[form]]
fields: # This is always required at the start
 name-of-the-field: # Use a valid YAML name
 label: Label # This is what the user sees
 type: type-of-field # The field types
 property: value... # Depending on the field type
[[/form]]

The default field type is 'text', unless you specify one or more values, in which case it defaults to 'select'.

Field Properties

Properties that apply to all field types

The 'label' property

If you specify a 'label' property then the field gets that text in the left column, or before the field for joined fields. If you do not specify a label then the field has an empty space in the left column, or is squashed up after the previous field, for joined fields. For example:

[[form]]
fields:
 address-line-1:
 label: Address
 width: 30
 address-line-2:
 width: 30
 address-line-3:
 width: 30
[[/form]]

The 'join' property

If you specify 'join: true' then the field is placed after the previous field, if any. This property has no effect if the field is the first in the form. For example:

[[form]]
fields:
 city:
 label: City
 width: 20
 postcode:
 label: Postcode
 width: 8
 join: true
[[/form]]

The 'before' property

Provides a string of plain text that displays before the field value

[[form]]
fields:
 phone:
 label: Phone
 width: 10
 before: +(1)
[[/form]]

The 'after' property

Pprovides a string of plain text that displays after the field value

[[form]]
fields:
 speed:
 label: Car speed
 width: 4
 after: mph
[[/form]]

Properties that apply to specific field types

There are additional properties that only apply to specific field types. These are documented below with the field type(s) they apply to.

Field Types

The 'text' field type

Defines a text or text box field. Allows 'width' and 'height' as properties. If you don't specify a height you get a normal 1-line text field. If you do specify it, you get a text box. For example:

[[form]]
fields:
 name:
 label: Your name
 type: text
 width: 30
 comment:
 label: Your comment
 type: text
 width: 50
 height: 3
 email:
 label: email address
 match: /^[_a-zA-Z0-9\-\+]+(\.[_a-zA-Z0-9-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+$/
[[/form]]

The specific properties you can use on a text field:

• width: specifies the visible field width in columns (fixed spaced characters, more or less).
• height: specifies the field height in rows, 1 is normal text field, 2 or more is a text box.
• match: specifies a regular expression that the field value must match.
• match-error: specifies a custom error message.
• hint: provides a string of text that is displayed in the field when empty.
• default: defines a default value for the field shown on new pages.

The 'select' field type

Defines a multi-value selection field. Requires a set of values. If you specify two to four values, you get a horizontal radio field. If you specify five or more values, you get a drop-down select field. For example:

[[form]]
fields:
 your-mood:
 label: Your mood
 type: select
 values:
 1: manic
 2: happy
 3: calm
 4: down
 5: depressed
 her-mood:
 label: Her mood
 type: select
 values:
 1: silent
 2: chatty
[[/form]]

The specific properties you can use on a select field:

• default: defines a default value for the field shown on new pages.

The 'checkbox' field type

Defines a checkbox field, stored in the form data as 0 or 1. For example:

[[form]]
fields:
 onions:
 label: Do you want onions?
 type: checkbox
 salami:
 label: How about extra salami?
 type: checkbox
 default: 1
[[/form]]

The specific properties you can use on a checkbox field:

• default: defines a default value for the field shown on new pages.

The 'pagepath' field type

Lets the user create and select from a page within a page tree; the 'path' is the list of all parents plus that page. It is visualized as page / page / page / page with at each level, the option of viewing that page, changing the page, or adding a new child. This does not affect the actual page parent, and a form can have many pagepath fields. The pagepath field value is stored as a page full name. Hidden pages are invisible to users when selecting and navigating the page tree.

[[form]]
fields:
 genre:
 label: Game genre
 type: pagepath
 category: genre
[[/form]]

The specific properties you can use on a pagepath field:

• category: specifies the category that holds the page tree.
• default: defines a default value for the field shown on new pages.

The 'hidden' field type

Adds data to the form that the user cannot see or edit. Takes no space visually. This is for putting data into the page so that data can be used later. The value of the field is defined by the 'value' property.

[[form]]
fields:
 version:
 type: hidden
 value: 1.0
[[/form]]

The specific properties you can use on a hidden field:

• value: sets the value of the field

The 'wiki' field type

Works like text but lets the user enter a block of wiki text. Note: wiki text is not allowed in normal text fields, it must be enabled explicitly with wiki fields.

[[form]]
fields:
 version:
 label: Fancy text field
 type: wiki
[[/form]]

The 'static' field type

This shows uneditable wiki text and lets the form designer add text and formatting to the form. Static fields are not stored in the page. Static fields get their value from the 'value' property.

[[form]]
fields:
 version:
 type: static
 value: Non-storable field with with **bold**, //strike// and __underline__.
[[/form]]

The specific properties you can use on a static field:

• value: sets the value of the field

The 'file' field type

This lets the user upload files directly from the data form. It is displayed as a link to the file.

Files are not uploaded to the same page. Instead, a separate page is created for each file in a different category, 'file' by default.

[[form]]
fields:
 document:
 type: file
 label: Upload document
 category: alternative-category
[[/form]]

The specific properties you can use on a file field:

• category: specifies the category that the page will be created in ('file' category if not specified), and the uploaded file is attached to this page.

The 'url' field type

This lets the user enter URLs. This is displayed as a link.

[[form]]
fields:
 info_link:
 type: url
 default: ftp://example.com/files/
 match-error: Custom error msg.
 required: true
 default-schema: ftp://
[[/form]]

The specific properties you can use on a url field:

• width: specifies the visible field width in columns (fixed spaced characters, more or less).
• default: defines a default value for the field shown on new pages.
• default-schema: define a default schema for URL ('http://' if not specified).
• match-error: specifies a custom error message.
• required: specifies if the field is mandatory [true/false] ('false' if not specified).

The 'password' field type

This lets the user enter masked text. To the user, each character they type is replaced by an asterisk ( * ).

[[form]]
fields:
 pass:
 type: password
[[/form]]

Important: Entered text is not encrypted, you can always read it in page source.

CSS Styling

You can modify the look and feel of your data forms using CSS (either per-site, or per page using the CSS module. This is the CSS model for data forms:

• table
  class: form-table
  • tr
    class: form-row
    • td
      class: form-labels
      • span
        class: form-label
    • td
      class: form-values
      • span/div (div for wiki and static)
        class: form-value field-{name}
        class': form-error (added to field while save when there is matching error)
        • label (auto-added to form when field have defined hint property)
          class: form-hinted
        • {field}
          class: form-{type}
        • span
          class: form-message

Symbols:

{name} - name of the field
{type} - type of the field (text, select, pagepath etc.)

Live demo

• The forms.wikidot.com site is a live demo of the features of data forms.
• pagepath.wikidot.com shows examples of the pagepath concept.

*