Franklin Storybook Addon
A storybook addon for working with Franklin projects.
Configuring your franklin project with Storybook
- Install storybook html
npx storybook init --type html
- Install the Franklin storybook addon
npm install -D @dylandepass/franklin-storybook-addon
- Update
./storybook/main.js
Here we are telling storybook to expose the content in ./scripts
, ./styles
and ./icons
as static directies in storybook.
This will allow us to use styles.css
and other dependacies in our stories. We are also registering the franklin-storybook-addon
with storybook.
module.exports = {
"stories": [
"../blocks/**/*.stories.js",
"../blocks/**/*.stories.jsx",
"../blocks/**/*.stories.mdx",
],
"addons": [
"@storybook/addon-essentials",
"@dylandepass/franklin-storybook-addon"
],
"framework": "@storybook/html",
"staticDirs": [
{ from: "../scripts", to: "/scripts" },
{ from: "../styles", to: "/styles" },
{ from: "../icons", to: "/icons" }
],
};
- Delete the sample storybook content
rm -rf ./stories
- Tell storybook to load
styles.css
Create the file preview-head.html
inside of ./.storybook
.
Add a link to styles.css
<link rel="stylesheet" href="./styles/styles.css">
Create stories content to load in storybook
-
In the root of the site content store (gdrive or sharepoint). Create a folder called
storybook
. -
Inside the
storybook
folder create a document for a block you want to use within storybook. I.E cards -
Paste an example cards content block inside the document and preview it.
-
In order for storybook to be able to load the example block we need to set a wildcard CORS policy on it.
- Create a sheet at in the content store at
/.helix/headers
if one doesn't exist.
- Create a sheet at in the content store at
-
Add the following rows
url key value /storybook/** access-control-allow-origin *
Create the story
-
Create a stories file for each block you want to use with storybook. I recommend putting the stories file in the same folder as the block code. (I.E blocks/cards/cards.stories.js)
Here is an stories file for a cards block.
import { FranklinTemplate } from '@dylandepass/franklin-storybook-addon'; import { loadPage } from '../../scripts/scripts.js'; import decorate from './cards.js'; import style from './cards.css'; export const Cards = (args, context) => FranklinTemplate(loadPage, args, context, decorate); Cards.parameters = { path: '/storybook/cards.plain.html', selector: '.cards', index: 0, }; Cards.storyName = 'Cards'; /** * Default Config */ export default { title: 'Cards', parameters: { docs: { description: { component: 'A block to display cards', }, }, }, argTypes: { blockClasses: { options: ['light', 'dark'], control: { type: 'radio' }, table: { category: 'Block', }, }, }, };
-
Setup
argTypes
The addon supports two types of optional argTypes,
sectionClasses
andblockClasses
. The option can either be mutually exclusive or not. If you want to support multiple classes at the same time you can change the control type fromradio
tocheck
.Section Classes
Any classes added to
sectionClasses
will be added to the section element as well as added get added tosection-metadata
in the content tab.Block Classes
Any classes added to
blockClasses
will be added to the block element and block heading in the content tab. -
Modify
scripts.js
The addon requires access to
loadPage()
method fromscripts.js
in order to decorate the franklin blocks correctly. You will need to updatescripts.js
to export theloadPage()
method and also wrap the call toloadPage
in a check to prevent it from being called when running in storybook.export async function loadPage() { console.log('loading page'); await loadEager(document); await loadLazy(document); loadDelayed(); } if(!window.__STORYBOOK_PREVIEW__) { loadPage(); }
Optionally, you may also want to wrap
loadBlocks
,loadHeader
andloadFooter
inloadLazy
in a check as well to prevent them from attemping to load in storybook. The franklin stoybook addon will takcare of decorating the block.if (!window.__STORYBOOK_PREVIEW__) { await loadBlocks(main); } if(!window.__STORYBOOK_PREVIEW__) { loadHeader(doc.querySelector('header')); loadFooter(doc.querySelector('footer')); }
Development scripts
-
yarn start
runs babel in watch mode and starts Storybook -
yarn build
build and package your addon code