als-layout 5.1.0 → 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 = {}) {
@@ -12,7 +13,7 @@ class Layout extends Document {
    }
 
    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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "als-layout",
-  "version": "5.1.0",
+  "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

@@ -17,8 +17,10 @@ npm i als-layout
 ```js
 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
@@ -53,7 +55,7 @@ const Layout = require('als-layout')
   * render switched to als-render
   * updated bug with meta tags after body
 
-
+
 ## Basic Usage
 
 ### Initialization
@@ -100,6 +102,8 @@ Example how it works:
 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?
@@ -119,7 +123,7 @@ const newLayout = layout.clone;
 
 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.
 
-
+
 ## 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:
@@ -168,6 +172,7 @@ In this example:
 
 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
 
 ### Constructor