be-inclusive (🥰)

be-inclusive enables weaving templates together. It is a close relative to be-imbued. be-imbued pushes DOM elements into other DOM fragments. be-included, instead, pulls in DOM elements from outside into the adorned element, following similar "syntax".

Like other be-enhanced based custom enhancements, be-inclusive can use attributes to enhance the functionality of the element it adorns.

However, the core functionality be-inclusive addresses seems so fundamental and important, that its functionality is already built into the underlying infrastructure supporting custom enhancements and binding from a distance (like trans-rendering supports).

Namely, without any help from this particular package, we can already do:

<div class=stanza id=Opening>
    <div>I don't care if <span itemprop=day1>Monday</span>'s blue</div>
    <div><span itemprop=day2>Tuesday</slot>'s gray and <span itemprop=day3>Wednesday</span> too</div>
    <div><span itemprop=day4>Thursday</span> I don't care about you</div>
    <div id=Friday>
        <div>It's <span itemprop=day5></span> I'm in love</div>
    </div>
</div>

<div class=stanza id=art>
    <div><span itemprop=day1>Monday</span> you can fall apart</div>
    <div><span itemprop=day2>Tuesday</span> <span itemprop=day3>Wednesday</span> break my heart</div>
    <div>Oh, <span itemprop=day4>Thursday</span> doesn't even start</div>
    <template src=#Friday></template>
</div>

... which allows us to reuse the HTML snippet:

<div id=Friday>
    <div>It's <span itemprop=day5></span> I'm in love</div>
</div>

via:

<template src=#Friday></template>

This syntax allows IDE's like VS Code to be able to jump to the source without the need for extensions being installed.

The syntax could also be used to good effect during a build process (SSG) or while server-side rendering, or in a service worker, w3c willing. If used with server-side rendering, the resulting HTML could be significantly heavier (even after factoring in gzip), so it could often be a net loss to do so on the server, rather than on the client. This package contains no such support currently for server-side rendering.

Example 1 - Simplest example with no value added from this package, no slots

Song lyrics can be "deconstructed" and repetitive sections (like the chorus) shared, without a single line of JavaScript (once the MountObserver API is loaded).

Please expand below to see the "code".

Applying DRY to punk lyrics

<a rel=noopener href="https://www.youtube.com/watch?v=tWbrAWmhDwY" target="_blank">Something's gone wrong again</a>

<div class=stanza>
    <div>Tried to find my sock</div>
    <div>No good, it's lost</div>
    <div id=title>Something's gone wrong again</div>
    <div>Need a shave</div>
    <div>Cut myself, need a new blade</div>
    
</div>

<div class=stanza>
    <template src=#title></template> 
    <div id=agains>
        <span id=again>And again</span> <span id=again2>And again, and again, again and something's gone wrong again</span>
        <template src=#title></template>
    </div>
</div>

<div class=stanza>
    <span>Tried to fry an egg</span><br>
    <span>Broke the yolk, no joke</span><br>
    <template src=#title></template> 
    <div>Look at my watch, just to tell the time but the hand's come off mine</div>
    <template src=#title></template> 
    
</div>

<div class=stanza>
    <template src=#title></template> 
    <template src=#agains></template> 

</div>

<div class=stanza>
    <div id="bus">
        <div>Nothing ever happens to people like us</div>
        <div>'Cept we miss the bus, something goes wrong again</div>
        
    </div> 
</div>

<div class=stanza>
    <div>Need a smoke, use my last fifty P.</div>
    <div>But the machine is broke, something's gone wrong again</div>
</div>


<div class=stanza>
    <template src=#agains></template> 
    <template src=#agains></template> 
    
</div>

<div class=stanza>
    <template src=#bus></template> 
    <template src=#agains></template> 
</div>

<div class=stanza>
    <div>
        <span>I turned up early in time for our date</span><br>
        <span>But then you turn up late, something goes wrong again</span><br>
        <span>Need a drink, go to the pub</span><br>
        <span>But the bugger's shut, something goes wrong again</span>
    </div>
</div>

