Vai alla nuova documentazione

Istruzioni

Le istruzioni consentono di trasformare delle pagine HTML in pagine che si adattano in base al contesto con il contentuo inserito nel gestionale. Ad esempio una pagina HTML di un reparto mostarà prodotti diversi in base al reparto.

Si hanno tre istruzioni che servono a definire la struttura del sito:

<!-- .extend "layout.html" -->
<!-- .region "name" --> ... <!-- .end region -->
<!-- .include "include.html" -->

tre istruzioni che gestiscono la visualizzazione dei contenuti:

<!-- .show variabile --> ... <!-- .end -->
<!-- .if variabile --> ... <!-- .end -->
<!-- .for variabile --> ... <!-- .end -->

l'istruzione extract:

[% variabile %]
[% variabile.attributo %]

e una istruzione per visualizzare gli snippet delle app:

<!-- .snippet name --> ... <!-- .end -->

Per ogni istruzione bisogna indicare una variabile su cui deve operare. Sono disponibili variabili per visualizzare il nome di un prodotto, variabili per visualizzare la lista dei reparti, variabili per determinare se un utente ha fatto il login al sito ecc. Le variabili variano in base alla pagina HTML, una lista completa è disponibile nel successivo capitolo.

All'interno delle istruzioni, al posto dei tre puntini, ci potrà essere qualsiasi codice HTML. Nel caso delle istruzioni if e for questo codice HTML potrà contenere anche altre istruzioni.

Un buon sistema per capire il funzionamento delle istruzioni e delle variabili è sperimentare con il codice delle pagine HTML fornite con il software.

Dopo la parola end di ogni istruzione si può scrivere il nome dell'istruzione stessa:

<!-- .show variabile --> ... <!-- .end -->
<!-- .if variabile --> ... <!-- .end -->
<!-- .for variabile --> ... <!-- .end -->

Facendo in questo modo si potrà rendere il codice più leggibile e il software farà un ulteriore controllo sulla corretta chiusura dell'istruzione.

Struttura del sito

Realizzare un sito complesso composto da molte pagine richiede strumenti che consentano di velocizzarne la costruzione e il successivo mantenimento. Open2b mette a disposizione le istruzioni extend, region e include che servono appositamente a questo scopo.

Istruzioni extend e region

In ogni sito, compresi quelli di commercio elettronico, è composto da pagine diverse una dall'altra che però condividono una stessa struttura. In Open2b il codice HTML che definisce la struttura comune a più pagine può essere messo in una pagina HTML apposita, che chiameremo pagina di layout. Le singole pagine del sito andranno ad estendere una pagina di layout definendo solamente il codice HTML differente per ogni pagina.

Nei template forniti con Open2b le pagine di layout si trovano nella cartella layouts, ma nulla vieta di metterli da un'altra parte, ma comunque sempre dentro la cartella del template.

Le pagine di layout, oltre al codice HTML che definisce la struttura della pagina, contengono le istruzioni region che indicano i punti nella pagina in cui codice HTML sarà definito nelle pagine del sito che estendono la pagina di layout in questione.

<!-- .region "body" -->

<!-- .end region -->

Una istruzione region può essere messa in qualsiasi punto della pagina di layout, l'importante è che abbia un nome univoco in tutta la pagina.

Una volta creata la pagina di layout è possibile utilizzarla come modello per velocizzare la creazione delle pagine del sito. Basta indicare la pagina di layout che si vuole estendere e scrivere il codice HTML per ogni region:

<!-- .extend "layouts/standard.html" -->
<!-- .region "body" -->
  <h1>Titolo</h1>
  <p>contenuto</p>
<!-- .end region -->

Istruzione include

Gli include, come compendio a layout e region, sono un potente strumento che consente di strutturare ulteriormente il codice sorgente delle pagine HTML per minimizzare il codice ripetuto ed avere un unico punto di intervento per le modifiche grafiche su diverse pagine.

Mentre i layout sono ottimi per gestire la struttura delle pagine, gli includes sono ideali per condividere blocchi di codice ripetuti in più pagine come ad esempio i menù, il modulo per il login e la ricerca.

