Comunitat DSTSC

1. Requisits generals de desenvolupament sobre Liferay.

1.1. Àmbit d'aplicació

Aquest apartat recull les especificacions de referència en la realització de projectes Liferay desenvolupats per la Diputació de Barcelona.

En termes generals, qualsevol arquitectura, solució, component estàndard o versió l'acceptació de la qual no estigui expressament citat, s'entén no pot ser incorporat implícitament, ja que la seva adopció, depèn, en tot cas, de la validació i acceptació expressa de la DSTSC.

En qualsevol cas els desenvolupaments s'ajustaran immediatament a les modificacions que es derivin de canvis en les especificacions tècniques recollides en aquest document, sigui per la pròpia evolució tecnològica, o com a conseqüència de les directives que, per la seva transcendència, es puguin establir en matèria de seguretat.

1.2. Característiques dels desenvolupaments

Els portlets, temes, layouts, etc. que es desenvolupin hauran de complir les següents característiques:

• Es compliran totes les convencions de codi java que proposa Sun / Oracle (http://www.oracle.com/technetwork/java/codeconv-138413.html).
• S'evitarà l'ús d'init params, excepte en aquells casos degudament justificats, i tots els paràmetres de configuració han de ser modificables des de la pantalla de configuració del portlet.
• La configuració d'un portlet es farà mitjançant l'acció config i no edit. Dit d'una altra manera, el portlet es configurarà amb una finestra emergent a l'estil dels portlets propis de Liferay.
• S'evitarà l'ús del plugin-ext per tots els mitjans possibles, excepte en aquells casos degudament justificats.
• Tots els connectors s'implementaran URLs amigables, excepte aquells que no sigui necessari com, per exemple, el que vagin al tauler de control.
• Tots els connectors seran multiidioma i implementaran aquells que estiguin disponibles al portal destinació.
• Els portlets es desenvoluparan d'acord amb la classe MVCPortlet, excepte en aquells casos degudament justificats
• La capa de persistència de tots els plugins implementarà aplicant el Service Builder de Liferay, sense excepció. També s'utilitzarà per generar serveis web.
• Els connectors que implementin una recerca s'utilitzaran Elastic Search i no accediran a la base de dades, excepte en els casos degudament justificats (com l'ús de camps no indexats).
• Les estructures de continguts web faran ús de totes les característiques que aporta Liferay, com camps obligatoris, ajudes, noms de camps comprensibles per a l'usuari, etc.
• Les plantilles de continguts web tindran una mida el més curt possible i s'utilitzaran per a una sola finalitat, sense complicar-se en excés per reaprofitar en diversos casos, facilitant així el seu manteniment i comprensió. Si cal es duplicaran parts de codi en diverses plantilles facilitant així l'evolució de cadascuna per separat. Totes es desenvoluparan en FreeMarker.
• La Diputació farà revisions de codi i podrà requerir que es refacin certes parts, classes, JSPs, o el portlet sencer, per no complir uns mínims paràmetres de qualitat (mala codificació, optimització de codi, temps de resposta, reutilització de codi, optimització de les connexions a base de dades, etc.)
• La versió de java serà la que la Diputació tingui el servidor d'aplicacions en el moment de començar els desenvolupaments.
• Absolutament tot el que es desenvolupi s'haurà de fer amb Liferay Developer Studio, amb l'última versió disponible.
• Els desenvolupaments es versionaran mitjançant Git, en un servidor de la Diputació de Barcelona. Es farà ús de l'estructura típica de "develop" i "master", fent ús de Git-flow (features, releases, ...).
   

2. Requisits per al disseny web

A continuació es detallen els requisits tècnics que han de complir els dissenys web o aplicacions web corporatius, així com els entregables que han de subministrar els proveïdors / dissenyadors / maquetadors:

2.1. Base de treball

