Copy a template inside a DOM node

npm install carbon-copy@0.1.29


Published on


Note that there are other client-side include web components you may want to compare this one with -- e.g. github's include-fragment-element and Juicy's juicy-html or xtal-fetch if carbon-copy doesn't meet your needs.

Copy a template inside a DOM node.

For basic functionality, use the b-c-c.js (or b-c-c.iife.js), element name: b-c-c It is ~1.5 kb minified and gzipped. It's functionality doesn't include the sections starting with "Adding string properties". For the full functionality, use element c-c, which is defined by file c-c.js. carbon-copy.js is an iife version of c-c.js. It is ~2.0 kb minifed and gzipped.


<template id="no-matter">No matter what we
    <slot name="verb1"></slot> (no matter what we <slot name="verb2"></slot>)
<c-c copy from="/no-matter">
    <span slot="verb1">
    <span slot="verb2">

Note the use of the attribute "copy". If this is present, you can modify the value of "from" dynamically, and it will clone the contents of the referenced template (based on id). If an existing template has already been copied, and the from value changes, the existing inner DOM gets hidden via display:none. If the value of "/from" reverts back, that original DOM will be reshown (and the last template hidden). c-c can be used, combined with templ-mount, to provide an alternative to Polymer's iron-pages, with no legacy dependencies.

Templates can come from outside any shadow DOM if the value of "from" starts with a slash. If "from" has no slash, the search for the matching template is done within the shadow DOM of the c-c element. If from starts with "../" then the search is done one level up, etc.

It can also be used in a kind of "Reverse Polish Notation" version of Polymer's dom-if.

Codeless Web Components

c-c generates a custom element on the fly, based on the id of the template. If the template is a simple word, like "mytemplate" the generated custom element will have name c-c-mytemplate. If the id has a dash in it, it will create a custom element with that name (so id's are limited to what is allowed in terms of custom element names).

It uses shadow DOM by default, but you can specify not to use shadow DOM with attribute "noshadow." Doing so will prevent the slot mechanism from working. Hopefully, if template instantiation becomes a thing, it will provide an alternative for this scenario.

So here are the steps to create a web component using c-c:

Step 1. Define a template:

<template id="hello-world">
    Hello, world

Step 2. Register the web component

<c-c from="/hello-world"></c-c>

Step 3. Add your web component to the page


Step 4. Stare into the abyss.

Adding string properties

The template can specify a list of string properties to add to the automatically generated web component:

<template id="pow" data-str-props="name,rank,serial_number">
        <slot name="subjectIs"></slot> 

If the web component's property is set, it will reflect to an attribute with the same name.

Attaching methods to the generated custom element

      <script nomodule data-methods="true">
          fn: function(){
            return this;
          onPropsChange: function(name, oldVal, newVal){
      <template id="beautiful" data-str-props="a,b,c">
          <slot name="subjectIs"></slot> beautiful</div>

All attribute changes call onPropsChange if it is defined.

Adding Object Properties

<template id="beautiful" data-obj-props="d,e">
        <slot name="subjectIs"></slot> beautiful

Object properties also observe attribute changes with the same name as the property, and also calls onPropsChange.

If you set the attribute value for an object property, it will assume the string is JSON, and will parse it.

Changes to object properties fire events with the name "[name of prop]-changed".

Install the Polymer-CLI

First, make sure you have the Polymer CLI and npm (packaged with Node.js) installed. Run npm install to install your element's dependencies, then run polymer serve to serve your element locally.

Viewing Your Element

$ polymer serve

Running Tests

$ polymer test

Your application is already set up to be tested via web-component-tester. Run polymer test to run your application's test suite locally.