search

detfaellesdesignsystem / dkfds-components

Styling og komponenter
Other
43 stars 13 forks source link

Migreringsguide for v10.0.0 #236

Open detfaellesdesignsystem opened 2 weeks ago

detfaellesdesignsystem commented 2 weeks ago

Migreringsguide

Før du begynder

Denne migreringsguide er henvendt til projekter, der skal opgradere fra version 9 af Det Fælles Designsystem (FDS) til version 10. Migreringsguiden dækker ikke, hvordan der migreres fra ældre versioner.

Migreringsguidens formål er at få projekter hurtigt i gang med version 10. Guiden beskriver derfor, hvordan man migrerer ved hjælp af DEPRECATED-filerne, da disse sørger for, at det meste tidligere HTML kan benyttes. Det er derefter muligt gradvist, komponent for komponent, at opgradere fuldt til version 10. DEPRECATED-filerne indeholder stadig breaking changes, men der er væsentligt færre af dem.

Guiden fokuserer på de tilpasninger, som er nødvendige for de fleste projekter. Afhængigt af hvordan dit projekt anvender og eventuelt har tilpasset koden i tidligere versioner, kan der være behov for flere justeringer. Husk at tilpasse URLs vist i guidens eksempler, så de peger på de rigtige mapper i dit projekt.

DEPRECATED-filerne vil blive fjernet senere i en major-version af FDS og eksisterer kun for at gøre det lettere at gå fra version 9 til version 10.

Se evt. release notes og Justering af tema og stylesheets for mere information.

Importér og opdatér stylesheets

Opdatering af css-fil

Dette trin gælder kun, hvis du ønsker at bruge DEPRECATED-filerne.

Hvis du benytter et af de medfølgende CSS-stylesheets, kan du udskifte det med deprecated-versionen.

Hvis du fx tidligere har brugt stylesheetet

<link type="text/css" rel="stylesheet" href="dist/css/dkfds-borgerdk.min.css">

ændres det nu til

<link type="text/css" rel="stylesheet" href="dist/DEPRECATED/dkfds-borgerdk-DEPRECATED.min.css">

Opdatering af scss-filer

FDS anvender fra version 10 @use i stedet for @import. Dog kan det være svært for nogle projekter at migrere til @use og derfor er der i de følgende eksempler anvendt @import. Se Justering af tema og stylesheets for, hvordan du importerer med @use.   I version 9 var de tre variable til at ændre stier til fonte, billeder og ikoner defineret ved:

$font-path:         '../fonts/IBMPlexSans/' !default;
$image-path:        '../img' !default;
$icons-folder-path: "../img/svg-icons" !default;

I version 10 er der tilføjet en skråstreg / i slutningen af $image-path og $icons-folder-path:

$font-path:         "../fonts/IBMPlexSans/" !default;
$image-path:        "../img/" !default;
$icons-folder-path: "../img/svg-icons/" !default;

Tjek om der er behov i dit projekt for at opdatere disse to variable med /.

Hvis du tidligere har importeret FDS med:

@import 'node_modules/dkfds/src/stylesheets/dkfds-virkdk';

og ønsker at anvende DEPRECATED-filerne, skriv da i stedet:

@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/dkfds-virkdk-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/variables-DEPRECATED';

Første stylesheet er den reelle FDS-styling (i ovenstående eksempel med Virk-temaet), mens andet stylesheet indeholder nogle af de variable, som er blevet fjernet i version 10. Hvis du ikke anvender nogen af disse variable, kan du undlade at importere den sidste fil – ellers bør du forsøge at gøre dig fri af filen inden næste major-version af FDS.

Hvis du har behov for at overskrive variable i FDS, gør da dette, inden du importerer nogen stylesheets. Fx:

$font-path: "../fonts/IBMPlexSans/";
$image-path: "../img/";
$icons-folder-path: "../img/svg-icons/";
$nav-responsive-breakpoint: sm;

@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/dkfds-borgerdk-DEPRECATED';

Hvis du har behov for specifikt at importere variable, funktioner og mixins, kan disse importeres med:

