⚠️ This element is DEPRECATED, we are developing new element that will replace it

<juicy-composition>

Custom Element that adds given Document Fragment to Shadow DOM

Demo

Check it live!

Install

Install the component using Bower:

$ bower install juicy-composition --save

Or download as ZIP.

Usage

1. Import polyfill, if needed:

   <script src="bower_components/webcomponentsjs/webcomponents.min.js"></script>

2. Import custom element:

   <link rel="import" href="bower_components/juicy-composition/juicy-composition.html">

3. Start using it!

   <template id="my-shadow">
       <h1>Here goes</h1>
       <p>Any HTML structure to be put into `juicy-composition`s shadowRoot</p>
       <p>It may contain slots: <slot name="my-slot">with fallback content</slot></p>
   </template>
   ....
   <juicy-composition>
       <div>My thing</div>
   </juicy-composition>
   <script>
       var juicyComposition = document.querySelector('juicy-composition');
       juicyComposition.composition = document.importNode(document.querySelector('#my-shadow').content, true);
       juicyComposition.stamp();
   </script>

Attributes

Attribute	Options	Default	Description
auto-stamp	Boolean	false	Set to make it stamp Shadow DOM on created and every composition change. It's also a autoStamp property. If set in run-time stamps imediately.

Properties

Attribute	Options	Default	Description
composition	DocumentFragment		Document Fragment to be used to in element's shadowRoot
autoStamp	Boolean	false	See [#Attributes]

Methods

Method	Parameters	Returns	Description
stamp			Call it to imperatively stamp shadow DOM tree. If auto-stamp attribute is set, it's done automatically, when element is created, or composition is changed.

Events

Event	Description
stamped	Triggered once shadow DOM is stamped

Slots

In your composition you can/should use slots to distribute the content within your layout. Conceptually, it matches Shadow DOM V1, which we use if available. However, we still support V0 syntax as well, due to browser & polyfill coverage.

<juicy-composition> adds also few handy features on top of that.

Custom slots

Naturally, thanks to Shadow DOM. If you can/want, you setup everything explicitly

<juicy-composition>
  <div slot="my-slot-name">smth</div>
</juicy-composition>

<template id="composition">
  My composition structure
  ...
  <!-- Shadow DOM V1 -->
  <slot name="my-slot-name"></slot>
  <!-- or in Shadow DOM V0 -->
  <content select="[slot='my-slot-name']"></content>
</template>

Automatic slot names

If for some reason your content does not have slot names, juicy-composition will add it automatically, so you will be able to distribute it easily, even if your content provider cannot do so. We will use child number as a slot-name.

<juicy-composition>
  <div slot="0">...</div><!-- slot name automatically generated -->
  <div slot="provided-name">...</div>
  <div slot="2">...</div><!-- slot name automatically generated -->
</juicy-composition>

Scoped slot names

You can also add name-space to your slot names, if for example you concatenate the content from many providers

<juicy-composition>
  <meta itemprop="juicy-composition-scope" content="fruits"></meta>
    <div slot="fruits-provider-slot-name">apple</div>
    <div>plum</div>
  <meta itemprop="juicy-composition-scope" content="veggies"></meta>
    <div>carrot</div>
</juicy-composition>

Will make slot names look like this

<juicy-composition>
    <meta itemprop="juicy-composition-scope" content="fruits"></meta>
    <div slot="fruits-provider-slot-name">apple</div>
    <div slot="fruits/1">plum</div>
    <meta itemprop="juicy-composition-scope" content="veggies"></meta>
    <div slot="veggies/0">carrot</div>
</juicy-composition>

Automatic slots

In case some content is added dynamically, out you just missed to add some slots for given content we will create slots automatically as well. We will append new <slot> (<content>) element(-s) to the end of the composition.

Force Shadow DOM v0

If for any reason you would like to force this element to use Shadow DOM v0, you can do that by setting the flag before you import this element:

<script>
    window.JuicyComposition = {shadow: 'v0'};
</script>
<link rel="import" href="bower_components/juicy-composition/juicy-composition.html">

Contributing and Development

History

For detailed changelog, check Releases.

License

MIT License