<div class=stanza>
    <div id=title2>Something goes wrong again</div>
    <div>
        <template src=#again></template>
        <div></div>
    </div>
    <div>And again, and again, again and something goes wrong again</div>
    <div>Ah, something goes wrong again</div>
    <template src=#title2></template>
    <template src=#title2></template> 
</div>


<style>
    .stanza{
        padding-top:20px;
        padding-bottom: 20px;
    }
</style>

Value-add of be-inclusive

The built-in inclusiveness that the mount-observer api supports has a fundamental limitation that Shadow DOM slots don't have -- with these "birtual inclusions", all traces of "slots" vanish so as not to conflict in any way with the ShadowDOM support that slots provide.

And more significantly, the mechanism for updating the slots and having them be projected into the ShadowDOM is completely non existent with this solution. That is the primary value-add of this library -- to provide some ability to emulate that feature (if you squint your eyes enough). Basically, we provide for a companion template element to be able to receive children dynamically, and when such children appear, these children get cloned and weaved into the source DOM fragment, based on matching attributes.

be-inclusive in a nutshell

<div itemscope id=love be-inclusive="of #MTWThFSaSu">
    <div class=stanza id=Opening>
        <div>I don't care if <span itemprop=day1></span>'s blue</div>
        <div><span itemprop=day2></slot>'s gray and <span itemprop=day3></span> too</div>
        <div><span itemprop=day4></span> I don't care about you</div>
        <div id=Friday>
            <div>It's <span itemprop=day5></span> I'm in love</div>
        </div>
    </div>

    <div class=stanza id=art>
        <div><span itemprop=day1></span> you can fall apart</div>
        <div><span itemprop=day2></span> <span itemprop=day3></span> break my heart</div>
        <div>Oh, <span itemprop=day4></span> doesn't even start</div>
        <template src=#Friday></template>
    </div>
    ...
</div>
<template id=MTWThFSaSu>
    <span itemprop=day1>Monday</span>
    <span itemprop=day2>Tuesday</span>
    <span itemprop=day3>Wednesday</span>
    <span itemprop=day4>Thursday</span>
    <span itemprop=day5>Friday</span>
    <span itemprop=day6>Saturday</span>
    <span itemprop=day7>Sunday</span>
</template>

What this does:

Searches within the DOM element with id "love" for elements whose attributes match the attributes of the child elements of the template element.
When a match is found, replaces/inserts the children of the target match with the children of the template child.
Monitors for changes to the children of the template with id MTWTFSaSu, and when new children are introduced, merges those into the adorned element.

Finessing the merge

In some cases, we want to "ignore" certain attributes in our match, and "insert" said attribute(s) into matching elements, in addition to weaving in the children. This is done as follows:

<div itemscope id=love>
    ...
    <data value=false itemprop=todayIsFriday>It's Thursday</data>
</div>

...

<template be-inclusive="in #love" be-inclusive-vigilantly>
    <data value=true itemprop=todayIsFriday -i="value">It's Friday</data>
</template>

-i can be a space delimited list of attributes to ignore during the query match / insert during the merge.

The "be-inclusive-vigilantly" means to add a mutation observer to the element with id "love" and watch for any new elements that get added that match the child "selector".

Since "be-inclusive" is a rather lengthy attribute to use as a "stem", a shorter name can be used in less formal environments, where conflicts between different libraries are easy to avoid. Tis package contains a reference that can be used for brevity: 🥰.

<div itemscope id=love>
    ...
    <data value=false itemprop=todayIsFriday>It's Thursday</data>
</div>

...

<template 🥰="in love" 🥰-vigilantly>
    <data value=true itemprop=todayIsFriday -i="value ">It's Friday</data>
</template>

Example 2 in detail

To see the full example described above in detail, please expand below

Tränslåtyng pøst pünk lyriks tø Sweedisλ

