@dylandepass/franklin-web-library

Franklin Web Library

Set of reusable classes and functions for rendering Franklin pages

Status

Installation

Can be added to a franklin project either with by downloading the bundles directly from the releases page on github, using a cloud bundler like skypack or using npm (requires a build step).

NPM

$ npm install @dylandepass/franklin-web-library

After installing, the library bundle can be added to scripts/ using the CLI:

$ npx franklin-web-library install

For more updating, removing, and options, see CLI

Github Release

Download the required bundles from the releases page.

Skypack Release

Franklin Web Framework ESM

Franklin Web Framework ESM (Minified)

Franklin Web Forms ESM

Franklin Web Forms ESM (Minified)

What's included?

The two scripts included are franklin-web-framework and franklin-web-forms.

franklin-web-framework

Includes a helper class that abstracts the decoration and loading of a franklin page. This class provides various hooks and overrides for customizating the franklin decoration and loading process.

Usage

import { Franklin } from 'https://cdn.skypack.dev/@dylandepass/franklin-web-library@latest/dist/franklin-web-library.esm.min.js';

Franklin.init({
  rumEnabled: true,
  rumGeneration: 'project-1',
  productionDomains: ['acme.com'],
  lcpBlocks: ['hero'],
})
  .withLoadEager(loadEager)
  .withBuildAutoBlocks((main) => {
    try {
      buildHeroBlock(main);
    } catch (error) {
      // eslint-disable-next-line no-console
      console.error('Auto Blocking failed', error);
    }
  })
  .decorate();

Builder Options

Builder configuration options

Name	Description	Example	Default
rumEnabled	Enable RUM collection?	true	false
rumGeneration	RUM generation id	'project-1'	undefined
productionDomains	A list of productions domains.	['acme.com']	[]
lcpBlocks	List of blocks classes to treat as LCP	['hero']	[]
autoAppear	Should we set the appear class on the body after LCP load? If false then client must add the appear class (document.querySelector('body').classList.add('appear');)	true	true
blocksSelector	The CSS selector used to query blocks	':scope > div > div'	'div.section > div > div'
lazyStyles	Should lazy styles be loaded (/styles/lazy-styles.css)	true	false
favIcon	Path to favIcon, supports both .icon and .svg	/styles/icon.ico	/styles/icon.svg
iconsPath	Path to icons folder	/somepath	/icons
enableBlockLoader	Should the block loader run? In some cases we don't want it to (i.e storybook)	false	true
loadHeader	Should the header be loaded	false	true
loadFooter	Should the footer be loaded	false	true

Lifecycle hooks

These lifecycle hooks can be used to tie custom logic into the page loading flow.

Hooks	Description
withLoadEager	Called just after main is decorated and LCP is loaded
withDecorateMain	Called after block decoration and before waitForLCP.
withLoadLazy	Called just after all blocks have been loaded (js/css)
withLoadDelayed	Called after the page load lifecycle has completed

Decoration/Loading overrides

If you need to customize the page decoration the following overrides are available.

Hooks	Description
withBuildAutoBlocks	Add any logic required to build auto blocks here
withDecorateSections	Overrides the default decorate sections logic
withDecorateBlock	Overrides the default decorate block logic
withLoadHeader	Overrides the default load header logic
withLoadFooter	Overrides the default load footer logic
withDecorateIcons	Overrides the default decorate icons logic
withDecorateButtons	Overrides the default decorate buttons logic

For example, if you want a different decoration for your buttons you can use withDecorateButtons to override the default behaviour.

import { Franklin } from 'https://cdn.skypack.dev/@dylandepass/franklin-web-library@latest/dist/franklin-web-library.esm.min.js';

Franklin.init({
  ...
})
  ...
  .withDecorateButtons((main) => {
    // custom button decoration code
  })
  .decorate();

See the API documentation.

franklin-web-forms

This is a pre-alpha and and mainly just an experiment.. Not meant for production use

Creates an HTML form based on a form definiton defined in a sheet. The form definition should be contained in the franklin-default sheet. No assumptions are made on the styling of the form as is left up to the developer to style the form markup.

import { createForm } from 'franklin-web-framework.esm.min.js';

export default async function decorate(block) {
  const form = block.querySelector('a[href$=".json"]');
  if (form) {
    form.replaceWith(await createForm(form.href));
  }
}

Supported form field definitions

Name	Description	Example
Field	The name of the field, will be set in the class name.	customerName
Label	The field label	Customer Name
Placeholder	Placeholder text for the field	Acme corp
Type	The field type. Currently supports text-field, heading, select, text-area	text-area
Format	The input type of the field.	password
Mandatory	Is this a required field?	x
Options	If field type is select, options are set here	Don't know, Yes, No
Rules	Basic rules enginem, currently only supports visible	{"type": "visible", "condition": {"key": "cms", "operator": "eq", "value": "AEM Sites"}}
Extra	Redirect path after submission	/thank-you

CLI

Examples

Update/reinstall (overwrites existing file):

$ npx franklin-web-library install --force

Remove without installing:

$ npx franklin-web-library uninstall

Install to a different path (must be inside current working directory):

$ npx franklin-web-library install --dir=./libs

Install Options

Option	Shorthand	Description	Default
--dir	-d	Install directory	-d=./scripts
--force	-f	Force overwrite existing, upgrade by deleting existing library at path.
--minify	-m	Install minified library

Development

New release are built automatically with every commit to main.

Build

$ npm install

Test

$ npm test

Lint

$ npm run lint