@import 'node_modules/dkfds/src/stylesheets/variables';
@import 'node_modules/dkfds/src/stylesheets/functions';
@import 'node_modules/dkfds/src/stylesheets/mixins';

  Hvis du tidligere har overskrevet eller anvendt dine egne farver med fx variablen $theme-colors, skal disse skrives om til $custom-colors i stedet for. Som eksempel vil den tidligere tematisering til borger.dk

$theme-colors: (
    "borgerdk": (
        100: #44831E,
        200: #3C5C22,
        300: #233614
    ),
    "background": (
        100: #f1f1f1
    )
);

skulle skrives om til

$custom-colors: (
    'borgerdk-100': #44831E, 
    'borgerdk-200': #3C5C22,
    'borgerdk-300': #233614,
    'background-100': #f1f1f1
);

Opdatér JavaScript

Opdatering af js-fil

Dette trin gælder kun, hvis du ønsker at bruge DEPRECATED-filerne.

Hvis du benytter den færdige JavaScript-fil dkfds.min.js, skal den udskiftes med deprecated-versionen.

Hvis du fx tidligere har indlæst og kørt scriptet med 

<script src="dist/js/dkfds.min.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
  DKFDS.init();
});
</script>

skal det nu ændres til

<script src="dist/DEPRECATED/dkfds-DEPRECATED.min.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
  DKFDS.init();
});
</script>

Opdatering af modul

Dette trin gælder kun, hvis du ønsker at bruge DEPRECATED-filerne.

Hvis du tidligere har importeret designsystemet med fx

import * as DKFDS from "dkfds";

så opdatér denne til

import * as DKFDS from "dkfds/dkfds-DEPRECATED";

eller

var DKFDS = require('dkfds/dkfds-DEPRECATED');

afhængigt af dit modulformat.

Modulerne dkfds og dkfds/dkfds-DEPRECATED er defineret i package.json og refererer til filerne ./dist/js/dkfds.min.js og ./dist/DEPRECATED/dkfds-DEPRECATED.min.js, såfremt du har behov for at importere på en anden måde i dit projekt. Hvis du anvender TypeScript, kan det være nødvendigt at oprette en .d.ts-fil i din root-mappe med nedenstående indhold:

declare module 'dkfds/dkfds-DEPRECATED';
declare module 'dkfds';

Opdatér HTML ved problemer med changes og breaking changes

Selvom ovenstående ændringer gør brug af DEPRECATED-filerne, kan der stadig være behov for ændringer i HTML’en. Tjek release notes for en komplet liste af ændringer, du skal være opmærksom på, eksempelvis:

Tjek for eventuelle tilretninger

Efter ovenstående ændringer burde dit projekts website kunne vises uden problemer. Hvis du anvender DEPRECATED-filerne burde du i dette trin altså kunne bygge og køre dit projekt.

Vær dog opmærksom på, at der stadig kan være behov for tilretninger visse steder, fx hvis du udover FDS anvender anden styling eller tidligere har lavet ændringer i koden.

Udskift komponenter

Efter du har taget DEPRECATED-filerne i brug, kan du løbende udskifte dine komponenter med version 10-koden.

Når du udskifter en komponent, så sørg for at udskifte samtlige komponenter af den type i løsningen på én gang, så der fx ikke er to sider med forskellig header eller to forskellige slags tooltips på en side. Dette minimerer også risikoen for konflikter mellem tidligere og ny kode.

Bemærk, at du kun kan udskifte komponenter gradvist med nedenstående guide, hvis du anvender Sass-filerne og JavaScript-moduler. Ellers kan du hente koden fra GitHub og selv justere stylesheets og JavaScript.

Opdatér HTML

Find og kopiér komponentens HTML fra designsystem.dk/komponenter

Opdatér JavaScript

Importér både dkfds og DEPRECATED-versionen, fx med

import * as DKFDS from "dkfds/dkfds-DEPRECATED";
import * as DKFDS_new from "dkfds";

Hvis du noget sted anvender DKFDS.init(), så udskift denne med:

DKFDS.init_limited();

