User Macro
In questo post andremo ad consultare un articolo presente in questo blog, che ritengo molto interessante. Lo esamineremo e cercheremo di approfondire l’argomento, in quanto lo ritengo un ottimo esempio didattico.
Andiamo in dettaglio
L’articolo del blog spiega come realizzare una alternativa alla macro Space Detail Macro, usando le macro per ottenere un risultato migliore 🙂
In particolare il risultato che offre con la sua macro è il seguente:
L’ho scelto perché si tratta di una macro molto semplice e, dal punto di vista didattico, la macro risulta realizzata molto bene.
Vediamo il codice
La configurazione preliminare della macro è molto semplice. La seguente immagine la riassume:
Il codice è molto semplice. Lo riporto di seguito nella sua interessa e successivamente lo andremo ad esaminare pezzo per pezzo, in modo da capire come viene eseguita ogni singola operazione.
## Macro title: Space Meta Data
## Macro has a body: Y or N (N)
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: Andrew Frayling
## Date created: 03/05/2012
## Installed by: <your name>
## Macro to display information such as number of pages, number of blog posts, attachment size, etc. about a Space.
## @noparams
## Get space details
#set ( $spaceName = $space.getName() )
#set ( $spaceKey = $space.getKey() )
#set ( $spaceHome = $space.getHomePage() )
#set ( $spaceCreator = $space.getCreatorName() )
#set ( $spaceCreationDate = $space.getCreationDate() )
#set ( $spaceDescription = $space.getDescription() )
#set ( $pageCount = $spaceManager.findPageTotal($space) )
#set ( $blogCount = $spaceManager.getNumberOfBlogPosts($space) )
## Get all pages in the current Space
#set ( $allPagesInSpace = $pageManager.getPages($space, true) )
## Reset total attachment file size
#set ( $totalAttachmentFileSizeForSpace = 0 )
## Reset total number of attachments
#set ( $totalAttachmentCount = 0 )
## Loop through all pages in the current Space
#foreach ($page in $allPagesInSpace)
## reset the attachment count for each page
#set ( $pageAttachmentCount = 0 )
## reset the attachment file size total for each page
#set ( $totalFileSizePerPage = 0 )
## get the attachments for each page
#set ( $allAttachments = $page.getAttachments() )
## Loop through each attachment
#foreach ($attachment in $allAttachments)
## Increment the attachment count for the page
#set ( $pageAttachmentCount = $pageAttachmentCount + 1 )
## Sum the size of the attachments on the page
#set ( $totalFileSizePerPage = $totalFileSizePerPage + $attachment.getFileSize() )
#end
## End looping through attachments
## Increment total attachment count for the current Space
#set ( $totalAttachmentCount = $totalAttachmentCount + $pageAttachmentCount )
## Sum the total size of attachments for the current Space
#set ( $totalAttachmentFileSizeForSpace = $totalAttachmentFileSizeForSpace + $totalFileSizePerPage )
#end
## End looping through pages
## Convert attachment size to MBs
#set ( $attachmentSizeMb = ($totalAttachmentFileSizeForSpace / 1024.00) / 1024.00 )
## Display Space Details
<table class="confluenceTable">
<tbody>
<tr>
<th class="confluenceTh">Name</th>
<td class="confluenceTd">$spaceName</td>
</tr>
<tr>
<th class="confluenceTh">Key</th>
<td class="confluenceTd">$spaceKey</td>
</tr>
<tr>
<th class="confluenceTh">Description</th>
<td class="confluenceTd">$spaceDescription.getBodyAsString()</td>
</tr>
<tr>
<th class="confluenceTh">Home Page</th>
<td class="confluenceTd">#contentLink2($spaceHome true false)</td>
</tr>
<tr>
<th class="confluenceTh">Created By</th>
<td class="confluenceTd">#usernameLink($spaceCreator) ($action.dateFormatter.formatDateTime($spaceCreationDate))</td>
</tr>
<tr>
<th class="confluenceTh">Number of Pages</th>
<td class="confluenceTd">$pageCount</td>
</tr>
<tr>
<th class="confluenceTh">Number of Blog Posts</th>
<td class="confluenceTd">$blogCount</td>
</tr>
<tr>
<th class="confluenceTh">Number of Attachments</th>
<td class="confluenceTd">$totalAttachmentCount (including all versions)</td>
</tr>
<tr>
<th class="confluenceTh">Total Size of Attachments</th>
<td class="confluenceTd">$attachmentSizeMb MB</td>
</tr>
</tbody>
</table>
Distinguiamo le seguenti sezioni nella macro:
- Testata
- Lettura parametri dello space
- Lettura della dimensione dei vari allegati
- Visualizzazione dati ottenuti
Andiamo ad esaminarle in dettaglio.
## Macro title: Space Meta Data
## Macro has a body: Y or N (N)
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: Andrew Frayling
## Date created: 03/05/2012
## Installed by: <your name>
## Macro to display information such as number of pages, number of blog posts, attachment size, etc. about a Space. ## @noparams
L’Intestazione della macro è quello che avevo già descritto nel mio primo post. In questo caso, l’autore ha realizzato una intestazione molto ben fatta, chiara, semplice e di rapido effetto.
Spiega subito le caratteristiche della macro in poche righe.
## Get space details
#set ( $spaceName = $space.getName() )
#set ( $spaceKey = $space.getKey() )
#set ( $spaceHome = $space.getHomePage() )
#set ( $spaceCreator = $space.getCreatorName() )
#set ( $spaceCreationDate = $space.getCreationDate() )
#set ( $spaceDescription = $space.getDescription() )
#set ( $pageCount = $spaceManager.findPageTotal($space) )
#set ( $blogCount = $spaceManager.getNumberOfBlogPosts($space) )
## Get all pages in the current Space
#set ( $allPagesInSpace = $pageManager.getPages($space, true) )
## Reset total attachment file size
#set ( $totalAttachmentFileSizeForSpace = 0 )
In questa sezione, invece, va a leggere tutte le informazioni dello Space, impostando tutte le variabili con le informazioni che si vogliono visualizzare nella macro. Notiamo le variabili, definite con la sintassi che è stata già spiegata nei precedenti post.
## Reset total number of attachments
#set ( $totalAttachmentCount = 0 )
## Loop through all pages in the current Space
#foreach ($page in $allPagesInSpace)
## reset the attachment count for each page
#set ( $pageAttachmentCount = 0 )
## reset the attachment file size total for each page
#set ( $totalFileSizePerPage = 0 )
## get the attachments for each page
#set ( $allAttachments = $page.getAttachments() )
## Loop through each attachment
#foreach ($attachment in $allAttachments)
## Increment the attachment count for the page
#set ( $pageAttachmentCount = $pageAttachmentCount + 1 )
## Sum the size of the attachments on the page
#set ( $totalFileSizePerPage = $totalFileSizePerPage + $attachment.getFileSize() )
#end
## End looping through attachments
## Increment total attachment count for the current Space
#set ( $totalAttachmentCount = $totalAttachmentCount + $pageAttachmentCount )
## Sum the total size of attachments for the current Space
#set ( $totalAttachmentFileSizeForSpace = $totalAttachmentFileSizeForSpace + $totalFileSizePerPage )
#end
## End looping through pages
## Convert attachment size to MBs
#set ( $attachmentSizeMb = ($totalAttachmentFileSizeForSpace / 1024.00) / 1024.00 )
In questa sezione del codice, viene eseguito un esempio di ciclo sulle varie pagine, per determinare la dimensione dei vari allegati alle pagine dello Space. Questo è sicuramente un ottimo esempio che mostra come sono reperite le informazioni usando il codice delle macro.
In aggiunta vediamo come eseguire il reperimento dei dati, quali le pagine presenti dentro uno space, e degli allegati. La sintassi non è affatto difficile e consente di poter lavorare agevolmente.
## Display Space Details
<table class="confluenceTable">
<tbody>
<tr>
<th class="confluenceTh">Name</th>
<td class="confluenceTd">$spaceName</td>
</tr>
<tr>
<th class="confluenceTh">Key</th>
<td class="confluenceTd">$spaceKey</td>
</tr>
<tr>
<th class="confluenceTh">Description</th>
<td class="confluenceTd">$spaceDescription.getBodyAsString()</td>
</tr>
<tr>
<th class="confluenceTh">Home Page</th>
<td class="confluenceTd">#contentLink2($spaceHome true false)</td>
</tr>
<tr>
<th class="confluenceTh">Created By</th>
<td class="confluenceTd">#usernameLink($spaceCreator) ($action.dateFormatter.formatDateTime($spaceCreationDate))</td>
</tr>
<tr>
<th class="confluenceTh">Number of Pages</th>
<td class="confluenceTd">$pageCount</td>
</tr>
<tr>
<th class="confluenceTh">Number of Blog Posts</th>
<td class="confluenceTd">$blogCount</td>
</tr>
<tr>
<th class="confluenceTh">Number of Attachments</th>
<td class="confluenceTd">$totalAttachmentCount (including all versions)</td>
</tr>
<tr>
<th class="confluenceTh">Total Size of Attachments</th>
<td class="confluenceTd">$attachmentSizeMb MB</td>
</tr>
</tbody>
</table>
Questa è la parte che si occupa della visualizzazione. Notiamo che si tratta di HTML, che sfrutta le classi e le proprietà di Confluence. Vediamo che tutti i risultati delle precedenti elaborazioni sono inserite in questa tabella, in maniera molto rapida.
Conclusioni
Abbiamo analizzato un esempio di macro, molto semplice ma nello stesso tempo, fondamentale. Con esso è possibile comprendere e capire meglio come si può realizzare una macro, come possiamo sfruttare i vari punti del linguaggio per realizzare le funzionalità di cui si abbisogna senza, in questo caso, dover installare nulla :-). Scusate se è poco 😀
Ringraziamenti
Un ringraziamento particolare va all’autore del post blog. L’articolo è ben fatto e, anche se in inglese, è molto chiaro. I complimenti all’autore sono d’obbligo. 🙂
