als-layout

v7.0.1

Published

3 months ago

HTML layout constructor with dynamic meta, styles, and scripts

0High
0Medium
0Low

alexsorkin

html layout document meta seo als-document

als-layout Documentation

als-layout is a JavaScript library designed to simplify and enhance the process of constructing and managing web page layouts. It provides a comprehensive API for modifying HTML documents dynamically, allowing developers to add, update, and manipulate various elements such as meta tags, styles, scripts, and more.

The als-layout library is versatile, suitable for:

Building dynamic web pages that require frequent updates to their metadata, styles, or scripts.
Creating templating systems where multiple page layouts share similar structures but differ in content or styling.
Developing web applications that need to dynamically adjust their UI based on user interactions or data changes.

Installation and Import

Install via npm:

npm i als-layout

Node (CommonJS)

const Layout = require('als-layout')

ESM (Module)

import Layout from 'als-layout'

Browser (with bundle)

<script src="layout.js"></script>
<script>
   const layout = new Layout()
</script>

Change Log for V7

⚠ Breaking changes: not backward compatible.

Removed

uglify js and css
status method
end method
minified attribute
propsToClone

Changed

All code is merged into a single file
Added ESM module build (index.mjs)
Added browser bundle (layout.js) that includes als-document and exposes a global Layout

Basic Usage

Initialization

const layout = new Layout();

Adding Elements

const layout = new Layout()
   .viewport() // default: width=device-width, initial-scale=1.0
   .title('Test title') // sets <title> and meta[og:title]
   .favicon('/favicon.png') // adds/updates favicon link
   .keywords(['some', 'keyword']) // updates meta[name=keywords]
   .image('/main-image.png') // sets og:image, twitter:image, twitter:card
   .description('Cool site') // sets meta description tags
   .url('/some', 'http://site.com') // sets canonical + og:url
   .style('body {margin:0; background-color:whitesmoke;}') // appends CSS to style tag
   .link('/styles.css') // adds stylesheet link if not already present
   .script({src:'/app.js'}) // external script
   .script({}, 'console.log("hello world")', false) // inline script in body

// Accessors
layout.body // getter for <body>
layout.head // getter for <head>
layout.html // getter for <html>

// Outputs
layout.rawHtml // raw HTML string
layout.clone   // cloned Layout instance

Cloning

Why Clone?

Cloning creates a complete, independent copy of a Layout instance. Useful when generating multiple pages from a base template.

Example

const newLayout = layout.clone;
newLayout.title('Cloned page');

Efficiency – avoids rebuilding from scratch
Isolation – modifications to clones don’t affect the original
Performance – fast even for larger layouts

Advanced Usage

const raw = /*html*/`<html></html>`
const host = 'http://example.com';

const layout = new Layout(raw, host).lang('fr');
console.log(layout.rawHtml);
// <!DOCTYPE html><html lang="fr"><head></head><body></body></html>

const homePage = layout.clone;
homePage.title('Home page');
homePage.body.innerHTML = `<h1>Home page</h1>`;
console.log(homePage.rawHtml);

const autoReload = layout.clone;
autoReload.script({}, 'setTimeout(() => window.location.reload(), 60000);', false);

API

Constructor

new Layout(html?: string, host?: string)

html: optional HTML string
host: base host for resolving relative URLs

Properties

layout.rawHtml – returns the current document as HTML string
layout.clone – returns a cloned instance

Methods

lang(lang: string) – sets <html lang>
title(title: string) – sets document <title> and Open Graph title
description(description: string) – sets description meta tags
favicon(href: string) – sets or updates favicon
meta(props: object) – sets or updates a <meta> tag
keywords(keywords: string[]) – sets or appends to meta[name=keywords]
viewport(viewport: string = 'width=device-width, initial-scale=1.0') – sets viewport meta
image(image: string) – sets OG and Twitter image meta tags
style(styles: string) – appends CSS styles into <style>
url(url: string, host?: string) – sets canonical + og:url
script(attrs: object = {}, innerHTML: string = '', head: boolean = true) – adds <script> tag
link(href: string, attributes: object = { rel: "stylesheet", type: "text/css" }) – adds stylesheet link

Notes

Version 7 removed status, end, minified, and propsToClone.
Use clone for creating independent layouts instead of extending clone properties.
Use layout.js in the browser for quick setup (exposes global Layout).