<a href="https://www.youtube.com/watch?v=ucX9hVCQT_U" target="_blank">Friday I'm in Love</a>
<button id="changeDays" onclick="updateModel()">Wi not trei a holiday in Sweeden this yer</button>
<script>
    function updateModel(){
        const model = {
            day1: 'måndag', day2: 'tisdag', day3: 'onsdag', day4: 'torsdag', day5: 'fredag',
            day6: 'lördag', day7: 'söndag',
        };
        Object.assign(song.beEnhanced.beInclusive.model, model);
    }
</script>
<template id="Friday">
    <div>It's <slot name=day5></slot> I'm in love</div>
</template>
<template id="Opening">
    <div class=stanza>
        <div>I don't care if <slot name=day1></slot>'s blue</div>
        <div><slot name=day2></slot>'s gray and <slot name=day3></slot> too</div>
        <div><slot name=day4></slot> I don't care about you</div>
        <template src=#Friday>
            <slot slot=day5 name=day5></slot>
        </template> 
    </div>
</template>

<template id="love">
    <template src=#Opening>
        <slot slot=day1 name=day1></slot>
        <slot slot=day2 name=day2></slot>
        <slot slot=day3 name=day3></slot>
        <slot slot=day4 name=day4></slot>
        <slot slot=day5 name=day5></slot>
    </template> 
    <div class="stanza">
        <div><slot name=day1></slot> you can fall apart</div>
        <div><slot name=day2></slot> <slot name=day3></slot> break my heart</div>
        <div>Oh, <slot name=day4></slot> doesn't even start</div>
        <template src=#Friday>
            <slot slot=day5 name=day5></slot>
        </template> 
    </div>
    <div class="stanza">
        <div><slot name=day6></slot> wait</div>
        <div>And <slot name=day7></slot> always comes too late</div>
        <div>But <slot name=day5></slot> never hesitate</div>
    </div>

    <div class="stanza">
        <div>I don't care if <slot name=day1></slot>'s black</div>
        <div><slot name=day2></slot>, <slot name=day3></slot> heart attack</div>
        <div><slot name=day4></slot> never looking back</div>
        <template src=#Friday>
            <slot slot=day5 name=day5></slot>
        </template> 
    </div>
    <div class="stanza">
        <div><slot name=day1></slot> you can hold your head</div>
        <div><slot name=day2></slot>, <slot name=day3></slot> stay in bed</div>
        <div>Or <slot name=day4></slot> watch the walls instead</div>
        <template src=#Friday>
            <slot slot=day5 name=day5></slot>
        </template> 
    </div>
    <div class="stanza">
        <div><slot name=day6></slot> wait</div>
        <div>And <slot name=day7></slot> always comes too late</div>
        <div>But <slot name=day5></slot> never hesitate</div>
    </div>
    <div class="stanza">
        <div>Dressed up to the eyes</div>
        <div>It's a wonderful surprise</div>
        <div>To see your shoes and your spirits rise</div>
        <div>Throwing out your frown</div>
        <div>And just smiling at the sound</div>
        <div>And as sleek as a shriek</div>
        <div>Spinning round and round</div>
        <div>Always take a big bite</div>
        <div>It's such a gorgeous sight</div>
        <div>To see you in the middle of the night</div>
        <div>You can never get enough</div>
        <div>Enough of this stuff</div>
        <div>It's <slot name=day5></slot></div>
        <div>I'm in love</div>
    </div>
    <template src=#Opening>
        <slot slot=day1 name=day1></slot>
        <slot slot=day2 name=day2></slot>
        <slot slot=day3 name=day3></slot>
        <slot slot=day4 name=day4></slot>
        <slot slot=day5 name=day5></slot>
    </template> 
    <div class="stanza">
        <div><slot name=day1></slot> you can fall apart</div>
        <div><slot name=day2></slot>, <slot name=day3></slot> break my heart</div>
        <div><slot name=day4></slot> doesn't even start</div>
        <template src=#Friday>
            <slot slot=day5 name=day5></slot>
        </template> 
    </div>
    <style>
        .stanza{
        padding-top: 20px;
    }
</style>
</template>

