Moduli per dati

Benvenuto! » Moduli per dati

(Pagina originale = http://www.wikidot.com/doc:data-forms )

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:

%%form_data{name}%%	Valore di campo dalla pagina data form se esiste
%%form_raw{name}%%	Per selezionare i campi e percorso della pagina, il valore interno salvato nel modulo dati della pagina. Per altri tipi di campo, vuoto.
%%form_label{name}%%	Etichetta e campo come definiti in data form se esiste
%%form_hint{name}%%	Il suggerimento del campo come definito in data form se esiste

Queste proprietà 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]]

Il concetto di percorso della pagina (Pagepath)

I moduli dati di Wikidot hanno un concetto unico, l'albero delle pagine ed il percorso pagina, che sono il modo in cui sono organizzati i dati.
Immaginate la vostra collezione di video giochi, e supponiamo che desideriate archiviare per ogni gioco, il genere del gioco.
I generi dei giochi formano un albero:

_root
- Avventura
- Azione
  - Simulazione
    - Guida
    - Altro
  - Combattimento
- Sport
  - Football
  - Corse

dove ogni parte dell'albero è una pagina wiki. Supponiamo che questo albero sia compreso in una categoria chiamata genere. Possiamo usare i link per collegare Corse a Sport, Guida a Simulazione e ad Azione.

Il sistema di moduli per dati rende facile navigare e modificare tale albero.
Definite un campo pagepath (percorso pagina) e ditegli di usare la categoria genere. Gli utenti possono scegliere qualsiasi genere, rendendo l'albero più preciso nel corso del tempo (se la categoria genere consente loro di creare e modificare pagine).

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

Un albero di pagina è sempre ancorata ad una pagina chiamata _root che Wikidot crea automaticamente quando nei moduli si inizia con un albero di pagine.

Eliminazione di un modulo

Se desiderate eleiminare un modulo dal _template, semplicemente non mettete commenti.
Oppure cancellatelo completamente o cambiate [[form]] in qualcos'altro come [[x-form]]. Altrimenti il modulo continuerà ad essere usato.

Riferimenti

La definizione del modulo è realizzata in YAML, che è un semplice linguaggio strutturato di markup (cioè a marcatori, come ad esempio il linguaggio html).
Un _template può avere un modulo singolo. Il modulko inizia con [[form]] e termina con [[/form]] come i blocchi di codice. All'interno di questi tags, viene descritto il modulo usando YAML:

[[form]]
fields:                           #  Questo è spesso richiesto all'inizio
  name-of-the-field:              #  Usate un valido nome YAML 
    label: Label                  #  Questo è ciò che l'utente vede
    type: type-of-field           #  I tipi di campi
    property: value...            #  Dipende dal tipo del campo
[[/form]]

Il tipo di campo di default è 'text' (testo), a meno che non vengano specificati uno o più valori, nerl qual caso il default è 'select' (scegli).

Si deve iniziare sempre il nome del campo con una lettera. I nomi dei campi che iniziano con una cifra o un altro carattere non sono validi. In caso di particolari simboli YAML come true, false, yes, no, potrebbe essere necessario circondare i medesimi con virgolette così: "yes".

Proprietà dei campi

Proprietà valide per tutti i tipi di campi

La proprietà 'label' (etichetta)

Se si specifica una proprietà 'label' (etichetta), il campo mette il testo nella colonna di sinistra, o prima del campo, per i campi collegati. Se non si specifica alcuna etichetta, il campo ha uno spazio vuoto nella colonna di sinistra, oppure viene schiacciato in alto, dopo il campo precedente, per i campi collegati.
Per esempio:

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

La proprietà 'join' (riunisci)

Se si specifica 'join: true', allora il campo è posizionato dopo il campo precedente, se presente. Questa proprietà non ha effetto se il campo è il primo inel modulo.
Per esempio:

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

La proprietà 'before' (prima)

Fornisce una stringa di testo visualizzata prima del valore di campo

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

La proprietà 'after'

Fornisce una stringa di testo visualizzata prima del valore di campo

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

Proprietà che si applicano a tipi specifici di campo

Ci sono proprietà aggiuntive che si applicano solo ai tipi specifici di campo. Esse sono documentate qui di seguito con il tipo di campo/campi cui si riferiscono.

Tipi di campi

Il campo di tipo 'text' (testo)

Definisce un campo testo o una casella testo. Consente le proprietà 'width' (larghezza) e 'height'(altezza). Se non si specifica l'altezza si ottiene un normale campo testo di 1-linea . Se invece si specifica, si ottiene una casella di testo.
Per esempio:

