XWiki Syntax 2.0

Generale

Preliminare

2.0 Introduction

A partire dalla versione 1.7 di XWiki Enterprise abbiamo introdotto una nuova sintassi di xwiki. La vecchia sintassi era stata chiamata Sintassi XWiki 1.0 e la nuova sintassi fu chiamata conseguentemente Sintassi XWiki 2.0. I motivi principali per l'introduzione di una nuova sintassi sono stati i seguenti:

• Superare i limiti e le ambiguità della sintassi XWiki 1.0 (che fu ispirata sia da Radeox - il motore di rendering sottostante- e da TWiki).
  • Simboli non ottimali. Per esempio il simbolo per il grassetto era un asterisco singolo. Ciò causava problemi quando gli utenti inserivano del testo che conteneva degli asterischi, dal momento che il testo seguente veniva considerato erroneamente in grassetto, mentre non lo era affatto. Per cui abbiamo razionalizzato la sintassi usando almeno caratteri doppi ovunque possibile.
  • Ambiguità. Per esempio c'era ambiguità tra una voce in grassetto all'inizio di una riga ed un elenco puntato. Era necessario risolvere le ambiguità per poter riscrivere l'editor WYSIWYG in modo che fosse deterministico.
• Per essere più vicini alla Sintassi Creole 1.0 che sta diventando lo standard delle sintasssi per i wiki. Inoltre la comunità di Creole ha speso del tempo per analizzare tutte le sintassi dei wiki esistenti prima di decidere i simboli da usare. Per cui le scelte fatte sono molto buone.

Oltre a queste due sintassi specifiche di XWiki abbiamo modificato anche il motore di rendering sottostante con XWiki Enterprise versione 1.7 (precedentemente era Radeox) in favore di un nostro motore che è un superset wrapper attorno a Wikimodel e Doxia (e si spera altri in futuro). Questo ci ha consentito di poter usare anche altre sintassi nel wiki: MediaWiki, Confluence, JSPWiki, Creole, TWiki e altre.

Considerazioni Generali

2.0 General Remarks

La sintassi XWiki 2.0 corregge alcuni errori o ambiguità che gli utenti potevano inserire come mostrato negli esempi della tabella seguente.

Altre sintassi

1.0 Other Syntaxes

A partire da XWiki Enterprise 1.6 sono implementate anche queste altre sintassi:

• JSPWiki
• MediaWiki
• Confluence
• TWiki
• Creole 1.0
• XHTML 1.0

Modifica

Paragrafi

2.0 Paragraphs

I paragrafi sono elementi di testo separati da 2 o più righe vuote.

Titoli

2.0 Headings

= livello 1 = 
== livello 2 ==
=== livello 3 ===
==== livello 4 ====
===== livello 5 =====
====== livello 6 ======

Formattazione Testo

2.0 Text Formatting

Riga Orizzontale

2.0 Horizontal Line

(% style="color:blue" %)
----

Elenchi

2.0 Lists

* voce 1
** voce 2
*** voce 3
* voce 4

1. voce 1
11. voce 2
111. voce 3
1. voce 4

1. voce 1
1*. voce 2
1*. voce 3
1. voce 4

(% style="list-style-type: square" %)
* voce 1
* voce 2

(% style="list-style-type: disc" %)
* voce 1
* voce 2

(% style="list-style-type: lower-alpha" %)
* voce 1
* voce 2

(% style="list-style-type: upper-alpha" %)
* voce 1
* voce 2

(% style="list-style-type: lower-roman" %)
* voce 1
* voce 2

(% style="list-style-type: upper-roman" %)
* voce 1
* voce 2

(% style="list-style-type: lower-greek" %)
* voce 1
* voce 2

(% style="list-style-type: upper-greek" %)
* voce 1
* voce 2

(% style="list-style-type: hiragana" %)
* voce 1
* voce 2

(% style="list-style-type: hiragana-iroha" %)
* voce 1
* voce 2

(% style="list-style-type: katakana" %)
* voce 1
* voce 2

