als-layout 5.0.1 → 5.2.0

package/docs/#.md

@@ -0,0 +1,19 @@
+# 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 Adding
+To use the `als-layout` library in your project, you can install it via npm and then include it in your JavaScript files:
+
+```bash
+npm i als-layout
+```
+
+```js
+const Layout = require('als-layout')
+```

package/docs/0-change-log.md

@@ -0,0 +1,37 @@
+## Change Log
+* V5.2.0
+  * options object on clone, cloned too (remove the reference and deep cloning the object)
+* V5.1.0
+  * status and end methods removed
+  * status and end methods added to als-view
+* V5.0.0
+  * constructor changed
+    * options object parameter instead separated parameters
+    * options.logger
+  * bugs fixed
+  * some refactoring
+  * minifiying error catching
+  * status and end methods added
+* V4.2.0
+  * link method changed
+    * `link(href, attributes = { rel: "stylesheet", type: "text/css" })`
+  * no version method
+    * no version parameter in image, link,script
+  * script
+    * script in footer added one after other in right order
+
+* V4.1.0
+  * Render removed
+
+* V4.0.0
+  * All code rebuilded and refactored
+  * No als-simple-css for style
+  * No charset method
+  * minifying for style and inner scripts
+  * updated render version
+  * render as element's method instead layout's method
+
+* V3.0.0
+  * render switched to als-render
+  * updated bug with meta tags after body
+

package/docs/1-basic-usage.md

@@ -0,0 +1,47 @@
+## Basic Usage
+
+### Initialization
+To start using `als-layout`, you first need to create a new instance of `Layout`. This instance will serve as the foundation for building and modifying your web page.
+
+```js
+const Layout = require('als-layout');
+const layout = new Layout();
+```
+
+### Adding Different Elements
+Once you have your `Layout` instance, you can easily add or modify various elements of your web page. Here are some examples of how you can use the library to customize your layout:
+
+```js
+const layout = new Layout()
+   .viewport() // default width=device-width, initial-scale=1.0
+   .title('Test title') // adding/updating title and meta[og:title]
+   .favicon('/favicon.png') // adding/updating link[rel=icon][type=image/x-icon] with new href
+   .keywords(['some', 'keyword']) // adding/updating meta[name=keywords]. not adding existing keywords
+   .image('/main-image.png', '1.5') // adding/updating meta - og:image, twitter:image, twitter:card
+   .description('Cool site') // adding/updating meta og:description, twitter:description, and description tag
+   .url('/some', 'http://site.com') // adding/updating meta[og:url] and link[rel="canonical"]
+   .style('body {margin:0; background-color:whitesmoke;}', true) // adding css styles to existing/new style tag. Second parameter is minified (default=false).
+   .link('/styles.css') // adding link[rel=stylesheet] if such href not exists
+   .script({src:'/app.js'}, '', true) // set script with src to head if such src not exists
+   .script({}, 'console.log("hello world")', false) // set script with script code to footer
+
+// Accessors for document parts
+layout.body // getter for body element (if not exists, created)
+layout.head // getter for head element (if not exists, created)
+layout.html // getter for html Element (if not exists, created)
+
+// Outputs
+layout.rawHtml // raw HTML of the document
+layout.clone // creates a new layout object clone for current object
+```
+
+### onload
+
+By adding onload attribute, you can run scripts for each element after dom content has loaded. 
+
+Example how it works:
+```js
+const layout = new Layout().viewport().title('On load').onload()
+layout.body.innerHTML = /*html*/`<div onload="this.innerHTML = 'new content'">original content</div>`
+```
+

package/docs/2-cloning.md

@@ -0,0 +1,19 @@
+## Cloning Functionality
+
+### What is Cloning and Why is it Necessary?
+Cloning in the `als-layout` library refers to creating a complete, independent copy of the existing `Layout` instance. This functionality is crucial when you need to generate multiple pages or versions of a page from a single base layout without affecting the original setup.
+
+### How to Use Cloning
+To clone a `Layout` instance, simply use the `clone` method. This method creates a new `Layout` instance with the same properties and settings as the original, allowing for independent modifications without interference.
+
+```js
+const newLayout = layout.clone;
+```
+
+### Benefits of Cloning
+- **Efficiency:** Cloning is highly efficient, especially for creating pages with similar structures but different content or styles. It avoids the overhead of reinitializing and reconfiguring a new `Layout` instance from scratch.
+- **Speed:** Cloning is fast, typically taking less than 20ms even for large pages. This makes it ideal for high-performance web applications that need to dynamically generate content.
+- **Isolation:** Changes made to a cloned `Layout` do not affect the original, ensuring that each instance can be modified independently based on specific requirements.
+
+Cloning is particularly useful in scenarios where templates or base layouts are used repeatedly with slight variations, providing a robust and scalable solution for web page generation.
+