Initialiser derefter specifikt modaler, mobilnavigation, overflow-menuer, faneblade og tooltips (du kan undlade at initialisere komponenter, der ikke anvendes i din løsning). Sørg for at anvende dkfds/dkfds-DEPRECATED til de komponenter, du endnu ikke har opdateret, og dkfds til den komponent, du er ved at opdatere. Se nedenstående tabel for eksempler på komponentinitialiseringer:

Eksempler på initialisering DKFDS from "dkfds/dkfds-DEPRECATED" DKFDS_new from "dkfds"
Initialisering af alle modaler 
const modals = document.querySelectorAll('.fds-modal'); 
for(let c = 0; c < modals.length; c++) {
  new DKFDS.Modal(modals[c]).init();
}
 
const modals = document.querySelectorAll('.fds-modal'); 
for(let c = 0; c < modals.length; c++) {
  new DKFDS_new.Modal(modals[c]).init();
}
Initialisering af mobilnavigation 
new DKFDS.Navigation().init();
 
new DKFDS_new.Navigation().init();
Initialisering af alle overflow-menuer 
const jsSelectorDropdown = document.getElementsByClassName('js-dropdown');
for(let c = 0; c < jsSelectorDropdown.length; c++){
  new DKFDS.Dropdown(jsSelectorDropdown[ c ]).init();
}
 
const jsSelectorDropdown = document.getElementsByClassName('js-dropdown');
for(let c = 0; c < jsSelectorDropdown.length; c++){
  new DKFDS_new.Dropdown(jsSelectorDropdown[ c ]).init();
}
Initialisering af alle faneblade 
const jsSelectorTabnav = document.getElementsByClassName('tabnav');
for(let c = 0; c < jsSelectorTabnav.length; c++){
 new DKFDS.Tabnav(jsSelectorTabnav[ c ]).init();
}
 
const jsSelectorTabnav = document.getElementsByClassName('div.tab-container');
for(let c = 0; c < jsSelectorTabnav.length; c++){
 new DKFDS_new.Tabnav(jsSelectorTabnav[ c ]).init();
}
Initialisering af alle tooltips 
const jsSelectorTooltip = document.getElementsByClassName('js-tooltip');
for(let c = 0; c < jsSelectorTooltip.length; c++){
  new DKFDS.Tooltip(jsSelectorTooltip[ c ]).init();
}
 
const jsSelectorTooltip = document.getElementsByClassName('tooltip-wrapper');
for(let c = 0; c < jsSelectorTooltip.length; c++){
  new DKFDS_new.Tooltip(jsSelectorTooltip[ c ]).init();
}

Opdatér Stylesheet

Fjern linjen

@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/dkfds-borgerdk-DEPRECATED';

og erstat den med linjerne (eksemplet anvender borger.dk-temaet):

@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/borgerdk-base-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/dkfds-base-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/inputs-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/alerts-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/header-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/navigation-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/sidenav-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/overflow-menu-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/table-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/toggle-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/tooltip-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/tabnav-DEPRECATED';
@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/print-DEPRECATED';

Når du så fx vil udskifte dine tooltips, fjern da linjen

@import 'node_modules/dkfds/src/DEPRECATED/stylesheets/components/tooltip-DEPRECATED';

og erstat den med

@import 'node_modules/dkfds/src/stylesheets/components/tooltip';

Bemærk, at filerne header-DEPRECATED, navigation-DEPRECATED og overflow-menu-DEPRECATED skal udskiftes samtidigt, da de er afhængige af hinanden.

Afrunding efter alle komponenter er udskiftet

Efter endt migrering kan du nøjes med at importere stylesheets med

@import 'node_modules/dkfds/src/stylesheets/dkfds-borgerdk';

eller

@import 'node_modules/dkfds/src/stylesheets/dkfds-virkdk';

afhængigt af dit tema.

For JavaScript-koden kan du fjerne eventuelle manuelle initialiseringer og importere med 

import * as DKFDS from "dkfds";

ligesom i version 9.

Fortæl os om din oplevelse med at migrere til version 10

Vi vil meget gerne høre om, hvordan dit projekt er lykkedes med at opgradere til version 10, herunder om denne migreringsguide og DEPRECATED-filerne har været en hjælp. Det kan I fortælle os om i kommentarerne her, hvor I også er velkomne til at stille spørgsmål.