MOLECULAR COMPONENTS

Anchor

CLASS

HTML GENERATED BY

Anchor().example()

Class Overview & Defaults

The Anchor Molecular Component class generates Anchor HTML elements to use in a JavaScript ES Module context.

                                
class Anchor extends Html_element {

    constructor (opts = false) { 
        
        ...

        this.defaults = {

            attributes: {

                // Default attributes 
                // specific to Anchor elements
                download : null,
                href : null,
                hreflang : null,
                ping : null,
                referrerpolicy : null,
                rel : null,
                target : null,
                type : null,

                // Inhereted default 
                // Html_element class attributes
                accesskey : null,
                autocapitalize : null,
                class : null,
                contenteditable : null,
                dir : null,
                draggable : null,
                exportparts : null,
                hidden : null,
                id : null,
                inputmode : null,
                is : null,
                itemid : null,
                itemprop : null,
                itemref : null,
                itemscope : null,
                itemtype : null,
                lang : null,
                part : null,
                slot : null,
                spellcheck : null,
                style : null,
                tabindex : null,
                title : null,
                translate : null

            },

            text: ['Default Anchor Link']

        }

        ...

    }

    get_class_defaults () { ... }

    get_merged_options (options) { ... }

    generate (options = false) { ... }

    example () { ... }
    
}

Class Methods

The Anchor Molecular Component comes with four methods. Of the four, the .generate() method will generally be the most used method in applications, while the other three methods are focused more on prototyping, development and/or debugging.

.get_class_defaults()

This method returns a multidimentional JavaScript object with each of the current state class properties represented as key/value pairs.

Arguments: No arguments needed or required
Available: Via any new class instance
Returns: A JS Object

Here's an example of the method in action:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// create a new instance to access the method
console.log( new Anchor().get_class_defaults() );

// alternative ways to get class defaults
let element = new Anchor();
console.log( element.get_class_defaults() );
console.log( element.defaults() );

.get_merged_options( {options} )

Sometimes when working with Molecular Components, we find ourselves wanting to double check the options we are passing into a component if we're are not getting an expected result. That's what the get_merged_options( {options} ) method is for!

The get_merged_options( {options} ) method requires passing in a JavaScript object argument. Then when any passed object properties (keys) match any default properties of the class, the passed values will override the default settings in our class instance, allowing the get_merged_options( {options} ) method to return the merged settings.

Requires: An object argument
Available: Via any new class instance
Returns: A JS Object

Please Note: All Molecular Components use a custom (declaritive) merge process that doesn't work like a typical JavaScript Object.assign() merge, nor a JavaScript spread operator (...) merge, or even a deep merge (like the functionality that's found in libraries/packages like lodash/deepmerge respectively).

Instead, Molecular Components use a merge pattern that works recursively, but respects all of the default nested object heirarchies and data types that Molecular Components depend upon in specific contexts.

And lastly, in the case of JavaScript arrays being used as Molecular Component settings values (common when creating settings with text nodes and inline element nodes in sequence... like a paragraph with a link within it), the custom merge process will override the default settings array entirely, and will not retain any data from the defaults. So basically, arrays of strings and nodes in Molecular Components settings objects are handled just like the traditional JS merge methods.

Here's an example of the method in action:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// setup options for the class
let my_anchor_options = {
    attributes: {
        class: 'text-dark',
        'data-attribute-example': 'Example Value' // property/key strings with hyphens/dashes MUST be quoted in JS!
    },
    text : 'My Anchor Text'
};

// create a new instance of the class
// pass in options
// and get the merged results
console.log( new Anchor().get_merged_options( my_anchor_options ) );

.generate( {options} )

The .generate() method is definitely the bread and butter method of any given Molecular Component class. Use this method to generate markup that applies to the settings and defaults specified in the class's current state, along with any custom parameter settings passed into the method.

All Molecular Component .generate() methods accept an optional (but recommended) argument that should be a JavaScript object with parameter settings for the expected output. This optional object argument needs to therefore conform to the class defaults data schema to change class defaults as expected.

Optional: Accepts an optional argument object
Available: Via any new class instance
Returns: A HTMLAnchorElement

Here's an example of the method in action:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// setup options for the method
let my_anchor_options = {
    attributes: {
        class: 'text-dark',
        href: 'https://obewds.com/',
        'data-attribute-example': 'Example Value' // property/key strings with hyphens/dashes MUST be quoted in JS!
    },
    text: 'My Anchor Text'
};

// generate the markup using options
let a_element = my_anchor.generate( my_anchor_options );

// log/append the element
console.log( a_element );
document.body.appendChild( a_element );

.example()

The .example() method is a quick prototyping method that allows us to call the class for example markup to work with. This comes in handy when trying to work out a new rapid prototyping idea or content flow issue on the fly or in a meeting, etc.

Additionally, Molecular Components .example() methods always have a minimal set of options that are automatically applied when the method is called, to allow devs to quickly get a feel for what the output is and how it's structured (in the case of complex components).

Arguments: No arguments needed or required
Available: Via any new class instance
Returns: A HTMLAnchorElement

Here's an example of the method in action:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// create a new instance to access the method
console.log( new Anchor().example() );

MINI TUTORIAL

Setting Defaults

Once we know what we can customize in any given Molecular Component, we have three basic trajectories from there:

Set defaults at the class level (upon instantiation)
Pass defaults into a .generate() method
Set/Pass defaults at both levels

When we set defaults during class instantiation, we can essentially work with the class in a factory pattern where all deritive output shares the same instantiated settings.

Here's an example:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// setup options for the class
let my_anchor_options = {
    attributes: {
        class: 'text-dark'
    }
};

// log the class defaults
console.log( new Anchor( my_anchor_options ).get_class_defaults() );

When we pass defaults into a .generate() method, we are adding our final settings for our expected markup.

Here's an example:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// create a new instance of the class, and pass in options
let my_anchor = new Anchor();

// setup options for the class
let my_anchor_options = {
    attributes: {
        class: 'text-dark',
        href: 'https://obewds.com/'
    },
    text: 'My Anchor Text'
};

// generate the markup using options
let anchor_element = my_anchor.generate( my_anchor_options );

// log the class defaults
console.log( anchor_element );

When we set defaults at both the class and the markup generation levels, we give our code tons of control and flexibility, while still keeping the code DRY.

Here's an example:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// setup options for the class
let anchors_options = {
    attributes: {
        class: 'text-dark'
    }
}

// create a new instance of the class, and pass in options
let anchors = new Anchor( anchors_options );

// setup options for component(s)

let site_anchor_opts = {
    attributes: {
        href: 'https://obewds.com/'
    },
    text: 'OBE:WDS Website'
};

let molecular_anchor_opts = {
    attributes: {
        href: 'https://obewds.com/molecular-components'
    },
    text: 'Molecular Components'
};

// generate the markup using options
let site_anchor = anchors.generate( my_anchor_options );
let molecular_anchor = anchors.generate( molecular_anchor_opts );

// log the class defaults
console.log( site_anchor );
console.log( molecular_anchor );

MINI TUTORIAL

Extending Molecular Components

Once we've generated a Molecular Component, we can work with it exactly like the output of the vanilla JS .createElement() method. This makes it easy to add important interaction aspects like event listeners!

Here's an example that adds a listener:

                                
// import the module via the html_elements aggregator file
import { Anchor } from './js/modules/html_elements.js';

// generate the component
let my_anchor = new Anchor().example();

// add an event listener
my_anchor.addEventListener('click', (event) => {
    
    event.preventDefault();

    alert('This handler was successfully added to a Molecular Component!');

});

// log and append the modified component
console.log( my_anchor );
document.body.appendChild( my_anchor );

Address Class

Anchor Component