package/docs/3-advanced-usage.md

@@ -0,0 +1,48 @@
+## Advanced Usage
+
+The `als-layout` library allows for sophisticated manipulation of web page layouts, providing robust tools for creating dynamic and complex web pages. Below is an advanced example demonstrating various capabilities of the library:
+
+```js
+const Layout = require('als-layout')
+
+// Starting with a basic HTML template and specifying the host for URL methods
+const raw = /*html*/`<html></html>`
+const host = 'http://example.com';
+const options = {
+   logger,
+   host, 
+   minified=false
+}
+const layout = new Layout(raw, options).lang('fr')
+console.log(layout.rawHtml)
+// <!DOCTYPE html><html lang="fr"><head></p></head><body></body></html>
+
+// Cloning the initial layout to create a specialized page
+const homePage = layout.clone
+homeAutoReload = layout.clone
+homePage.title('Home page')
+homePage.body.innerHTML = /*html*/`<h1>Home page</h1>`
+console.log(homePage.rawHtml)
+// <!DOCTYPE html><html lang="fr"><head><title>Home page</title><meta property="og:title" content="Home page"></head><body><h1>Home page</h1></body></html>
+
+// Adding script that reloads the page every minute
+homeAutoReload.script({}, 'setTimeout(function() { window.location.reload(); }, 60000);', false)
+console.log(homeAutoReload.rawHtml)
+// <!DOCTYPE html><html lang="fr"><head><title>Automatic Reload Page</title><meta property="og:title" content="Automatic Reload Page"></head><body><script>setTimeout(function() { window.location.reload(); }, 60000);</script></body></html>
+
+// Demonstrating dynamic stylesheet linkage with versioning
+homePage.link('/css/main.css')
+console.log(homePage.rawHtml)
+// Includes link to the stylesheet with version parameter to ensure fresh cache
+```
+
+In this example:
+
+- We start with a basic HTML template and use the `lang` method to set the language.
+- We use the `clone` method to create two versions of the base layout: one for the home page and another that automatically reloads every minute.
+- We manipulate the `body` of the `homePage` to include custom HTML.
+- We add a script to `homeAutoReload` that sets up an automatic page reload, showcasing how to insert JavaScript dynamically.
+- We dynamically add a versioned link to a stylesheet in the `homePage`, demonstrating control over caching and resource management.
+
+This advanced example illustrates how `als-layout` can be used to handle complex scenarios and requirements in web development, enhancing the flexibility and power at your disposal.
+

package/docs/4-api.md

@@ -0,0 +1,88 @@
+## API
+
+### Constructor
+
+#### `new Layout(html: string, options: object)`
+
+Creates a new `Layout` instance.
+
+- **html**: The initial HTML document string.
+- **options**: Configuration options for the layout instance.
+  - **minified**: Boolean (default: `false`). Determines if inline CSS and JavaScript should be minified.
+  - **logger**: Function (default: `console`). Function for errors in minifiying and url method.
+  - **host**:  String (defult:`undefined`). String for url method. 
+
+
+### Properties
+
+#### `layout.rawHtml`
+
+Returns the inner HTML of the document.
+
+#### `layout.clone`
+
+Creates a clone of the current layout instance, preserving `options`.
+
+### Methods
+
+#### `lang(lang: string): this`
+
+Sets the `lang` attribute on the `<html>` element.
+
+#### `onload(): this`
+
+Adds an `onload` script to the document. If called multiple times, the script is only added once.
+
+#### `title(title: string): this`
+
+Sets the document title and creates an Open Graph title meta tag.
+
+#### `description(description: string): this`
+
+Adds description meta tags for SEO and social platforms.
+
+#### `favicon(href: string): this`
+
+Sets or updates the favicon URL.
+
+#### `meta(props: object): this`
+
+Adds or updates a `<meta>` tag with specified attributes.
+
+- **props**: An object where each key-value pair corresponds to a meta attribute.
+
+#### `keywords(keywords: array): this`
+
+Sets or appends keywords in the `content` attribute of a `<meta name="keywords">` tag.
+
+#### `viewport(viewport: string): this`
+
+Sets the viewport meta tag. Default: `width=device-width, initial-scale=1.0`.
+
+#### `image(image: string): this`
+
+Sets meta tags for Open Graph and Twitter cards for an image.
+
+#### `style(styles: string, minified: boolean = this.options.minified): this`
+
+Adds inline CSS to the document. If `minified` is true, the CSS is minified.
+
+- **styles**: CSS string.
+- **minified**: Boolean (optional).
+
+#### `url(url: string, host: string = this.URL): this`
+
+Sets the canonical URL and Open Graph URL meta tags.
+
+#### `script(attrs: object = {}, innerHTML: string = '', head: boolean = true, minified: boolean = this.options.minified): this`
+
+Adds a `<script>` tag to the document.
+
+- **attrs**: Attributes for the `<script>` tag.
+- **innerHTML**: Inline JavaScript (optional).
+- **head**: Boolean (default: `true`). If `false`, the script is added to `<body>`.
+- **minified**: Boolean. If true, inline JavaScript is minified.
+
+#### `link(href: string, attributes: object = { rel: "stylesheet", type: "text/css" }): this`
+
+Adds a `<link>` tag for external stylesheets.