• Es desenvoluparà en HTML5 sobre un sistema basat en retícules.
• S'ha d'utilitzar Bootstrap (versió 4.3):
  • Això vol dir que cal maquetar basant-se en el Grid System de Bootstrap (és a dir han d'aparèixer classes del tipus: class="container", class="row", class="col-lg-4"). Igual que els botons i altres components que han de seguir les classes definides per Bootstrap.
  • Els desenvolupaments .js que es necessitin s'han de fer en un fitxer .js a part del de Bootstrap, per poder actualitzar o canviar la versió posteriorment. I aquest fitxer de Bootstrap ha de ser amb la versió 'minimitzada' (bootstrap.min.js).
  • El mateix passa amb els .css, haurien de ser dos arxius separats: un amb els estils de bootstrap (bootstrap.min.css) i un altre o diversos amb les personalitzacions fetes a mida.
  • Totes les llibreries javaScript necessàries per Bootstrap ja van incloses a Liferay y no cal afegir-les, excepte quan es fa una maqueta html.
• La primera línia de totes les pàgines serà: <! DOCTYPE html>
• El codi HTML ha de validar la seva estructura segons els criteris de la W3C: http://validator.w3.org
• El disseny ha de ser responsiu i adaptar-se als salts de resolució definits per Bootstrap
• Es requereix compatibilitat amb els següents navegadors:
  • IE11 o superior (tant amb manera compatibilitat activat com desactivat).
  • Chrome versió actual - 1.
  • Firefox versió actual - 1.
  • Safari versió actual - 1.
  • Opera versió actual - 1.
• S'han de complir els criteris d'accessibilitat de les pautes WCAG 2.1 del W3C assolint el nivell AA. Validadors: http://www.tawdis.net, Wave, etc.
• En tot moment durant el desenvolupament i l’execució del contracte es vetllarà pel compliment del Reglament de Protecció de Dades Personals. Això inclou, si s’escau, també la recollida de consentiment d’ús de les cookies per l’entorn del web i la recollida de dades personals en tots els formularis.
• A totes les planes del lloc web s’incorporarà un script pel seguiment amb Google Analytics/Google Tag Manager que serà proporcionat per la corporació.
• S'utilitzaran els rols WAI-ARIA per marcar les zones funcionals del web: article / banner / complementary / contentInfo / main / navigation / search. Exemple: <div id = "logo" role = "banner"> ... </ div>
• Es treballarà amb el joc de caràcters UTF-8.

2.2. Contrast de colors (fons / text)

El contrast de colors ha de complir la WCAG AA i cal validar que el text i el fons estan prou contrastats. Es pot utilitzar un validador en línia, com ara: ContrastChecker.

2.3. Sobre l'HTML

• Per garantir la compatibilitat amb tots els dispositius d'incloure sempre les següents directives en l'head, tal i com indica la web de Boostrap:

<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

2.4. Sobre les CSSs

• Tots els estils, excepte allò que es justifiqui o no sigui possible, han d'estar fora del codi HTML i en fitxers css. No s'utilitzaran estils incrustats en html ni estils directament en el head, excepte casos degudament justificats.
• No es modificaran estils originals de llibreries externes (com Bootstrap). Per sobreescriure'ls s'utilitzaran arxius css separats que es carregaran posteriorment a l'original. Idealment aquestes classes sobreescrites hauran de ser més específiques que les originals.
• Es recomana validar la qualitat del codi amb http://csslint.net i seguir les seves recomanacions.
• Evitarem especialment l'ús i sobreús del !Important, cal treballar amb l'especificitat.
• S'ha de subministrar disseny i estils per a tots els elements HTML:
  • Taules (table)
  • Llistes de definició (dl, dt, dd)
  • Text:
    • Tipografies i cos de lletra
    • Encapçalaments (h1, h2, h3, h4, h5, h6)
    • Estats dels vincles (hover, activi ...)
    • Avisos (text destacat)
  • Llistes (ul, o ...)
  • Formularis (label, input, select, fieldset, textarea, checkbox ...)
  • Botons
  • etc ...

2.5. Sobre el JS

• Tot el javascript ha d'estar fora de l'HTML en fitxers .js. Queda prohibit l'ús de javascript inline, excepte en aquells casos que es justifiqui convenientment.
• Tot el javascript ha de ser no-intrusiu i executar-se després de l'esdeveniment ready (). S'haura de tenir en compte l'ús de les Automatic Single Page Application de Liferay i l'adaptació del codi Javascript a aquest funcionament i els seus events propis.
• Molt important! El desenvolupament en javascript es farà tot sota la directiu: "usi strict";
• Es recomana validar la qualitat del codi amb http://jslint.com i seguir les seves recomanacions.

2.6. Entregables

Els entregables d'un nou disseny seran:

• Per una maqueta html:
  • Fitxers de treball amb .psd o similars.
  • Pàgina maquetada amb HTML / CSS / JS del layout i una mostra de tots els elements HTML disponibles (llista, taula, títols, formularis, botons, avisos, etc ...).
  • Pàgina maquetada amb HTML / CSS / JS per a cada tipus diferent de pàgina que contempli el disseny. Alguns exemples típics són:
    • Portada.
    • Pàgina interior.
    • Pàgina interior amb desplegables.
    • Pàgina interior amb menú a l'esquerra.
    • Pàgina interior amb columnes.
    • Pàgina interior amb formularis.
    • Pàgina de resultats de cerca.
    • etc.
• Per un tema Liferay:
  • El plugin de tema completament desenvolupat i pujat al Git corporatiu.
  • Els Layouts que puguin ser necessaris, ja siguin nous o modificats (mantenint la compatibilitat amb qui ja estigui fent ús).
  • Les noves estructures i plantilles de contiguts web, si són necessàries.
  • Els ADTs (plantilles de visualització d'aplicació), si s'ha fet ús.
  • Les modificacions de plugins que hagin estat necessàries, prèviament aprovades per la Diputació.