(% style="list-style-type: katakana-iroha" %)
* voce 1
* voce 2

(% style="list-style-type: armenian" %)
* voce 1
* voce 2

(% style="list-style-type: hebrew" %)
* voce 1
* voce 2

(% style="list-style-type: georgian" %)
* voce 1
* voce 2

(% style="list-style-type: cjk-ideographic" %)
* voce 1
* voce 2

Elenchi di Definizione

2.0 Definition Lists

; termine
: definizione

; termine1
: definizione1
:; termine2
:: definizione2

(% style="color:blue" %)
; termine
: definizione

Nuova riga/Interruzioni di riga

2.0 New Line Line Breaks

Una nuova riga è un ritorno a capo. Un'interruzione di riga è una nuova riga forzata che può comparire in un punto qualsiasi del testo.

Collegamenti - Links

2.0 Links

Caratteristica	Sintassi XWiki 2.0	Risultato
Link ad una pagina nello Spazio corrente	[[WebHome]]	XWiki
Link con etichetta	[[etichetta>>WebHome]] La sintassi XWiki è supportata anche all'interno delle etichette	etichetta
Link con sintassi XWiki nell'etichetta	[[**etichetta in grassetto**>>WebHome]]	etichetta in grassetto
Link ad una pagina di uno spazio specificato	[[Main.WebHome]]	Main
Link ad un subwiki	[[subwiki:Main.WebHome]]	Main
Link che si apre in una nuova pagina	[[etichetta>>WebHome||rel="__blank"]]	etichetta
Link ad un URL direttamente nel testo	Questo è un URL: http://xwiki.org	Questo è un URL: http://xwiki.org
Link ad un URL	[[http://xwiki.org]]	http://xwiki.org
Link ad un URL con etichetta	[[XWiki>>http://xwiki.org]]	XWiki
Link ad un indirizzo email	[[john@smith.net>>mailto:john@smith.net]]	john@smith.net
Link ad un'immagine	[[image:Space2.Page2@img.png>>Space1.Page1]]
Link ad un'immagine con parametri	[[[[image:Space2.Page2@img.png||width="26" height="26"]]>>Space1.Page1]]
Link ad un allegato nella pagina corrente	[[text>>attach:img.png]]	text
Link ad un allegato in una pagina diversa	[[text>>attach:Space.Page@img.png]]	text
Link ad una Ancora in una pagina	[[label>>Space.Page#anchor]]	label
Link ad un Titolo in una pagina	[[label>>Space.Page#HMyheading]]	label

Specifiche dei link con la Sintassi XWiki 2.0

Il formato completo di un link è [etichetta>>] (risorsa) [@interWikiAlias] [||parametri]

• etichetta: Stringa opzionale che sarà mostrata all'utente dopo il render del link. L'etichetta può contenere della sintassi XWiki. Se non viene specificata un'etichetta sarà generata un'etichetta predefinita. Il modello di generazione può essere cambiato, vedere la Admin Guide. Esempio: My Page
• risorsa: Il riferimento completo al link con la sintassi seguente: (riferimento) [?Stringaquery] [#ancora]
  • riferimento: Il riferimento al collegamento in una delle forme seguenti:
    • URL: qualsiasi URL nella forma protocollo://percorso. Esempi: http://xwiki.org, https://svn.xwiki.org/
    • Nome pagina Wiki riferimento nella forma [[NomeWiki:] spazio.] (pagina). Esempi: WebHome, Main.WebHome, mywiki:Main.WebHome
      • NomeWiki: Stringa opzionale che contiene il nome di un subwiki (animal) di una 'farm' di wiki. Il link punterà ad una pagina all'interno di quel subwiki. Esempio: miowiki
      • spazio: Nome opzionale di uno Spazio del wiki. Se non si specifica uno spazio verrà usato lo spazio corrente. Esempio: Main
      • pagina: Stringa obbligatoria che contiene il nome della pagina del wiki cui si vuole collegarsi. Esempio: WebHome
    • Allegato riferimento nella forma attach: [wikiPageName@] (attachmentName). Esempi: attach:img.png, attach:mywiki:Main.WebHome@img.png
      • attach:: Stringa richiesta che identifica la risorsa come allegato.
      • wikiPageName: Stringa opzionale con il riferimento al documento che contiene l'allegato, vedere sopra "Wiki page name".
      • attachmentName: Nome dell'allegato come è stato memorizzato nel wiki.
    • indirizzo Email nella forma mailto: (emailAddress) (#anchor non è valido). Esempio: mailto:john@smith.com
      • mailto:: Stringa richiesta che identifica la risorsa come email.
      • emailAddress: Indirizzo del destinatario dell'email. Esempio: "john@smith.com"
  • Stringaquery: Stringa opzionale di query per specificare parametri che saranno usati nel rendering dell'URL. Esempio: mydata1=5&mydata2=Hello
  • anchra: Nome di un'ancora opzionale che punta ad un'ancora definita nel link cui si fa riferimento. Notare che in XWiki le ancore sono create automaticamente per i titoli. Esempio: HTableOfContents
• interWikiAlias: Alias opzionale Inter Wiki come definito nella InterWiki Map (vedere la Admin Guide). Questo vale solo per i nomi delle pagine wiki. Esempio: wikipedia
• parametri: elenco opzionale di parametri che si possono passare al link. Esempio: rel="__blank" (apri in una nuova finestra)

Tabelle

2.0 Tables

È possibile creare facilmente del testo in forma tabellare. Con la Sintassi XWiki 2.0 sono supportati anche parametri per la tabella, le righe o le celle.

!=Titolo 1!=Titolo 2
!!Parola 1!!Parola 2

(% style="background-color:red;text-align:center" %)
|=Titolo 1|=(% style="background-color:yellow" %)Titolo 2
|Parola 1|Parola 2

{{velocity}}
$xwiki.ssfx.use("js/xwiki/table/table.css")
$xwiki.jsfx.use("js/xwiki/table/tablefilterNsort.js", true)
{{/velocity}}

(% class="grid sortable filterable doOddEven" id="tableid" %)
(% class="sortHeader" %)|=Titolo 1|=Titolo 2
|Cella 11|Cella 12
|Cella 21|Cella 22

Immagini

2.0 Images

Caratteristica	Sintassi XWiki 2.0	Risultato
Immagine da un allegato nella pagina corrente	image:img.png
Immagine da un allegato di un altro documento	image:Space.Page@img.png
Immagine con parametri	[[image:img.png||width="25" height="25"]]
Immagini raggiungibili con un URL	image:http://some/url/img.png

Specifiche per le Immagini in Sintassi XWiki 2.0

Il formato completo di un'immagine è image: (riferimento) oppure [[image: (riferimento) {||parametri}]]

• image: Stringa richiesta che identifica la risora come immagine.
• riferimento: Il riferimento all'immagine che sarà mostrata in una delle forme seguenti:
  • URL: Un qualunque URL ad un'immagine nel formato http://percorso/Nomeimmagine. Esempio: http://domain.org/path/img.png
  • Allegato riferimento nel formato {{{Nomewiki:} spazio.} pagina@} (Nomeimmagine)
    • NomeWiki: Stringa opzionale che contiene il nome di un subwiki (animal) di una 'farm' di wiki. Il link punterà ad una pagina all'interno di quel subwiki. Esempio: miowiki
    • spazio: Nome opzionale di uno spazio del wiki. Se non si specifica uno spazio viene usato lo spazio corrente. Esempio: Main
    • pagina: Stringa opzionale che contiene il nome di una pagina del wiki a cui l'immagine fa riferimento come allegato. Esempio: WebHome
    • Nomeimmagine: Stringa richiesta con il nome dell'immagine allegata alla pagina così come è memorizzato nel wiki.
• parametri: Elenco opzionale di parametri separati da uno spazio passati all'immagine. Esempio: width="800" height="600" alt="img.png" title="My nice image"
  • Attributi HTML: Tutti gli attributi definiti dallo standard HTML saranno aggiunti al codice HTML renderizzato <img> tag.
    • style: Informazioni sullo stile CSS che si deve applicare all'immagine. Esempio: style="float:right;height:50" (immagina a destra, altezza 50 pixel), style="display:block;margin-left:auto;margin-right:auto;width:80%" (immagine centrata, larghezza 80% del blocco), style="vertical-align:bottom" (il testo inzia in basso all'immagine)
    • height: Parametro che definisce l'altezza visualizzata dell'immagine. Il valore dovrebbe essere in pixel (esempio: height="80") o in pixel relativi all'altezza del blocco contenente l'immagine (esempio: height="40%").
    • width: Parametro che definisce la larghezza visualizzata dell'immagine. Il valore dovrebbe essere in pixel (esempio: width="80") o in pixel relativi alla larghezza del blocco contenente l'immagine (esempio: width="40%").
    • title: Parametro che definisce il titolo visualizzato dell'immagine che sarà visibile quando ci si passa sopra con il mouse, per esempio. Esempio: title="La mia bella immagine"
    • alt: Parametro che definisce quale testo deve essere mostrato se il browser non è in grado di visualizzare l'immagine. Dal momento che questo è un attributo HTML richiesto XWiki userà il nome del file se il parametro alt non è definito. Esempio: alt="img.png"
    • Altro: Una spiegazione più approfondita sul tag HTML <img> tag che comprende altri attributi si può trovare su on w3.org.

Avanzato

Verbatim

2.0 Verbatim

Contenuto testuale, verbatim cioè parola per parola

Consente di inserire del contenuto che non sarà formattato (in altre parole non viene considerata la sintassi XWiki).

{{{
contenuto
**verbatim**
su più righe
}}}

contenuto
**verbatim**
su più righe

Citazioni

2.0 Quotations

Permette di citare, quotare, del testo.

> Giovanni ha detto questo
Io ho detto va bene

> Giovanni ha detto questo
>> Maria ha risposto questo
Io ho detto va bene

Gruppi

2.0 Groups

Si possono usare i Gruppi per inserire direttamete un altro documento nel documento corrente. Questo permette per esempio di inserire elementi complessi in una voce di un elenco o all'interno di una cella di una tabella. I Gruppi sono delimitati dai seguenti elementi sintattici:(((...))). Un Gruppo può contenere un altro Gruppo senza limiti di nidificazione.

|=Titolo 1|=Titolo 2|=Titolo 3
|Cella Uno|(((
= Documento incluso =

Alcuni paragrafi inclusi.

* voce elenco uno
* voce elenco due
** sotto elemento 1
** sotto elemento 2
))) | Cella Tre

Paragrafo successivo nel documento di livello superiore

Escapes

2.0 Escapes

Escapes - Commenti testo non valutato

Consente di commentare e quindi non valutare la sintassi XWiki

Parameters

2.0 Parameters

Con la Sintassi XWiki 2.0 è possibile passare dei parametri tra i diversi elementi sintattici ed anche a blocchi di testo. Si usa questo per esempio per applicare uno stile. Si può impostare qualunque parametro chiave/valore. Il motore di render XHTML passerà questi parametri come attributi XHTML della sottostante rappresentazione XHTML dei differenti elementi sintattici.

(% class="miaClasse" style="mioStile" id="myId" %)
= titolo =

<h1 class="miaClasse" style="mioStile" id="myId">titolo</h1>

Programmazione

Macro

2.0 Macros

Anche nella Sintassi XWiki 2.0 ci sono due tipi di macro:

• Macro Velocity (chiamate usando la sintassi #macroname(param1 ... paramN) all'interno della Macro Velocity)
• Macro XWiki (chiamate usando la sintassi {{macroname param1="value1" ... paramN="valueN"}} )

{{code language="java"}}
System.out.println("Hello World!");
{{/code}}

HTML

2.0 HTML

Scripts

2.0 Scripts

{{velocity}}
#set ($var = "qualsiasi")
{{/velocity}}

{{groovy}}
def var = "qualsiasi"
{{/groovy}}