package/lib/layout.js

@@ -2,6 +2,7 @@ const { Document, SingleNode } = require('als-document');
 const script = require('./script');
 const style = require('./style');
 const onloadScript = require('./onload');
+const deepClone = require('als-deep-clone')
 
 class Layout extends Document {
    constructor(html, options = {}) {
@@ -9,11 +10,10 @@ class Layout extends Document {
       this.options = options
       this.logger = options.logger || console
       this.root = this.html
-      this.statusCode = 200
    }
 
    get rawHtml() { return this.innerHTML }
-   get clone() { return new this.constructor(new Document(this, this.URL), this.options) }
+   get clone() { return new this.constructor(new Document(this, this.URL), deepClone(this.options)) }
    lang(lang) { this.html.setAttribute('lang', lang); return this }
 
    onload() {
@@ -113,17 +113,6 @@ class Layout extends Document {
       this.head.insert(2, linkElement)
       return this
    }
-
-   status(statusCode) { this.statusCode = statusCode; return this }
-
-   end(res,statusCode = this.statusCode, rawHtml = this.rawHtml) {
-      res.writeHead(statusCode);
-      if (res.set) res.set('Content-Type', 'text/html') // for Express
-      else res.setHeader('Content-Type', 'text/html') // for http
-      res.end(rawHtml)
-      return this
-   }
-
 }
 
 module.exports = Layout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "als-layout",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "main": "index.js",
   "scripts": {
     "test": "node --test --experimental-test-coverage",
@@ -11,6 +11,7 @@
   "license": "MIT",
   "description": "Html layout constructor",
   "dependencies": {
+    "als-deep-clone": "^1.0.0",
     "als-document": "^1.4.0",
     "uglify-js": "^3.19.2",
     "uglifycss": "^0.0.29"

package/readme.md

@@ -19,6 +19,11 @@ const Layout = require('als-layout')
 ```
 
 ## Change Log
+* V5.2.0
+  * options object on clone, cloned too (remove the reference and deep cloning the object)
+* V5.1.0
+  * status and end methods removed
+  * status and end methods added to als-view
 * V5.0.0
   * constructor changed
     * options object parameter instead separated parameters
@@ -77,8 +82,6 @@ const layout = new Layout()
    .link('/styles.css') // adding link[rel=stylesheet] if such href not exists
    .script({src:'/app.js'}, '', true) // set script with src to head if such src not exists
    .script({}, 'console.log("hello world")', false) // set script with script code to footer
-   .status(200)
-   .end(response);
 
 // Accessors for document parts
 layout.body // getter for body element (if not exists, created)
@@ -98,7 +101,9 @@ Example how it works:
 ```js
 const layout = new Layout().viewport().title('On load').onload()
 layout.body.innerHTML = /*html*/`<div onload="this.innerHTML = 'new content'">original content</div>`
-```
+```
+
+
 ## Cloning Functionality
 
 ### What is Cloning and Why is it Necessary?
@@ -166,6 +171,7 @@ In this example:
 - We dynamically add a versioned link to a stylesheet in the `homePage`, demonstrating control over caching and resource management.
 
 This advanced example illustrates how `als-layout` can be used to handle complex scenarios and requirements in web development, enhancing the flexibility and power at your disposal.
+
 
 ## API
 
@@ -255,11 +261,3 @@ Adds a `<script>` tag to the document.
 #### `link(href: string, attributes: object = { rel: "stylesheet", type: "text/css" }): this`
 
 Adds a `<link>` tag for external stylesheets.
-
-#### `status(statusCode: number): this`
-
-Sets the HTTP status code for the response.
-
-#### `end(res: object): this`
-
-Sends the HTML response with the specified `statusCode` and sets `Content-Type` to `text/html`.