@dylandepass/helix-web-library NPM

Helix Web Library

Set of reusable classes and functions for rendering Helix pages

Status

Installation

Can be added to a helix 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/helix-web-library

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

$ npx helix-web-library install

For more updating, removing, and options, see CLI

Github Release

Download the required bundles from the releases page.

Skypack Release

Helix Web Framework ESM

Helix Web Framework ESM (Minified)

Helix Web Forms ESM

Helix Web Forms ESM (Minified)

What's included?

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

helix-web-framework

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

Usage

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

HelixApp.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 { HelixApp } from 'https://cdn.skypack.dev/@dylandepass/helix-web-library@latest/dist/helix-web-library.esm.min.js';

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

See the API documentation.

helix-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 helix-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 'helix-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 helix-web-library install --force

Remove without installing:

$ npx helix-web-library uninstall

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

$ npx helix-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