Suddividere un articolo in pagine, l'uso delle pagebreak in Joomla 1.5

Le pagebreak (interruzioni di pagina) sono un valido strumento di formattazione che permette di suddividere un articolo in più pagine collegate tra di loro mediante una tabella dei contenuti (indice) e due link di navigazione Prev. e Succ. per muoversi tra le pagine. Completa la struttura dell'articolo multipagina l'indicazione della pagina corrente e il numero totale di pagine dell'articolo.

Joomla! fornisce nativamente questa funzionalità mediante due plugin, Content - Pagebreak e Editor Button - Pagebreak.

Content - Pagebreak è il plugin incaricato dell'analisi dell'articolo e della creazione della tabella dei contenuti, della barra con l'indicazione della pagina e della barra di navigazione. Questo plugin è necessario al funzionamento delle pagebreak.

Editor Button - Pagebreak è il plugin che si occupa di aggiungere e gestire il pulsante pagebreak in fondo all'editor dei contenuti e che permette l'inserimento guidato della pagebreak.

Di seguito la procedura per creare o trasformare un articolo in un articolo multipagina:

1. apri un documento esistente
   1. accedi al Gestore Articoli tramite il menù Contenuti > Gestore Articoli, seleziona l'articolo che ti interessa mediante la corrispondente checkbox, clicca sul pulsante Modifica;
      in alternativa clicca sul titolo dell'articolo;
   2. se sei loggato nel front-end ed hai i permessi almeno di autore, clicca sull'icona di modifica articolo;
   oppure crea un nuovo documento cliccando su Nuovo articolo nel Pannello di controllo
2. posiziona il cursore nel punto dove vuoi inserire la pagebreak;
3. clicca sul pulsante pagebreak in fondo all'editor dei contenuti e si aprirà la finestra Inserisci pagebreak;
   
4. inserisci il campo Titolo pagina che verrà visualizzato dopo il titolo dell'articolo, se lo lasci vuoto verrà mostrato solo il titolo dell'articolo;
   nel campo Tabella dei contenuti devi inserire la descrizione breve della pagina che verrà visualizzata nell'indice, se lo lasci vuoto verrà visualizzato Pagina #
5. clicca sul pulsante pagebreak, la finistra verrà chiusa e verrà visualizzata una linea orizzontale che indica il punto di interruzione pagina;
   
   per chiudere la finestra senza inserire la pagebreak clicca sul pulsante X
6. ripeti i passi da 2 a 5 per ogni pagebreak richiesta.

Non è possibile modificare il titolo della pagina o il testo della tabella dei contenuti direttamente dall'editor dei contenuti una volta inserita una pagebreak. Per modificarla devi eliminarla usando il tasto CANC o BACKSPACE e reinserirla con la procedura descritta sopra o come vedremo in seguito bisogna agire sul codice HTML dell'articolo.

Le pagebreak è attiva solo in modalità visualizzazione articolo mentre non lo è per nella visualizzazione prima pagina.

Non è possibile associare un titolo alla prima pagina.

Opzioni

Il plugin Content - pagebreak ha alcune opzioni che permettono di modificare il comportamento delle pagebreak, vediamoli insieme:

Abilita plugin (No/Sì): se impostato su sì, suddivide l'articolo in pagine, mentre se è impostato su no, visualizza l'intero articolo senza mostrare le linee orizzontali associate alle pagebreak;

Titolo sito (No/Sì): permette di scegliere se visualizzare o meno il titolo della pagina di fianco al titolo dell'articolo;

Tabella dei contenuti (Nascondi/Mostra): permette di scegliere se mostrare o meno la tabella dei contenuti;

Mostra tutti (Nascondi/Mostra): permette di scegliere se visualizzare o meno la voce mostra tutte le pagine alla fine della tabella dei contenuti.

Approfondimento

Livello di difficoltà: **
Conoscenze necessarie: Joomla!, HTML, CSS

La pagebreak altro non è che un tag hr la cui classe css è system-pagebreak; per tale motivo la gestione delle pagebreak può essere effettuata direttamente modificando il codice HTML dell'articolo.

La sintassi del tag hr è la seguente:

<hr title="Titolo pagina" alt="Tabella dei contenuti" class="system-pagebreak" />

dove title rappresenta il titolo della pagina e alt è la voce relativa nella tabella dei contenuti. Gli attributi title e alt possono essere omessi e la pagebreak ha lo stesso comportamento che avrebbe se fossero lasciati vuoti e corrispettivi campi nella finestra Inserisci pagebreak.

Le opzioni del plugn Content - pagebreak sono poche e non permettono grandi possibilità di modifica del comportamento delle pagebreak. Una strada percorribile con semplicità è la modifica dei fogli di stile. Di seguito le classi CSS associate alle pagebreak ed alcuni esempi di modifica dei fogli di stile:

Nascondere la barra di navigazione:

.pagenavbar {
  display: none;
}

Centrare la barra di conteggio:

.pagenavcounter {
  text-align: center;
}

Override del Template

Livello di difficoltà: ***
Conoscenze necessarie: Joomla!, HTML, CSS, PHP

La struttura di supporto degli articoli multipagina che propone Joomla! con il suo plugin Content - pagebreak è estremamente rigida, ma grazie all'uso della tecnica dell'override del template è possibile personalizzarla senza troppo sforzo.

L'obiettivo che ci proponiamo è quello di avere un indice basato su lista e non su tabella, di avere la barra di navigazione in basso a sinistra e l'indicazione di pagina in basso a destra.

Iniziamo dando uno sguardo al codice HTML generato dal plugin pagebreak:

<table cellpadding="0" cellspacing="0">
  <tr><th>Indice</th></tr>
  <tr><td><a href="/…">Le pagebreak, come usarle</a></td></tr>
  <tr><td><a href="/…">Pagina 2</a></td></tr>
  <tr><td><a href="/…">Tutte le pagine</a></td></tr>
</table>
<div class="pagenavcounter">Pagina 1 di 2</div>
<p>Test articolo</p>
<div class="pagenavbar">Prev. - Succ.</div>

passiamo al layout default della vista article del componente com_content per verificare come Joomla! genera e visualizza i vari elementi di un articolo multipagina e come possiamo intervenire per modificarne il comportamento. Il file in questione è components/com_content/views/article/tmpl/default.php

<?php if (isset ($this->article->toc)) : ?>
  <?php echo $this->article->toc; ?>
<?php endif; ?>
<?php echo $this->article->text; ?>

Dall'analisi dell'estratto di codice sopra riportato è chiaro che il plugin pagebreak genera la TOC (tabella dei contenuti) e l'assegna al campo toc dell'articolo. Ma non è chiaro come vengono generate e gestite la barra di navigazione e l'indicazione della pagina.

Bisogna quindi analizzare il codice del plugin per capirlo.Il file in esame è plugins/content/pagebreak.php che ometto per brevità. In sostanza il plugin aggiunge l'indicazione di pagina in testa al codice HTML dell'articolo e la barra di navigazione in coda.

Adesso che è chiaro come il plugin genera il codice HTML passiamo alla sua modifica. Iniziamo trasformando la tabella dei contenuti in una lista dei contenuti.

<table cellpadding="0" cellspacing="0" class="contenttoc"> 
  <tr><th>Indice</th></tr>
  <tr><td><a href="/…">Le pagebreak, come usarle</a></td></tr>
  <tr><td><a href="/…">Pagina 2</a></td></tr>
  <tr><td><a href="/…">Tutte le pagine</a></td></tr>
</table>

<div class="contenttoc">
  <h4>Indice</h4><ul>
  <li><a href="/…">Le pagebreak, come usarle</a></li>
  <li><a href="/…">Pagina 2</a></li>
  <li><a href="/…">Tutte le pagine</a></li>
</ul></div>

La trasformazione della tabella dei contenuti in lista è una operazione abbastanza semplice, tutto quello che ci serve è una sosituzione di stringhe. Basta infatti sostituire i tag della tabella con quelli della lista.

Lo spostamento dell'indicazione di pagina è un po' meno immediato ma sempre abbastanza semplice: bisogna effettuare un taglia e copia al volo.

Prima di procedere con il codice completo è bene sapere che l'indicazione di pagina non è presente se visualizzi l'articolo per intero.

if (isset ($this->article->toc)) {
  $toc = $this->article->toc; 
  $toc = str_replace(
    array('<table cellpadding="0" cellspacing="0" ', '<th>', '</th>', '<td>', '</td>', '</table>', '<tr>', '</tr>'),
    array('<div ', '<h4>', '</h4><ul>', '<li>', '</li>', '</ul></div>'), 
    $toc); 
  echo $toc;
  $text = $this->article->text;
  if (strpos($text, '<div class="pagenavcounter">') === false)   
    echo $text; 
  else if (($fine = strrpos($text, '<div class="pagenavbar">')) === false)  
    echo $text; 
  else {    
    $inizio = strpos($text, '</div>')+6;   
    echo substr($text, $inizio, $fine-$inizio)    
      . substr($text, 0, $inizio)    
      . substr($text, $fine);
  }
} else
  echo $this->article->text;

L'ultima modifica da apportare riguarda il foglio di stile per allineare la toc e l'indicazione di pagina a destra.

div.contenttoc {
  margin: 5px;
  border: 1px solid #ccc;
  padding: 5px;
  float: right;
}

.pagenavcounter {
  float: right;
}

Come visto l'override del template si è rivelato ancora una volta una tecnica potente e versatile per modificare il comportamento standard di Joomla!

Fonti
Splitting a long Article into multiple linked pages

Articolo scritto da Helios Ciancio - www.eshiol.it