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.

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

2. Navigazione

3. Informazioni di sistema

4. Altre

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:

   1 from wikiutil import get_unicode, get_bool, get_int, get_float
   2 
   3 Dependencies = []
   4 generates_headings = False
   5 
   6 def macro_NomeMacro(macro, arg1, arg2, arg3=7):
   7     # gli argomenti possono essere None o un oggetto unicode
   8 
   9     arg1 = get_bool(macro.request, arg1)
  10     arg2 = get_float(macro.request, arg2)
  11     # dato che arg3 ha un valore predefinito di 7, è sempre un int long
  12 
  13     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.

1. 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:

   1 def macro_Example(macro, arg1, arg2):
   2   ...

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

1.1. Valori predefiniti

Se la macro dichiara dei valori predefiniti come in questo esempio:

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

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:

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

1.2. Argomenti unità

Se la propria macro dichiara degli argomenti con unità, le stesse sono richieste:

   1 from MoinMoin import wikiutil
   2 def macro_Example(macro, arg1=wikiutil.UnitArgument(None, float, ['px', '%'], defaultunit='px')):
   3     if arg1:
   4         if arg1[1] == 'px':
   5             arg1 = '%dpx' % int(arg1[0])
   6         else:
   7             arg1 = '%g%s' % arg1
   8     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

1.3. Scelte

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

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

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'

1.4. Argomenti richiesti

Se devono essere richiesti degli argomenti, è possibile indicarlo usando la classe required_arg istanziata ottenendo il tipo dell'argomento:

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

1.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:

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

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

1.6. 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:

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

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.