Main

Vi utvecklar utifrån våra riktlinjer och beslut. SAD Externwebben Frontend dokumentet innehåller flera kapitel av de övergripande riktlinjer som vi utvecklar efter.

Frontend i följande sub-områden

• HTML
• CSS
• JavaScript
• Tillgänglighet

HTML

HTML riktlinjer

Vi kodar HTML och använder template språk Handlebars.js
Undvik att implementera logik i hbs-filerna. I några av våra webbplatser har vi JSP också.

CSS

CSS riktlinjer

Prefix/namespace: Alla våra klasser ska ha ett prefix/namespace, på Styleguide s_ och lokalt på presentationstjänsterna tar vi prefix från tjänstens namn tex Mina Utbetalningar mu_

BEM

Vi använder BEM namnstandard, Harry Roberts variant för att namnge css-klasser. Det innebär att vi delar in sidan i block och element (=htmltaggar) i block. Ett block är t ex

Element som hör till ett block namnges med blockets namn först, sedan __ och sedan elementets namn

Det finns inga nivårer av element, element i element namnges bara som "blockets-namn__elementets-namn". Om det finns behov av att ytterligare bryta ut delar så kan man påbörja ett nytt block. Element och block kan ha modifier-klass som signalerar att det är en variant av det ursprungliga elementet. Modifier-klassen läggs på förutom basklassen t ex

Flytta gärna css som måste överlagras till modifier-klassen för att undvika onödig överlagring. Det är okej med element som inte finns i sin basform utan bara med olika modifiers.

State-klasser

Element och block kan ha en state-klass som signalerar att det befinner sig i ett visst tillstånd. Detta används ofta när man med javascript vill förändra ett element och markera att det är aktivt, expanderat, felaktigt etc. State-klassen läggs på ytterligare till elementet. State-klasser börjar med ```is-``` (förutom namespace)

.s_contact-form__input {
//style för element

&.s_is-error {
//style för element när det är fel
}
}

Filstruktur

Varje css-block (se ovan) ska ligga i en fil som heter samma som blocket. Vi använder _ för att markera sass-filer som ska inkluderas i andra.

I en fil med namnet `_contact-form.scss` får bara klasser som börjar med `.s_contact-form` finnas.** State-klasser (.s_is-..) undantaget. Om ett block behöver stylas olika beroende på dess kontext ska en modifier läggas på (istället för att styla på förälderns klass).

Formatering av koden

Vi utgår ifrån default uppsättning av regler i [sass-lint](https://github.com/sasstools/sass-lint) med några få undantag, se sass-lint.yml i styleguide All css som berör ett element ska ligga inuti det elementets måsvingar. Det gäller såväl modifier-klasser, state-klasser, mediaqueries och saker som påverkas av en förälder (inom blocket). Exempel:

.s_contact-form__input {
font-size: 1.2em;

@include s_mq-gte-small {
font-size: 1.4em;
}

&.s_contact-form__input--left {
float: left;
}

&.s_is-active {
font-weight: bold;
}

.s_contact-form.s_is-error & {
border-color: $color-error;
}
}

Vad vi stylar på

Vi använder med få undantag klasser för att styla element. Normalize-css och bas-css får sätta style direkt på htmltagg. I det fall vi inte kan påverka html (det kommer från CMS) kan vi styla direkt på element inom blocket.

Gömma element

För att dölja/gömma element används attributet hidden. Exempel:

.s_some-block__some-element {
//style för element

&[hidden] {
//dölj element med hidden attribut
display: none;
}
}

Andra riktlinjer för sass

• Alla färger deklareras i varibler
• Använd $_ för att markera en variabel som bara används lokalt i nuvarande fil
• Använd mixins, inte extends

JavaScript

JavaScript riktlinjer

Ramverk/bibliotek: Vi använder så få ramverk och bibliotek som möjligt för att sidan inte ska bli för tung. Det är okej att använda små bibliotek (max 5kB) som utför en specifik uppgift där vi vinner tid och förvaltningskostad på att använda ett färdigt bibliotek. Bibliotek hämtas ner via npm och laddas mha

där de används. Webpack ser till att biblioteket bara laddas en gång.

Namnstandard

• Namnge filer med små bokstäver och bindestreck mellan orden

• Namnge test-filer med .test på slutet

• Namnge konstanter med stora bokstäver

• Namnge klasser med stor bokstav först

• Använd generellt camelcase i övrig javascript

• Namnge variabler som håller DOM-element med $ först

• Namnge privata metoder (som inte är tänkta att användas utanför klass/modul) med _

Moduler

Vi använder tre sätt för att skriva javascript-moduler, klasser, objekt eller funtioner.

Klasser

Klasser ska användas för moduler som kan ha flera instanser på samma sida. Se till att koden inuti klassen inte jobbar med element globalt, utan alltid letar efter element inuti elementet som modulen initieras i.

Initiera klass från "index.js"

Objekt

Ifall du är säker på att din modul bara ska köras en gång per sida bör du använda ett objekt istället för klass. Det blir ett naturligt singleton och det är lättare att förstå att modulen bara kan initieras en gång per sida.

Initiera objekt från "index.js"

Funktion

I de fall javascriptet är mycket enkelt kan det gå att göra som en ren funktion. Exempel på detta är index-filerna som bara initierar komponenter.

Css klasser i javascript

• Klasser som används av javascript ska prefixas

• Klasser som är prefixade "s_js-" får ej användas av css för styling, element som används av javascript har alltså en klass för javascript och en för styling
• Klasser som används för att initiera en viss javascriptmodul får gärna heta som modulen fast med prefix först dubbla klassnamn, ett för js och ett för css

• Klasser som används för att hitta element inuti modulen namnges enligt BEM standard precis som för vanliga css-klasserna

• State-klasser får sättas direkt av javascript, dessa börjar alltid med "s_is-" och beskriver ett tillstånd på ett element

• State-klasser får användas av både javascript och css

Dölja element

Använd gärna attributet ```hidden``` för att dölja/visa element. Lägg dit attributet för att dölja elementet, ta bort det för att visa elementet.

Parametrar och statiska variabler till moduler

Använd gärna data-attribut för att skicka in parametrar/variabler till javascript-moduler. Data-attributen ska namnges med prefix "data-s_"

Logiska variabler

För att göra koden mer läsbar kan man använda logiska variabler. D.v.s. variabler som beskriver ett tillstånd istället för att lista en lång komplex if satts.

Länkar

• Lär dig javascript utan jquery
• ES2015 mha babel
• ESlint

Tillganglighet

Tillgänglighet riktlinjer

• Huvudinnehåll är åtkomligt utan javascript
• Rätt html5 element (article, header, footer, main mm)
• Korrekt rubrikstruktur (h1 -> h2 -> h3 osv, börja om på h1 inuti article)
• Formulär använder fieldset+legend för att gruppera fält och label finns för alla fält
• Färgkontrast - text mot bakgrund (kolla med Color contrast check)
• Tabba genom sidan funkar bra (även fäll in/ut funktioner etc)
• Tabbfokus syns tydligt (ram med bjärt färg, t ex turkos, runt elementet)
• Felmeddelanden läses upp (lägg role="alert" och aria-live="assertive" på elementet)
• Element som fäller ut annat innehåll markeras med aria-expanded=true/false och aria-controls (som hänvisar till utfällt element)
• Använd riktigt button-element för knappar (istället för att lägga role="button" på annan tagg)
• Använd autocomplete="new-password" för att undvika browserns automatiska ifyllnad.
• För obligatoriska fält, sätt attributet required (undvik aria-required).

Axe-Core tillgänglighetstestning

För att stödja dig som utvecklare i att koda tillgängligt, använder vi JS-libbet Axe-core i våra dev-miljöer. Det validerar den färdigrenderade sidan mot WCAG 2.1. Om sidan har valideringsfel, rapporteras dessa i sidhuvudet. Axe-core körs alltså enbart i dev-miljöer (hostnamn måste börja på 'dev-').

Om du vill använda Axe i valfri annan miljö, kan du antingen skapa en kaka i LocalStorage med namnet 'va_enabled'. Du kan även kicka igång Axe i konsollen med 'window.pm.devTools.validateAccessibility.init()'. Det kan vara användbart för att kontrollera dynamisk HTML som ändrats efter den initiala sidrenderingen.

Testa gärna som om du vore blind/synskadad genom att köra sidan med ChromeVox (plugin till Chrome).

Här nedan följer lite aria-tips

• Använd alltid lämpligt "role"-attribut i samband med aria för att få aria-attributet att fungera
• aria-label - Läser upp angiven text om label inte finns
• aria-labelledby - Läser upp texten i angivet element om label inte finns
• aria-describedby - Läser upp texten i angivet element
• Inkludera inte mixins från Styleguide till en presentationstjänst, använd css klass istället tex s_icon-plus

Visual Regression Test

Jobba med Visual Regression Testing

Navigera till terminalen under ps-styleguide och kör:

När testarna har körts, öppnas en ny flik i webbläsaren där testresultatet visas. Verifiera att endast dina ändringar färgmarkerats som diff.

Om du vill acceptera resultatet kör du "npm run regression:approve". Nya versioner av de bildfiler du förändrat kommer då att skapas. Gör "git commit" och "git push" endast på de nya versionerna.

Så skapar vi ett test

Det finns flera implementationer att skapa test med.
Under kataloggen styleguide/ps-styleguide/visual-regression/tests/
finns:

• baseScenarios.js
• elementsScenarios.js
• componentsScenarios.js
• developersScenarios.js

Det är indelat såsom de olika sidor på Styleguide.
tex om man skapar en ny section på base, då kan man lägga en ny entry i arrayen ['color', 'typography', 'space'] under baseScenarios.js,
Under elementsScenarios.js finns det flera mer interaktion med element för att skapa avancerade test. text

Main

Detta är exempel på hur en responsive-table ser ut och fungerar

Main

Detta är exempel på hur en print-knapp ser ut och fungerar

Main

Detta är exempel på hur en expand-all-knapp ser ut och fungerar

Main

Detta är exempel på hur en show-hide ser ut och fungerar

Main

Detta är exempel på hur enable-disable fungerar

Main

Detta är exempel på hur en clear ser ut och fungerar

Main

Detta är exempel på hur en pnr-input ser ut och fungerar

Main

Detta är exempel på hur en date-input ser ut och fungerar

Main

Detta är exempel på hur en year-month-input fungerar

Main

Detta är exempel på hur en multi-select ser ut

Detta är två exempel på hur en input-select kan se ut

Main

Detta är exempel på hur en add-remove ser ut

Main

Detta är exempel på hur ett ansökanflöde ser ut

Main

Detta är exempel på hur ett ändringsflöde ser ut

Main

Code

s_divider

Divider med modifier s_divider--readmore

Main

Detta är exempel på hur en CharacterCounter fungerar

Main

Main

När användaren stängt av JavaScript och funktionalitet kräver det. Visa info meddelande samt lägg til cssklass "s_js__required"

Main

Detta är exempel på hur Disclaimer (friskrivning) ser ut och fungerar

En friskrivningstext enligt nedan ska finnas omedelbart före varje knapprad med en signeringsknapp där användaren kan starta en signering.

Main

Som utvecklare kopierar du mappen "template-component" och börjar implementera din kod med hjälp av den.
Mappen finns på path: resources\templates\components\template-component

Info

Filstruktur

sg_box har en tydlig filstruktur. Namnet på innehållet man vill presentera är basen.
Bilden visar filstruktur på template-component
Tabs mappen innehåller .hbs filer med innehåll för respektive tab.