## Please edit system and help pages ONLY in the master wiki!
## For more information, please see MoinMoin:MoinDev/Translation.
##master-page:HelpOnMacros
##master-date:2008-10-12 00:48:22
#acl -All:write Default
#format wiki
#language it

<<Navigation(children)>>
<<BR>><<BR>>
<<TableOfContents>>

== Le macro ==

Le macro consentono di inserire nuove funzionalità nelle normali pagine wiki; l'unica cosa che le rende speciali è che contengono delle macro. Se si modificano pagine tipo ModificheRecenti o InformazioniSulSistema, è possibile vedere cosa si intende.

Per ulteriori informazioni sulle possibili formattazioni, consultare AiutoSuModificaPagina.

=== Macro di ricerca ===

MoinMoin utilizza un nuovo motore di ricerca, che consente di svolgere ricerche sofisticate utilizzando sia il riquadro di ricerca interattiva sia una qualsiasi delle macro di ricerca. Per un ulteriore aiuto, consultare AiutoSuRicerche.

||||||'''Macro''' ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> '''Descrizione''' ||'''Esempio''' ||
||||||{{{<<AdvancedSearch>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Crea un dialogo di ricerca avanzata nella pagina || Consultare CercaPagina ||
||||||{{{<<TitleSearch>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Crea un riquadro di ricerca nella pagina che cerca tra i titoli delle pagine || Consultare CercaPagina ||
||||||{{{<<FullSearch>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Crea un riquadro di ricerca nella pagina che cerca nel contenuto delle pagine || Consultare CercaPagina ||
||||||{{{<<FullSearch()>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenca le pagine che contengono il titolo della pagina (come facendo clic sul titolo della pagina) || Consultare la pagina CategoriaCategoria ||
||||||{{{<<FullSearch(text)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenca le pagine che contengono il termine ricercato || /* Cerca {{{powered}}}:<<FullSearch(powered)>> */ ||
||||||{{{<<FullSearchCached(text)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Lavora come la macro {{{FullSearch}}} ma crea una cache statica dei risultati. Utilizzarla se si preferisce cercare velocemente su un risultato aggiornato || /* Cerca {{{powered}}}:<<FullSearchCached(powered)>> */ ||
||||||{{{<<GoTo>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Vai direttamente alla pagina indicata || Consultare CercaPagina ||
||||||{{{<<PageList(Help)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenca le pagine il cui titolo corrisponde al termine ricercato || Consultare AiutoIndice ||

=== Navigazione ===
||||||'''Macro''' ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> '''Descrizione''' ||'''Esempio''' ||
||||||{{{<<RecentChanges>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenco di pagine modificate di recente || Consultare ModificheRecenti ||
||||||{{{<<TitleIndex>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Indice di tutti i titoli delle pagine || Consultare IndiceDeiTitoli ||
||||||{{{<<WordIndex>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Indice di tutte le parole nei titoli delle pagine || Consultare IndicePerParola ||
||||||{{{<<WantedPages>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenco di pagine che non esistono || Consultare PagineAssenti ||
||||||{{{<<OrphanedPages>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenco di pagine non referenziate da altre pagine || Consultare PagineOrfane ||
||||||{{{<<AbandonedPages>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenca le pagine non modificate da più tempo || Consultare PagineAbbandonate ||
||||||{{{<<RandomPage>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Collegamento a una pagina a caso || `<<RandomPage>>` ||
||||||{{{<<RandomPage(#)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Collegamenti a un dato numero di pagine a caso || Due pagine a caso:`<<RandomPage(2)>>` ||
||||||{{{<<TableOfContents([maxdepth])>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Visualizza un indice locale, limitato a una profondità massima (maxdept) || Consultare inizio pagina ||
||||||{{{<<Anchor(anchorname)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Macro per inserire "ancore" in una pagina || <<Anchor(qui)>>[[#qui]] ||
||||||{{{<<Navigation(children[,maxdepth])>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Macro che elenca tutte le pagine che discendono da una pagina || Consultare inizio pagina ||
||||||{{{<<Navigation(siblings[,maxdepth])>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Navigazione rapida tra pagine sullo stesso livello || Consultare /MailTo ||
||||||{{{<<Navigation(slideshow)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Crea un collegamento per passare da modalità presentazione a quella wiki e uno per far partire la presentazione || Consultare AiutoSuPresentazione ||
||||||{{{<<Navigation(slides)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra i collegamenti a prima/precedente/prossima/ultima slide || Consultare AiutoSuPresentazione ||
||||||{{{<<AttachInfo>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra il numero di file allegati alla pagina attuale || Consultare AiutoSuAzioni/AllegaFile ||
||||||{{{<<AttachInfo(page)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra il numero di file allegati alla pagina indicata || Consultare AiutoSuAzioni/AllegaFile ||
||||||{{{<<AttachList(pagename,mimetype)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra l'elenco dei file allegati || Consultare AiutoSuAzioni/AllegaFile ||

=== Informazioni di sistema ===

||||||'''Macro''' ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> '''Descrizione''' ||'''Esempio''' ||
||||||{{{<<Hits>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> a counter for page hits {{{<<Hits([all=(False,True)][,event_type=(VIEWPAGE,SAVEPAGE)]>>}}}|| <<Hits>> ||
||||||{{{<<InterWiki>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenco di tutti i nomi InterWiki conosciuti || InterWiki ||
||||||{{{<<SystemInfo>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Informazioni sul wiki, sull'interprete Python e sul sistema ospite || InformazioniSulSistema ||
||||||{{{<<PageCount(exists)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Calcolo del numero di pagine attuali. Se viene utilizzato come argomento {{{exists}}}, verranno mostrate solo le pagine esistenti. || <<PageCount>> pagine ||
||||||{{{<<PageSize>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenca le dimensioni di tutte le pagine || Consultare PaginePerDimensione ||
||||||{{{<<StatsChart(type)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra grafici statistici (attualmente sono definiti questi tipi: hitcounts, pagesize, useragents) || Consultare StatisticheEventi e sottopagine ||
||||||{{{<<SystemAdmin>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Informazioni per gli amministratori del sistema || Bisogna essere ''superuser'' per utilizzare questa macro<<BR>> <<SystemAdmin>> ||
||||||{{{<<EditedSystemPages>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Elenco di tutte le pagine di sistema modificate || <<EditedSystemPages>> ||
||||||{{{<<WikiConfig>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra al super-utente le impostazioni della configurazione del wiki diverse dalle quelle predefinite||È necessario essere super-utente per utilizzare questa macro <<BR>> {{{<<WikiConfig>>}}} ||
||||||{{{<<WikiConfigHelp>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra la descrizione di tutti i parametri di configurazione || {{{<<WikiConfigHelp>>}}} ||

=== Altre ===
||||||'''Macro''' ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;"> '''Descrizione''' ||'''Esempio''' ||
||||||{{{<<Action(action [,text])>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Collega una pagina con un'azione valida, il testo opzionale può essere utilizzato come alias (i nomi delle azioni fanno distinzione tra maiuscole e minuscole)|| `<<Action(print, Stampa questa pagina)>>`, <<Action(print, Stampa questa pagina)>>||
||||||{{{<<Icon(image)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra icone di sistema || Consultare AiutoSuNavigazione ||
||||||{{{<<BR>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Forza un a capo ||Prima riga<<BR>>seconda riga ||
||||||{{{<<RandomQuote(pagename)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Seleziona una parte di testo a caso della pagina indicata o da {{{BiscottiDellaFortuna}}} se questa viene omessa || <<RandomQuote(BiscottiDellaFortuna)>> ||
||||||{{{<<Include(HelloWorld[,"heading"[,level]])>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Include i conenuti di un'altra pagina || Per dettagli consultare [[/Includi]] ||
||||||{{{<<FootNote(text)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Aggiunge una nota a fondo pagina<<FootNote(Il testo non può contenere alcuna formattazione wiki)>> oppure mostra tutte le note a piè di pagina se non viene fornito un argomento || Consultare l'esempio a fine pagina ||
||||||{{{<<Date(timestamp)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra la data come da impostazioni di sistema || <<Date>> ||
||||||{{{<<DateTime(timestamp)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra data e ora<<FootNote("timestamp" può essere vuoto (ora attuale), un numero di secondi dal 1970 (unix timestamp) o una specifica temporale W3C ("2002-01-23T12:34:56"). Vedi RFC822, sez. 5. )>> come da impostazioni utente || <<DateTime>> ||
||||||{{{<<GetText(text)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Carica le traduzioni I18N (per utilizzi su pagine di Aiuto) || "Edit``Text" viene tradotto in "<<GetText(EditText)>>" ||
||||||{{{<<GetText2(,message,argument1,argument2,...)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Carica le traduzioni I18N (per utilizzi su pagine di aiuto o su pagine wiki con output generato) e sostituisce `%s` nel messaggio a seconda degli argomenti. Il primo carattere dell'argomento è utilizzato come separatore (in questo esempio: una virgola). Si può evitare il separatore utilizzando una barra rovescia. || "`<<GetText2(,[You may not read %s],FooBar)>>`" diventa "<<GetText2(,[You may not read %s],FooBar)>>" ||
||||||{{{<<TeudView>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Utile per wiki di sviluppo su intranet, per visualizzare documentazione pydoc formattata con un foglio di stile XSLT || Vedi http://twistedmatrix.com/wiki/python/TeudProject ||
||||||{{{<<MailTo(email)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Protegge il tuo indirizzo email dagli ''spam bot'' ||Per dettagli vedi /MailTo ||
||||||{{{<<NewPage(PageTemplate,ButtonLabel,[ParentPage,@ME,@SELF] [,NameTemplate])>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Permette agli utenti di creare con facilità (sotto-) pagine, usando la pagina {{{PageTemplate}}} come modello per una nuova pagina e la stringa {{{NameTemplate}}} come maschera per il nome.<<FootNote(`NameTemplate` viene formattato come `time.strftime()`, con l'eccezzione che `%s` viene sostituito da quanto inserito nel riquadro di modifica (che viene mostrato solo se richiesto). Se {{{NameTemplate}}} non viene specificato o è vuoto, viene sostituito in modo predefinito con `%s`.)>> `@ME` viene utilizzato se si vuole creare la pagina come sotto pagina della pagina personale. `@SELF` viene utilizzato per creare una sotto pagina sotto la pagina dalla quale viene invocata la macro. || <<NewPage(CategoryTemplate, Crea la nuova Categoria,,Category%s)>> ||
||||||{{{<<GetVal(NeatSnippets,regards)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Restituisce il corrispondente trovato nelle pagine dizionario. || Nel caso esistesse una pagina !GermanDict contenente la voce ''Test'', dovresti vederne la traduzione qui: <<GetVal(GermanDict,Test)>> ||
||||||{{{ <<MonthCalendar(,,12)>>}}} ||
||<5%><<BR>>||<75% style="margin: 10px; vertical-align: top;">Mostra un calendario e crea i collegamenti per ogni giorno in sottopagine || Vedi /CalendarioMensile ||

<<FootNote>>

== Scrivere una macro ==

Creare un file python di nome {{{NomeMacro.py}}} nella directory {{{data/plugin/macro}}}. Assicurarsi che abbia una sola funzione chiamata {{{macro_NomeMacro(macro, arg1, arg2, ...)}}} che ne costituisce il punto iniziale.

 * il primo argomento, ''macro'', è un'istanza della classe Macro e viene valorizzata in una stringa col nomemacro
 * gli argomenti ''arg1'', ''arg2'', ... sono gli argomenti forniti dall'utente, ma ci sono dei casi particolari (consultare sotto)

È possibile accedere all'oggetto `request` usando `macro.request`, per esempio per accedere ai parametri di un modulo e ad altre informazioni dell'utente.

La funzione dovrebbe usare il formattatore per costruire un markup valido per il tipo di pagina. Nella maggior parte dei casi è HTML, quindi creare una macro che ritorna HTML funzionerà quasi sempre a parte quando sono richiesti formati come XML o `plain/text` (è possibile usare `macro.formatter` per accedere al formattatore corrente).

Per esempio, la propria pagina wiki contiene le seguenti righe:
{{{
<<NomeMacro(True, 1.7772, 17)>>
}}}

È possibile creare un file !NomeMacro.py in questo modo:
{{{
#!python

from wikiutil import get_unicode, get_bool, get_int, get_float

Dependencies = []
generates_headings = False

def macro_NomeMacro(macro, arg1, arg2, arg3=7):
    # gli argomenti possono essere None o un oggetto unicode

    arg1 = get_bool(macro.request, arg1)
    arg2 = get_float(macro.request, arg2)
    # dato che arg3 ha un valore predefinito di 7, è sempre un int long

    return macro.formatter.text("gli argomenti sono: %s %2.3f %d" % (arg1, arg2, arg3))
}}}
 . /!\ Aggiungere una voce in {{{Dependencies}}} se l'output della macro non deve rimanere nella cache. Questo è importante nel caso in cui l'output della macro possa cambiare, per esempio se la macro effettua una ricerca su pagine wiki che possono essere state modificate da altri utenti o carica informazioni da un database esterno il cui contenuto può cambiare. In questo caso il valore di ogni voce non ha importanza e può essere considerato una descrizione abbreviata del "perché i risultati di questa macro non devono restare in cache". Controllare in altre macro per trovare casi più interessanti.

Se la macro è in grado di generare titoli (chiamando `macro.formatter.heading()`), impostare `generates_headings` a `True` per consentire alla macro `TableOfContents` di analizzare la propria macro alla ricerca dei titoli da usare.

=== Argomenti della macro ===

Gli argomenti passati alla macro sono normalmente istanze unicode di `None` se l'utente non ha fornito alcun valore.

Considerare questo esempio:
{{{#!python

def macro_Example(macro, arg1, arg2):
  ...
}}}

e il codice wiki (coi risultati)
{{{
 1. <<Example()>>            - passa None, None
 2. <<Example(a,b)>>         - passa u'a', u'b'
 3. <<Example(,)>>           - passa None, None
 4. <<Example("",)>>         - passa u'', None
}}}

==== Valori predefiniti ====

Se la macro dichiara dei valori predefiniti come in questo esempio:
{{{#!python

def macro_Example(macro, arg1=7, arg2=2.1):
  ...
}}}


Gli argomenti possono quindi essere saltati e vengono convertiti automaticamente al valore predefinito:
{{{
 1. <<Example()>>            - passa 7, 2.1
 2. <<Example(,3)>>          - passa 7, 3.0
 3. <<Example(2)>>           - passa 2, 2.1
 4. <<Example(a,7.54)>>      - errore, "a" non è un intero
}}}

Inoltre, è possibile dichiarare il tipo che si vuole ottenere:
{{{#! python

def macro_Example(macro, arg1=int, arg2=float):
  ...
}}}

In questo modo l'utente è obbligato a inserire il parametro corretto, ma è possibile evitare questo passando un argomento vuoto nel cui caso la macro riceverà il valore `None`:
{{{
 1. <<Example()>>            - passa None, None
 2. <<Example(a, 2.2)>>      - errore, "a" non è un intero
 3. <<Example(7, 2.2)>>      - passa 7, 2.2
 4. <<Example(, 3.14)>>      - passa None, 3.14
}}}

==== Argomenti unità ====

Se la propria macro dichiara degli argomenti con unità, le stesse sono richieste:
{{{#!python
from MoinMoin import wikiutil
def macro_Example(macro, arg1=wikiutil.UnitArgument(None, float, ['px', '%'], defaultunit='px')):
    if arg1:
        if arg1[1] == 'px':
            arg1 = '%dpx' % int(arg1[0])
        else:
            arg1 = '%g%s' % arg1
    return macro.formatter.text("argument is: %s" % (arg1))
}}}
Il valore di defaultunit, px, è utilizzato se l'utente non ne inserisce uno e deve inserire le unità valide come "px" o "%".
{{{
 1. <<Example()>>             - argomento è: None
 2. <<Example(100)>>          - argomento è: 100px
 3. <<Example(100mm)>>        - <<Example: Invalid unit in value 100mm (allowed units: px, %)>>
 4. <<Example(100px)>>        - argomento è: 100px
}}}

==== Scelte ====

Se la propria macro può accettare diverse scelte, è possibile dichiararlo come segue:
{{{#!python

def macro_Example(macro, fruit=(u'apple', u'orange')):
  ...
}}}

Questo richiede che l'utente inserisca una qualsiasi delle scelte fornite e utilizza la prima nel caso non ne sia fornita alcuna:
{{{
 1. <<Example(apple)>>       - passa u'apple'
 2. <<Example(OrAnGe)>>      - errore, indica all'utente quali scelte sono valide
 3. <<Example()>>            - passa u'apple'
}}}

==== Argomenti richiesti ====

Se devono essere richiesti degli argomenti, è possibile indicarlo usando la classe `required_arg` istanziata ottenendo il tipo dell'argomento:
{{{#! python
from MoinMoin.wikiutil import required_arg

def macro_Example(macro, arg1=required_arg(int)):
  ...
}}}

Questo richiede che l'utente inserisca l'argomento:
{{{
 1. <<Example()>>            - errore, argomento "arg1" richiesto
 2. <<Example(4.3)>>         - errore, "4.3" non è un intero
 3. <<Example(5)>>           - passa 5
}}}


==== Argomenti chiave ====

Se la propria macro deve accettare degli argomenti arbitrati sotto forma di chiavi da passare a qualcos'altro, deve dichiarare un parametro `_kwargs` con valore predefinito un dizionario vuoto:
{{{#!python

def macro_Example(macro, _kwargs={}):
  ...
}}}

Questo fa in modo che l'utente posso passare qualsiasi valore, anche stringhe unicode arbitrarie:
{{{
 1. <<Example(äöü=7)>>       - passa il dizionario {u'äöü': u'7'}
 2. <<Example(=7)>>          - passa il dizionario {u'': u'7'}
 3. <<Example(a=1,"d e"=3)>> - passa il dizionario {u'a': u'1', u'd e': u'3'}
 4. <<Example(a)>>           - errore, troppi argomenti non-chiave
}}}

==== Argomenti di coda ====

Gli argomenti di coda consento alla propria macro di accettare un qualsiasi numero di argomenti posizionale o consentono di gestire la sintassi di macro come:
{{{
[[Macro(1, 2, 3, name=value, name2=value2, someflag, anotherflag)]].
}}}

Per poter gestire tutto questo, dichiarare un parametro `_trailing_args` con un elenco vuoto come valore predefinito:
{{{#!python

def macro_Example(macro, i1, i2, i3, name, name2, _trailing_args=[]):
  ...
}}}

Inoltre, quando l'utente fornisce troppi argomenti, questi sono inseriti in `_trailing_args`:
{{{
 1. <<Example(1, 2, 3, name=test, name2=test2, flag1)>>   - valido, passa u'flag1' in _trailing_args
 2. <<Example(1, 2, 3, test, test2, flag1)>>              - idem
}}}

È possibile usare questa caratteristica assieme al parametro `_kwargs`.