<template id=song 
    be-inclusive='{
        "of": "#love",
        "slotMap": {"span": "|"},
        "xform": {
            "| day1": 0,
            "| day2": 0,
            "| day3": 0,
            "| day4": 0,
            "| day5": 0,
            "| day6": 0,
            "| day7": 0
        },
        "initModel": {}
    }'
>
    <span slot=day1 init-val-from="textContent">Monday</span>
    <span slot=day2 init-val-from="textContent">Tuesday</span>
    <span slot=day3 init-val-from="textContent">Wednesday</span>
    <span slot=day4 init-val-from="textContent">Thursday</span>
    <span slot=day5 init-val-from="textContent">Friday</span>
    <span slot=day6 init-val-from="textContent">Saturday</span>
    <span slot=day7 init-val-from="textContent">Sunday</span>
</template>

If you need to pull the value from an element buried deep within the element, specify the path starting with a dot.

For example:

<div slot=myInput init-val-from=.querySelector|input.value>
    <label>
        My Input:
        <input value=initialVal>
    </label>
</div>

The vertical pipe represents an open parenthesis that automatically closes at the end of the expression, or before the next period (".").

The init-val-from attribute is actually optional, and we use as much inference as possible to derive the initial value from the element -- if the element is a microdata element (as is the case here) it applies the same rules -- it assumes the value from the textContent. If the element is an input element, it gets the value based on the type (checkbox, number, etc).

So this works just the same:

<template id=song 
    be-inclusive='{
        "of": "#love",
        "slotMap": {"span": "|"},
        "xform": {
            "| day1": 0,
            "| day2": 0,
            "| day3": 0,
            "| day4": 0,
            "| day5": 0,
            "| day6": 0,
            "| day7": 0
        },
        "initModel": {}
    }'
>
    <span slot=day1>Monday</span>
    <span slot=day2>Tuesday</span>
    <span slot=day3>Wednesday</span>
    <span slot=day4>Thursday</span>
    <span slot=day5>Friday</span>
    <span slot=day6>Saturday</span>
    <span slot=day7>Sunday</span>
</template>

Example 3 - Adventures with the Shadow DOM

In the example below, this package again provides nothing beyond what is supported in the underlying library on which be-inclusive (and other be-enhanced enhancements) rests -- the MountObserver. Here we use slots / Shadow DOM in all its glory, using the platform's ability to update slots as needed, combined with the MountObserver's support for template importing (with ShadowDOM open/closed mode).

Sample Markup

<style>
    div {
        background-color: cornsilk;
    }
</style>
    
<h3><a href="https://www.youtube.com/watch?v=eAfyFTzZDMM" target="_blank">Beautiful</a></h3>
<h4>Christina Aguilera</h4>

<p>Don't look at me</p>
<p>
    <div>Everyday is so wonderful</div>
    <div>Then suddenly</div>
    <div>It's hard to breathe</div>
    <div>Now and then I get insecure</div>
    <div>From all the pain</div>
    <div>I'm so ashamed</div>
</p>
<template id=beautiful>
    <div>
        <slot name=subjectIs></slot> beautiful
    </div>
</template>
<template id=down>
    <div>So don't you bring me down today</div>
</template>
<template id=chorus>
    <div>
        <template src=#beautiful shadowRootModeOnLoad=open></template>
        <span slot=subjectIs>
            <slot name=subjectIs1></slot>
        </span>
    </div>

    
    <div>No matter what they say</div>
    <div prop-pronoun>Words
        <slot name=verb1></slot> bring
        <slot name=pronoun1></slot> down</div>
    <div>Oh no</div>
    <div>
        <template src=#beautiful shadowRootModeOnLoad=open></template>
        <span slot=subjectIs>
            <slot name=subjectIs2></slot>
        </span>
    </div>

    <div>In every single way</div>
    <div>Yes words
        <slot name=verb2></slot> bring
        <slot name=pronoun2></slot> down
    </div>
    <div>Oh no</div>
    
    <template src=#down></template>
    </template>
    
    <div class=chorus>
    <template src=#chorus shadowRootModeOnLoad=open></template>
    <span slot=verb1>can't</span>
    <span slot=verb2>can't</span>
    <span slot=pronoun1>me</span>
    <span slot=pronoun2>me</span>
    <span slot=subjectIs1>I am</span>
    <span slot=subjectIs2>I am</span>
    </div>

    <p>
    <div>To all your friends you're delirious</div>
    <div>So consumed</div>
    <div>In all your doom, ooh</div>
    <div>Trying hard to fill the emptiness</div>
    <div>The pieces gone</div>
    <div>Left the puzzle undone</div>
    <div>Ain't that the way it is</div>
