SPA-portletin JSP-avaussivun rakenne

Angular-kirjaston mukaanotto portlettiin on vastaava, kuin muillakin Javascript-kirjastoilla. Se määritellään liferay-portlet.xml sivulla. Google suosittelee Angularin käyttöönottoa websivun osoitteesta, esimerkiksi:

<header-portlet-javascript>http://ajax.googleapis.com/ajax/libs/angularjs/1.4.4/angular.min.js</header-portlet-javascript>

Javascript-kirjastot on yksinkertaisinta ottaa mukaan nimenomaan ”headerissa”, jolloin käytettöalue on koko sivu. Liferay-portlet.xml sivun sisältö on tavanomainen. Ajaxable-tagin arvoksi pitää laittaa true. Sovelluskohtaisia Javascript-tiedostoja kertyy useita JSP-portlettia kohden, koska Javascript-koodi kannattaa pilkkoa omiin yleiskäyttöisiin tiedostoihin.

SPA-portleteilla on yksi JSP-aloitussivu, joka toimii toiminnan kehyksenä. Tämä sivu muistuttaa tavallisten portlettien JSP-sivuja. Muut sivut ovat yksinkertaisempia, koska niistä puuttuu aloitussivun Java-koodi, joka on aloitussivulla merkittävässä roolissa. SPA-portetin aloitussivun data voitaisiin tuoda sivua ladatessa, mutta parempi ajatus on käyttää siinäkin Ajaxia. Tässä toimii jälleen yksinkertaisuuden periaate: data haetaan vain yhdellä tavalla portlettien JSP-sivulla. Tämä myös yksinkertaistaa portlet-luokan Java-koodia. Käsittelemme ensin avaussivun rakenteen.

Seppien ideana on jälleen yksinkertaisuus ja yleinen toistettava rakenne. JSP-avaussivun rakenne käyttää seuraavaa järjestystä:
1. JSP-sivun tagit: <%@ taglib…%> ja <%@ page import…%> rivit.
2. Portlettien valmiiden Java-objektien käyttöönotto: <portlet:defineObjects />
3. Mahdollinen Java-koodi mielellään vain tähän kohtaan, mutta sitä ei pitäisi normaalisti tarvita lainkaan.
4. ResourceURLien määritys. Tässä annetaan jokaiselle Ajax-kutsulle sen URL.
5. HTML-osuus, jonka root-elementti on div (portleteissa ei ole html-, head- eikä body-tageja)
6. Javascript-osuus, normaalisti script-tagien sisällä.

Ensimmäinen (1) kohta hyvin suoraviivainen. Portletti-tagit on otettava mukaan ainakin Ajax-taskien identifioimisen takia:

<%@ taglib uri=”http://java.sun.com/portlet_2_0″ prefix=”portlet” %>

JSP-sivu on Java-koodia, ja siksi siinä on otettava mukaan (import) tarvittavat Java-luokat, ainakin portlettiluokka, koska Ajax-tunnisteet on määritelty siellä:

<%@ page import=”com.test.company.CompaniesPortlet” %>

Muut Java-luokat määritellään samalla tavalla. Näiden tarve pitäisi kuitenkin olla minimaalinen, ja käyttö silloinkin hyvin perusteltu, koska kyse on MVC-arkkitehtuurista, jossa kontrolleri on clientilla. Mikäli avaavalla JSP-sivulla on Java-koodia ja tarvitaan luokkia, on se luultavammin merkki tämän arkkitehtuurin epätarkasta käsittelystä. Sovellusarkkitehtuureissa eri osien rajat on pidettävä hyvin selkeinä ja havainnollisina, pienetkin poikkeamat sotkevat merkittävästi rakennetta.

Toinen (2) kohta on vakio, ja se on syytä merkitä ensimmäisen kohdan jälkeen, selkeyden vuoksi. Portletin valmisobjekteja ei SPA-portleteissa aina tarvita, varsinkin jos sivulla ei ole Java-koodia. Oliot (objektit) löytyvät portlettien dokumentaatiosta ja ne ovat tavanomaiset vakio-objektit JSP-sivulla. Sepät laittavat kyseisen merkinnän aina, ikäänkuin portlettiin kuuluvana leimana, jolloin olioiden käytettävyyttä ei tarvitse jatkossa miettiä.

Kolmas (3) kohta pitäisi olla likimain tyhjä. Tämä on skriplettikoodin (<%…%>) paikka ja tavallisissa portleteissa tätä kohtaa käytetään datan hakuun. SPA-portletissa data haetaan Ajax-toiminnoilla, joten pyri jättämään tämä kohta tyhjäksi, ellei ole hyvää syytä toimia toisin.

Neljäs (4) kohta on hyvin selkä ja myös vakiomainen. Tässä annetaan jokaiselle portletin JSP-sivujen Ajax-taskille oma tunnus, jota Javascript-koodissa ja Java-portletkoodissa käytetään tunnistamaan toiminto. Kaikki määritykset ovat tämän kaltaisia (huomio ”portlet” prefix, joka määriteltiin kohdassa 1):

<portlet:resourceURL var=”selectAllUrl” id=”<%=CompaniesPortlet.SELECT_ALL%>” />
<portlet:resourceURL var=”selectRowUrl” id=”<%=CompaniesPortlet.SELECT_ROW%>” />

Viides (5) kohta on sivun sisältö. SPA-portletissa tämä voi olla hyvin yksinkertainen tapauksissa, joissa vaihtuva sivu sisältää kaiken näytettävän. Aivan yhtähyvin vaihdettava sivu on vain osa sivua, jolloin aloitussivulla on enemmän HTML-koodia. Sepät käyttävät tässä puhdasta HTML:aa tai Angularin kanssa yhteensopivaa käyttöliittymäkirjastoa. On myös mahdollista tehdä useita vaihdettavia sisältökohtia samalla sivulle. Miten tämä Angularissa tapahtuu, siitä myöhemmissä blogeissa.

Kohta kuusi (6) sisältää aloitussivun Javascript-koodin. Ensimmäiseksi on perusteltava sitä, miksi tätä koodia ei sisällytetä erilliseen Javascript-tiedostoon. Tässä kohtaa määritellään globaalit Javascript-muuttujat ja edellä määritellyt Ajax-taskien tunnisteet kopioidaan Javascript-muuttujiin, nekin ovat globaaleja. Osa muuttujista on käytännössä oltava globaaleja, eikä sen toteuttaminen toisin ole ainakaan yhtään selkeämpää, näin kertoo seppien kokemus.

Seuraavassa blogissa jatkamme avaussivun Javascript-koodin toteutuksesta, mitä siinä on huomioitava, yleisesti ja nimenomaan SPA-Angular-käyttöliittymässä.