Liferay Portal Overview

Liferay Portal Server è un tool estremamente potente e versatile. Nell'ultima versione, esso ha raggiunto un maggiore grado di maturità e ha aggiunto molte funzionalità. In questo articolo affrontiamo lo sviluppo del tema grafico di un progetto web.

Sempre più spesso ci viene richiesto di studiare la grafica per progetti web realizzati con Liferay Portal Server [1]. Questo significa sviluppare il tema grafico, ossia l'insieme di stili CSS, immagini, template (con XSL o Velocity VM [2]) e layout personalizzati. Il processo di creazione di un nuovo tema inizia con il suo studio grafico mediante gli opportuni software di progettazione; una volta definita la veste grafica si può passare alla creazione del tema su Liferay.

I temi Liferay sono hot deployable plugin in grado di trasformare completamente l'aspetto grafico del portale rendendolo facile da usare e visivamente piacevole, tant'è che a volte risulta difficile o addirittura impossibile riconoscere un sito realizzato con Liferay [3].

Startup

La creazione di un tema vuoto è piuttosto semplice. Per farlo abbiamo a disposizione diversi modi. Ne illustriamo due.

Plugins Software Development Kit (SDK)

Il Plugin SDK [4] è un framework per la generazione di plugin (portlet, temi, hook, etc.) creato dal team di Liferay. Vediamo come utilizzarlo per il tema. Dal terminale posizionarsi all'interno della cartella dove si è scompattato il plugin SDK, dentro themes. Lanciare il comando create.bat su Windows o create.sh su Linux/Mac OS con i due argomenti richiesti: nome e titolo. Attenzione: il parametro nome non deve contenere spazi ed al nome viene automaticamente appeso "-theme".

Nello specifico, definiamo il nome del tema "Liferay-Solution" e il titolo di visualizzazione "Liferay Solution theme". Avremo quindi:

create.bat Liferay-Solution "Liferay Solution Theme"

Tramite questo script il plugin SDK crea dentro themes la cartella Liferay-Solution-Theme. All'interno troveremo i file necessari per il deploy di un tema. In questa stessa cartella inseriremo, come spiegato più avanti nell'articolo, i file (CSS, immagini, template, etc. ) utili a definire l'aspetto grafico del tema, organizzati secondo una precisa struttura.

Liferay IDE

Liferay IDE [5] è un plugin per Eclipse sviluppato anch'esso dal team di Liferay. Sostanzialmente ci permette di fare quello che facciamo con il Plugins SDK, ma in maniera visuale. Per i dettagli di installazione e configurazione si rimanda a [5].

Una volta installato, per creare il tema basta avviare il wizard dal menù (vedi fgura 4), riempire i campi richiesti, nome e titolo visualizzato e cliccare su Finish (vedi figura 5). Ora abbiamo il nostro tema vuoto pronto per la personalizzazione.

Il principio dell'ereditarietà

I temi Liferay sono organizzati in una struttura modulare che consente allo sviluppatore di modificare rapidamente l'aspetto grafico di una singola portlet o di un qualsiasi oggetto presente sulla pagina. Non è necessario personalizzare/modificare ogni singolo aspetto del tema in quanto esso eredita le immagini, gli stili e i template dai temi di default di Liferay. I temi personalizzati quindi si basano sulle differenze rispetto a temi di default di Liferay. Nel file build.xml è possibile determinare ciò che si desidera utilizzare come base per il tema. Il nostro tema dimostrativo "Liferay-Solution" si basa sul tema "_styled". Di seguito si riporta il contenuto del file build.xml

<project name="Liferay-Solution-theme" basedir="." default="deploy">
  <import file="../build-common-theme.xml" />
  <property name="theme.parent" value="_styled" />
</project>

Il tema padre è definito dalla proprietà theme.parent [6]. Nel nostro caso abbiamo scelto di ereditare "styled" che prevede stili delle portlet piuttosto minimali. Si potrebbe anche scegliere di ereditare il tema "unstyled" che non contiene alcun tipo di stile.

Struttura

La struttura di un tema organizza i diversi tipi di risorse in cartelle facilmente accessibili [7]. La struttura completa di "Liferay-Solution" è la seguente:

/ Liferay-Solution-theme /
  / Docroot /
    / WEB-INF /
      liferay-plugin-package.properties
      liferay-look-and-feel.xml
  / _diffs /
    / Css /
      custom.css
    / Images /
      / pic /
    / Layouttpl /
      / Custom /
        home.tpl
        home.png
    / Templates /
      portal_normal.vm
  / Css /
    application.css
    base.css
    custom.css
    dockbar.css
    extras.css
    forms.css
    layout.css
    main.css
    navigation.css
    portlet.css
  / Images /
    ...
  / Layouttpl /
    / Custom /
      home.tpl
      home.png
  / Templates /
    init_custom.vm
    navigation.vm
    portal_normal.vm
    portal_pop_up.vm
    portlet.vm