</p>

<p>
    <div class=chorus>
        <template src=#chorus shadowRootModeOnLoad=open></template>
        <span slot=verb1>can't</span>
        <span slot=verb2>can't</span>
        <span slot=pronoun1>you</span>
        <span slot=pronoun2>you</span>
        <span slot=subjectIs1>You are</span>
        <span slot=subjectIs2>You are</span>
    </div>
</p>
<br>
<template id=no-matter>
    No matter what we <slot name=verb1></slot> (no matter what we <slot name=verb2></slot>)
</template>
<div>
    <template src=#no-matter shadowRootModeOnLoad=open></template>
    <span slot=verb1>do</span>
    <span slot=verb2>do</span>
</div>
<div>
    <template src=#no-matter shadowRootModeOnLoad=open></template>
    <span slot=verb1>say</span>
    <span slot=verb2>say</span>
</div>

<div>We're the song inside the tune (yeah, oh yeah)</div>
<div>Full of beautiful mistakes</div>
<p>
    <div>And everywhere we go (and everywhere we go)</div>
    <div>The sun will always shine (the sun will always, always, shine)</div>
    <div>And tomorrow we might awake</div>
    <div>On the other side</div>
</p>

<p>
    <div class=chorus>
        <template src=#chorus shadowRootModeOnLoad=open></template>
        <span slot=verb1>won't</span>
        <span slot=verb2>can't</span>
        <span slot=pronoun1>us</span>
        <span slot=pronoun2>us</span>
        <span slot=subjectIs1>We are</span>
        <span slot=subjectIs2>We are</span>
    </div>
</p>

<p>
    <div>Oh, oh</div>
    <div>Don't you bring me down today</div>
    <div>Don't you bring me down, ooh</div>
    <div>Today</div>
</p>

Example 4 - Applying DRY to the song of the material universe [TODO]

The Periodic Table Codepen has lots of repetitive, periodic DOM in it. Performance can actually be improved over server-rendering all ths HTML by utilizing templates for the purpose of reducing repeating HTML (yes, it even improves over HTML with gzip in place).

In order to support this, some features have been added to be-inclusive -- specifying arrays of includes, and prepending when needed.

The markup can be found here.

[TODO] beatify

[WIP] share templates

Viewing Demos Locally

Install git.
Fork/clone this repo.
Install node.
Open command window to folder where you cloned this repo.
npm install
npm run serve
Open http://localhost:8000/demo/dev in a modern browser.

Name		Name	Last commit message	Last commit date
Latest commit History 248 Commits
.github/workflows		.github/workflows
.vscode		.vscode
demo		demo
legacy		legacy
tests		tests
ts-refs		ts-refs
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
be-inclusive.js		be-inclusive.js
emc.js		emc.js
imports.html		imports.html
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

be-inclusive (🥰)

Example 1 - Simplest example with no value added from this package, no slots

Value-add of be-inclusive

be-inclusive in a nutshell

Example 2 in detail

Example 3 - Adventures with the Shadow DOM

Example 4 - Applying DRY to the song of the material universe [TODO]

Viewing Demos Locally

About

Uh oh!

Releases

Packages

Uh oh!

Languages

License

bahrus/be-inclusive

Folders and files

Latest commit

History

Repository files navigation

be-inclusive (🥰)

Example 1 - Simplest example with no value added from this package, no slots

Value-add of be-inclusive

be-inclusive in a nutshell

Example 2 in detail

Example 3 - Adventures with the Shadow DOM

Example 4 - Applying DRY to the song of the material universe [TODO]

Viewing Demos Locally

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages