als-layout
Version:
HTML layout constructor with dynamic meta, styles, and scripts
164 lines (124 loc) • 5.08 kB
Markdown
# 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:
```bash
npm i als-layout
```
### Node (CommonJS)
```js
const Layout = require('als-layout')
```
### ESM (Module)
```js
import Layout from 'als-layout'
```
### Browser (with bundle)
```html
<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
```js
const layout = new Layout();
```
### Adding Elements
```js
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
```js
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
```js
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
```js
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`).