Il codice in comune viene salvato in un file, che chiameremo file di inclusione, per poi essere richiamato all'interno delle pagine HTML:

<!-- .include "includes/header.html" -->

Nei template forniti con Open2b, i file di inclusione si trovano nella cartella includes ma nulla vieta di metterli da un'altra posizione, ma comunque sempre dentro la cartella del template.

Istruzione show

L'istruzione show mostra nella pagina del sito un contenuto dinamico rappresentato dalla variabile indicata. Ad esempio il seguente codice, utilizzabile nella pagina di un prodotto, mostra l'immagine del prodotto:

<!-- .show image --> <!-- .end -->

Il seguente, utilizzabile in qualsiasi pagina, mostra invece il pulsante per fare il login al sito:

<!-- .show login --> <!-- .end -->

Il seguente, utilizzabile in alcune determinate pagine, mostra messaggio che informa dell'esito di una azione intrapresa dell'utente come ad esempio la compilazione del modulo di registrazione:

<!-- .show statusMessage --> <!-- .end -->

Istruzione if

L'istruzione if consente di visualizzare del codice HTML in base ad una condizione data dalla variabile indicata. Ad esempio il seguente mostra un messaggio se l'utente ha fatto il login al sito:

<!-- .if isLoggedIn --> <em>Benvenuto</em> <!-- .end -->

Se invece, al contrario, desideriamo visualizzare un messaggio se l'utente non ha ancora fatto il login possiamo utilizzare l'operatore not:

<!-- .if not isLoggedIn --> fai il login <!-- .end -->

Nel successivo capitolo sono elencati tutti i marcatori raggruppati in base alla pagina in cui possono essere utilizzati.

Istruzione for

Alcune variabili rappresentano una lista di elementi, come ad esempio una lista di reparti, oppure una lista di prodotti. Per visualizzare gli elementi di questa lista si utilizza l'istruzione for.

Ad esempio il seguente visualizza una lista di reparti:

<!-- .for departments -->
  <!-- .show name --> Magliette <!-- .end -->
<!-- .end for -->

Se si desidera mostrare un solo elemento della lista, basta indicarne l'indice tra parentesi:

<!-- .for departments(5) -->
  <!-- .show name --> Magliette <!-- .end -->
<!-- .end for -->

Il primo indice della lista è il numero 1.

Ad esempio la variabile menus rappresenta la lista dei menù gestibili nel gestionale. Con il seguente codice è possibile mostrare il menù 3:

<!-- .for menus(3) -->
  <!-- .show title --> Titolo <!-- .end -->
  ...
<!-- .end for -->

Istruzione extract

L'istruzione extract si applica alle stesse variabili a cui si applica l'istruzione show ma consente di estrarre solo una parte dal codice HTML prodotto da show. In particolare estrae o il contenuto del tag HTML o un singolo attributo del primo tag.

Se ad esempio <!-- show name --> <!-- .end --> genera il seguente codice:

<a href="/custodia-per-cellulare">Custodia per cellulare</a>

allora [% name %] ne estrae il contenuto rimuovendo i tag HTML:

Custodia per cellulare

mentre [% name.href %] estrae il valore dell'attributo href del primo tag:

/custodia-per-cellulare

Questo consente un uso più flessibile di show che in diverse circostanze può essere molto utile.

Come ulteriore esempio della sua efficacia, rifacendosi all'esempio precedente, se si vuole che la pagina si apra in una nuova finestra del browser allora basta scrivere:

<a href="[% name.href %]" target="_blank">[% name %]</a>

e il codice generato sarà:

<a href="/custodia-per-cellulare" target="_blank">Custodia per cellulare</a>

Diversamente da show, l'istruzione extract può essere usata con sicurezza all'interno di un attributo di un tag come ad esempio:

<html class="[% page %]">

Il codice HTML rimane ben formato ed eventuali caratteri non consentiti in un attributo vengono sottoposti ad escape.

Istruzione snippet

L'istruzione snippet si utilizza per inserire all'interno delle pagine gli snippet delle app. Per sapere quali snippet si possono utilizzare consultare la documentazione delle app installate nel negozio.