[[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]]

Proprietà specifiche che si possono utilizzare in un campo testo:

width:specifica la larghezza del campo visibile nelle colonne (fisso caratteri spaziati, più o meno).
height: specifica l'altezza del campo in righe; 1 è campo di testo è normale, 2 o più è una casella di testo.
match: specifica un' espressione regolare a cui deve corrispondere il valore del campo.
match-error: specifica un messaggio di errore personalizzato.
hint: fornisce una stringa di testo che viene visualizzata nel campo quando è vuoto.
default: definisce un valore predefinito per il campo visualizzato nelle pagine nuove.

Il campo di tipo 'select' (scegli)

Definisce una selezione multi-valore di campo. Richiede un insieme (due o più) di valori. Se si specificano da due a quattro valori, si ottiene un campo orizzontale "radio". Se si specificano cinque o più valori, si ottiene un campo per selezione "a tendina".
Per esempio:

[[form]]
fields:
  Stato d'animo vostro:
    label: Stato d'animo vostro:
    type: select
    values:
      1: maniaco
      2: felice
      3: calmo
      4: abbattuto
      5: depresso
  Stato d'animo suo (di lei):
    label: Suo stato d'animo
    type: select
    values:
      1: silente
      2: ciarliero
[[/form]]

Proprietà specifiche che possono essere impiegate in un campo select.

default: definisce un valore predefinito per il campo visualizzato nelle pagine nuove.

Il campo di tipo 'checkbox' (casella di controllo)

Definisce un campo checkbox (casella di controllo), memorizzato nei dati del modulo come 0 oppure 1. Per esempio:

[[form]]
fields:
  cipolle:
    label: Gradite delle cipolle?
    type: checkbox
  salumi:
    label: Ancora salumi?
    type: checkbox
    default: 1
[[/form]]

Le specifiche proprietà che si possono usare in un campo checkbox:

default: definisce un valore di default per il campo mostrato in una pagina nuova.

Il campo di tipo pagepath (percorso della pagina)

Permette all'utente di creare e selezionare da una pagina all'interno di un percorso di pagina; il 'percorso' è la lista di tutti i "parents" (genitori), più quella pagina. E ' visualizzato come page / page / page / page con, ad ogni livello, la possibilità di visualizzare quella pagina, cambiare la pagina, o aggiungere un nuovo figlio. Ciò non incide sul genitore effettiva della pagina, e un modulo può avere molti campi pagepath. Il valore del campo pagepath viene memorizzato come un nome di pagina intera. Le pagine nascoste sono invisibili agli utenti quando scelgano o navigano nell'albero delle pagine.

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

Proprietà specifiche che possono essere usate in un campo pagepath (percorso):

category: specifica la categoria che contiene l'albero delle pagine
default: definisce un valore predefinito per il campo visualizzato nelle pagine nuove

Il campo di tipo 'hidden' (nascosto)

Aggiunge al modulo dati che l'utente non può vedere o modificare. Non prende alcun spazio visivo. Questo consente di mettere i dati nella pagina in modo che i essi possano essere utilizzati in seguito. Il valore del campo è definito dalla proprietà 'valore'.

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

Le proprietà specifiche che si possono utilizzare in un campo "hidden" (nascosto):

value: imposta il valore del campo

Il campo di tipo 'wiki'

Opera come testo, ma consente all'utente di inserire un blocco di testo wiki. Nota: Il testo wiki non è consentito nei campi di testo normale, ma la funzione deve essere abilitata esplicitamente con i campi di wiki.

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

Il campo di tipo 'static' (statico)

Mostra un testo 'wiki' non modificabile e permette la progettazione del modulo aggiungere testo e formattazione per il modulo. I campi 'static' (statici) non vengono memorizzati nella pagina. I campi statici ottengono il loro valore dalla proprietà 'valore'.

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

Le proprietà specifiche che si possono utilizzare su un campo statico:

value: imposta il valore del campo

Il campo di tipo 'file'

Questo campo consente all'utente di caricare i file direttamente dal modulo di dati. Viene 'visualizzato come un link al file.

I file non vengono caricati nella stessa pagina. Invece, per default, viene creata una pagina separata per ogni file in una categoria diversa, 'file'.

[[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.

Note that images won't be treated like they are when attaching an image to simple (non-data-form-enabled) page. This means there will be no thumbnails for them and they won't be displayed by [[gallery]] tag. We plan to make it more consistent with regular uploads, though. See the corresponding wish and if you feel this is an important issue, rate it up.

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