All'interno della cartella docroot è presente la cartella diffs dove andremo a inserire tutte le personalizzazioni, modificando esclusivamente le parti del tema che differiscono dal tema principale. Per fare questo è necessario copiare la struttura della directory del tema principale dentro la cartella diffs, ponendo solo le cartelle e i file necessari alla personalizzazione. Per esempio, se vogliamo sostituire un'icona di default (nello specifico search.png) dobbiamo ricreare il percorso relativo dentro la cartella diffs, ossia /images/common/search.png. Nel nostro tema "Liferay Solution", la struttura di diffs è la seguente:

/ _diffs /
  / Css /
    custom.css
  / Images /
    / common /
    / pic /
  / Layouttpl /
    / Custom /
      home.tpl
      home.png
  / Templates /
    portal_normal.vm

Andiamo ad analizzare le singole cartelle nel dettaglio.

Gli stylesheet: CSS

È la cartella che raccoglie gli stili .css del nostro tema e contiene esclusivamente il file custom.css, incluso nel file main.css del tema principale. Essendo l'ultimo file letto, per la legge della cascata va a sostituire tutti gli altri stili precedentemente richiamati. Di conseguenza per personalizzare il nostro tema è sufficiente modificare il file custom.css aggiungendo nuovi stili o sovrascrivendo quelli del tema principale. Si raccomanda di non modificare gli altri stili specifici del portale (application.css, dockbar.css, ecc); questo renderà molto più facile l'aggiornamento del portale in quanto basterà sostituire solamente il file custom.css e applicare eventualmente gli opportuni aggiustamenti.

Le immagini del portale: IMAGES

Contiene la directory pic nella quale andremo a inserire tutte le immagini personalizzate del portale e la directory common che contiene le immagini sovrascritte a quelle di default (vedi paragrafo Struttura)

I modelli di layout: LAYOUTTPL

L'impaginazione del main-content, ovvero l'area in cui andremo a posizionare le varie portlet, viene gestita tramite i modelli di layout. Essi dividono la pagina in varie aree dove poter trascinare e posizionare le portlet [8]. La struttura tipica di un file .tpl con Liferay 5.x è:

<td class="lfr-column" colspan="2" id="column-1" valign="top">
  $processor.processColumn("column-1")
</td>

dove l'impaginazione è organizzata con le tabelle. Invece, con Liferay 6.0, i file .tpl hanno un aspetto molto simile al seguente:

<div id="main-content" role="main">
  <div class="portlet-layout">
    <div class="portlet-column" id="column-1">
      $processor.processColumn("column-1")
    </div>
    <div class="portlet-column" id="column-2">
      $processor.processColumn("column-2")
    </div>
  </div>
</div>

dove l'impaginazione è organizzata con i DIV. I modelli predefiniti di Liferay 6.0 controllano se il browser utilizzato è IE di una versione precedente alla 8:

#if ($browserSniffer.isIe($request) && $browserSniffer.getMajorVersion($request) < 8)

In questo caso i layout utilizzano la vecchia struttura a tabelle, mentre per tutti gli altri browser utilizzano i DIV, evitando così di specificare gli stili ad hoc per tutte le versione di IE. Liferay viene fornito con diversi modelli di layout predefiniti.

Molto spesso capita di dover costruire una pagina più complessa, come puo' essere ad esempio una homepage. Si deve quindi creare un modello di layout personalizzato. Per il nostro tema grafico abbiamo realizzato il seguente layout chiamato home.tpl:

<div class="home" id="main-content" role="main">
  <div class="portlet-layout portlet-column-big">
    <div class="portlet-column-1 portlet-column" id="column-1">
      $processor.processColumn("column-1")
    </div>
    <div class="portlet-column-2 portlet-column" id="column-2">
      $processor.processColumn("column-2")
    </div>
    <div class="portlet-column-3 portlet-column" id="column-3">
      $processor.processColumn("column-3")
    </div>
    <div class="portlet-column-4 portlet-column" id="column-4">
      $processor.processColumn("column-4")
    </div>
  </div>
  <div class="portlet-layout">
    <div class="portlet-column-left portlet-column" id="column-5">
      $processor.processColumn("column-5")
    </div>
    <div class="portlet-column-center portlet-column" id="column-6">
      $processor.processColumn("column-6")
    </div>
  </div>
</div>

Coerentemente con la filosofia di replicare solamente le cartelle su cui abbiamo effettuato una personalizzazione, dentro la directory / Layouttpl / andiamo a creare la cartella / Custom / all'interno della quale sistemeremo il file home.tpl e l'icona home.png (vedi figura 8).

Per far comparire il nostro layout all'interno della lista dei layout di default, è necessario che entrambi vengano richiamati nel file /docroot/WEB-INF/liferay-look-and-feel.xml con la seguente sintassi:

<layout-templates>
  <custom>
    <layout-template id="home" name="Home">
      <template-path>/layouttpl/custom/home.tpl</template-path>
      <wap-template-path>/layouttpl/custom/home.tpl</wap-template-path>
      <thumbnail-path>/layouttpl/custom/home.png</thumbnail-path>
    </layout-template>
  </custom>
</layout-templates>

