@dylandepass/helix-web-library v1.13.1
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 (Minified)
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 |
Development
New release are built automatically with every commit to main.
Build
$ npm install
Test
$ npm test
Lint
$ npm run lint
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago