MOLECULAR COMPONENTS

Address

CLASS

HTML GENERATED BY

Address().example()

Class Overview & Defaults

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

                                
class Address extends Html_element {

    constructor (opts = false) { 
        
        ...

        this.defaults = {

            attributes: {

                // 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 Address Text']

        }

        ...

    }

    get_class_defaults () { ... }

    get_merged_options (options) { ... }

    generate (options = false) { ... }

    br () { ... }

    strong ( textStrOrArr ) { ... }

    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 { Address } from './js/modules/html_elements.js';

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

// alternative ways to get class defaults
let element = new Address();
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 { Address } from './js/modules/html_elements.js';

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

// create a new instance of the class
// pass in options
// and get the merged results
console.log( new Address().get_merged_options( my_address_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 { Address } from './js/modules/html_elements.js';

// setup options for the method
let my_address_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 Address Text'
};

// generate the markup using options
let a_element = my_address.generate( my_address_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 { Address } from './js/modules/html_elements.js';

// create a new instance to access the method
console.log( new Address().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 { Address } from './js/modules/html_elements.js';

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

// log the class defaults
console.log( new Address( my_address_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 { Address } from './js/modules/html_elements.js';

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

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

// generate the markup using options
let address_element = my_address.generate( my_address_options );

// log the class defaults
console.log( address_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 { Address } from './js/modules/html_elements.js';

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

// create a new instance of the class, and pass in options
let addresss = new Address( addresss_options );

// setup options for component(s)

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

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

// generate the markup using options
let site_address = addresss.generate( my_address_options );
let molecular_address = addresss.generate( molecular_address_opts );

// log the class defaults
console.log( site_address );
console.log( molecular_address );

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 { Address } from './js/modules/html_elements.js';

// generate the component
let my_address = new Address().example();

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

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

});

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

Html_element Class

Anchor Class