Operando in questo modo il layout viene associato al nostro tema grafico e non può essere applicato al di fuori di esso. Alternativamente è possibile creare un layout staccato dal tema, disponibile a livello globale, così da poterlo utilizzare indipendentemente dal tema scelto.

I modelli di pagina: TEMPLATE

È la directory che contiene i modelli di pagina o template. Il template su cui siamo andati ad intervenire è portal_normal.vm modificando i riferimenti nel footer e commentando la breadcrumb in quanto non prevista nella nostra interfaccia grafica. Questo file contiene la dockbar ed è possibile, ad esempio, inserire eventuali javascript, controllare la posizione della toolbar di navigazione e gestire variabili custom [9] di Velocity [2].

Il nostro tema grafico

A titolo di esempio pubblichiamo il tema grafico del progetto "Liferay Solution Theme", un portale dimostrativo dai contenuti fittizi (vedi figura 11).

Sono state inserite quattro applicazioni di default:

Site Map è la portlet che mostra i link a tutte le pagine del sito. Nel nostro caso l'abbiamo configurata in modo da visualizzare soltanto le pagine figlie della pagina Archivio.

Search è laportlet che consente agli utenti di ricercare contenuti all'interno del sito.

Asset Publisher è la portlet che permette di visualizzare liste di articoli di diverse tipologie (blog, documenti, wiki, ecc). È possibile scegliere la tipologia di visualizzazione (solo titolo, titolo con estratto, titolo con contenuto) e decidere quali tipologie mostrare tramite l'utilizzo dei tags.

Web Content Display è la portlet che consente di visualizzare il contenuto di un solo articolo.

Una volta inserite le applicazioni, dobbiamo scegliere se applicare o meno i bordi a queste portlet. Se intendiamo aggiungere i bordi, andremo ad intervenire su tre stili:

• .portlet .portlet-topper
• .portlet .portlet-title
• .portlet .portlet-content

Con la personalizzazione di questi, è possibile dare la stessa veste grafica a tutte le portlet col bordo che andremo ad inserire nel nostro portale. Se abbiamo l'esigenza di personalizzare ulteriormente possiamo operare in due modi:

• personalizzare la singola applicazione specificando nel file custom.css la classe della portlet interessata (ad esempio .portlet-search .portlet .portlet-title);
• personalizzare la singola portlet andando ad incollare lo stile direttamente in "aspetto grafico > stili avanzati" specificando l'istanza della portlet (ad esempio: #ppid56INSTANCEs0N6). L'inconveniente è che, una volta cancellata la portlet, questi dati vengono persi con essa.

Una portlet senza bordi, invece, ha una struttura più snella, senza il titolo e caratterizzata da una sola classe: .portlet-borderless-container. Quindi per la personalizzazione andremo ad intervenire sullo stile .portlet-borderless-container e sulle sue declinazioni.

Una volta terminate tutte le personalizzazioni, lanciamo il comando

ant deploy

nel terminale all'interno della cartella del tema. Andiamo così a creare il file .war (Web Archives Repository) ossia un archivio che contiene tutti i file del tema. Infine procediamo con l'integrazione attraverso l'installazione del file

Liferay-Solution-theme-5.2.3.1.war

nel pannello di controllo del portale (Installazione Plugin > Plugin del tema > Installa altri temi > Invia file).

Conclusioni

Con questo primo articolo sulla customizzazione grafica, abbiamo voluto mostrare sia alcuni concetti alla base del funzionamento di Liferay, sia il modo in cui è possibile realizzare alcuni semplici temi grafici in maniera lineare e veloce. Con questo strumento e un po' di capacità, infatti, la qualità dei risultati è garantita: sicuramente un ausilio notevole per chi deve realizzare portali. Continueremo ad approfondire Liferay nei prossimi numeri: nel frattempo i lettori interessati possono scaricare e analizzare il tema grafico proposto (

Riferimenti

• [1] Liferay: il sito

http://www.liferay.com/

• [2] Apache Velocity

http://velocity.apache.org/

• [3] Development LIferay: come creare un tema

http://www.liferay.com/documentation/liferay-portal/6.0/development/-/ai/creating-liferay-themes-2

• [4] Plugins Software Development Kit (SDK)

http://www.liferay.com/documentation/liferay-portal/6.0/development/-/ai/the-plugins-sdk

• [5] Liferay IDE

http://www.liferay.com/community/wiki/-/wiki/Main/Liferay+IDE

• [6] Development LIferay: proprietà theme-parent

http://www.liferay.com/web/olaf.kock/blog/-/blogs/theme-development%3a-choosing-your-parent?33redirect=%2fcommunity%2fblogs

• [7] Development LIferay: anatomia di un tema

http://www.liferay.com/documentation/liferay-portal/6.0/development/-/ai/anatomy-of-a-theme

• [8] Layout

http://www.liferay.com/community/wiki/-/wiki/Main/Layout+Template

• [9] Variabili di Velocity custom

http://www.liferay.com/community/wiki/-/wiki/Main/Custom+Velocity+Variables