https://github.com/bahrus/carbon-copy
Copy an HTML template into a DOM node.
https://github.com/bahrus/carbon-copy
custom-element custom-elements customelement referenced-template shadow-dom template-instantiation webcomponent webcomponents
Last synced: about 2 months ago
JSON representation
Copy an HTML template into a DOM node.
- Host: GitHub
- URL: https://github.com/bahrus/carbon-copy
- Owner: bahrus
- License: mit
- Created: 2017-08-06T16:45:28.000Z (almost 8 years ago)
- Default Branch: baseline
- Last Pushed: 2023-03-04T02:40:48.000Z (about 2 years ago)
- Last Synced: 2024-10-03T02:15:42.425Z (8 months ago)
- Topics: custom-element, custom-elements, customelement, referenced-template, shadow-dom, template-instantiation, webcomponent, webcomponents
- Language: TypeScript
- Size: 580 KB
- Stars: 2
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.webcomponents.org/element/bahrus/carbon-copy)
b-c-c size:
c-c size:
# \
**NB:** These components work best in a [futuristic](https://github.com/bahrus/templ-mount) HTML-friendly world. In the meantime, they may work best with the help of [one](https://www.npmjs.com/package/html-include-element) [of](https://www.webcomponents.org/element/@github/include-fragment-element) [these](https://www.npmjs.com/package/@vanillawc/wc-include).
Copy a template inside a DOM node.
## b-c-c
For basic functionality, reference carbon-copy/b-c-c.js and use element name: b-c-c. It just clones the source template into the shadowDOM or innerHTML of the element (depending on the value of the noshadow attribute).
Syntax:
```html
No matter what we
(no matter what we )
...
do
say
```
Note the use of the attribute "copy". This attribute/property makes the tag more readable, but also acts as an "if" logical operator. If attribute/property "copy" is present/true, only then will it clone the contents of the referenced template (based on id).
The copy property is reflected via the data-copy-is attribute ("true"/"false"),except on browsers that support custom pseudostate. This attribute/state can be used for styling.
In short, b-c-c can be used as a kind of basic "Reverse Polish Notation" version of Polymer's [dom-if](https://polymer-library.polymer-project.org/2.0/docs/devguide/templates#dom-if).
If the attribute "from" changes, b-c-c will blow away what was there before, and clone in the new template. [c-c, on the other hand, will preserve the existing inner (Shadow) DOM, and make it get hidden via display:none. If the value of "/from" reverts back, that original DOM will be re-rendered (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. Subject to change]
Templates can come from outside any shadow DOM if the value of "from" starts with a slash. If "from" starts with "./", the search for the matching template is done within the shadow DOM of the (b-)c-c element (or outside any ShadowDOM if the (b-)c-c element is outside any ShadowDOM). If from starts with "../" then the search is done one level up, etc.
At each stage, if a host web component is hosting the shadowDOM, and it has a property with the list case of the id, then that property is assumed to reference an HTMLTemplateElement. This allows hosting web components to inject the property template dynamically.
By default, b-c-c will copy in the referenced template into a Shadow DOM snippet. However, if you prefer it copy straight into innerHTML, add attribute / property "noshadow." Doing so will, of course, eliminate the slot mechanism from functioning. Hopefully, if template instantiation becomes a thing, that will provide an alternative for this scenario, in terms of declarative support for dynamic content.
In the meantime / in addition, b-c-c supports two additional properties for adjusting the content dynamically:
If toBeTransformed/to-be-transformed property/attribute is set, then b-c-c won't append the clone, until a trans-render context object is passed in to property trContext.
## Templatize a materialized DOM element
b-c-c can not only be used to instantiate a template (repeatedly), but also an already materialized DOM element. It does this by creating a template copy of that DOM element first, and then cloning. Subsequent copies from the same DOM element will derive from the template copy (so if the DOM element mutates, copies won't see that).
[b-c-c demo](https://jsfiddle.net/bahrus/t0n9eLuo/2/)
## Sample Markup of b-c-c
Markup
```html
Document
div {
background-color: cornsilk;
}
Beautiful
Christina Aguilera
:host {
background-color: blanchedalmond;
}
No matter what we (no matter what we )
div {
background-color: burlywood;
}
beautiful
So don't you bring me down today
div {
background-color: paleturquoise;
}
No matter what they say
Words
bring
down
Oh no
In every single way
Yes words
bring
down
Oh no
Don't look at me
Everyday is so wonderful
Then suddenly
It's hard to breathe
Now and then I get insecure
From all the pain
I'm so ashamed
can't
can't
me
me
I am
I am
To all your friends you're delirious
So consumed
In all your doom, ooh
Trying hard to fill the emptiness
The pieces gone
Left the puzzle undone
Ain't that the way it is
can't
can't
you
you
You are
You are
do
do
say
say
We're the song inside the tune (yeah, oh yeah)
Full of beautiful mistakes
And everywhere we go (and everywhere we go)
The sun will always shine (the sun will always, always, shine)
And tomorrow we might awake
On the other side
won't
can't
us
us
We are
We are
Oh, oh
Don't you bring me down today
Don't you bring me down, ooh
Today
```
## c-c -- Codeless Web Components
For more extended functionality, use element c-c, "codeless component" (reference: carbon-copy/c-c.js).
Unlike b-c-c, c-c actually generates a custom (web) component 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).
So here are the steps to create a web component using c-c:
Step 1. Define a template:
```html
Hello, world
```
Step 2. Register the web component
```html
```
Or, if the c-c element comes right after the template element:
```html
Hello, world
```
Step 3. Add your web component to the page
```html
...
...
```
Step 4. Stare into the abyss.
### Adding string/numeric/bool properties to your declarative web component
The template can specify a list of primitive properties to add to the automatically generated web component:
```html
...
```
These properties can be read via attributes on the "c-c-pow" element instances (in this example), or passed in as properties. They will reflect to [custom psuedo states](https://www.chromestatus.com/feature/6537562418053120) when the browser allows it.
### Bind to the properties
c-c (or carbon-copy) supports binding to the UI using an [extension](https://www.npmjs.com/package/templ-arts) of Github's [Template-Parts library](https://github.com/github/template-parts/).
Example:
```html
Hello, {{place}}
```
Results in displaying "Hello mars".
The value of place can be manipulated either via the attribute value or the property value. Lisp-case/camelCase is used for attributes/properties.
[Demo](https://jsfiddle.net/bahrus/t0n9eLuo/4/)
Setting default values
```html
Hello, {{place}}
```
### Attaching event handlers
Use [on-to-me](https://github.com/bahrus/on-to-me) [or](https://github.com/bahrus/pass-down) [other](https://github.com/bahrus/p-et-alia) [declarative](https://github.com/bahrus/xtal-decor) vocabulary libraries.
## carbon-copy [TODO]
Finally we get to element carbon-copy. It synthesizes some of the features of both b-c-c and c-c together.
Like b-c-c, it can take a materialized DOM element as its input, not just a template. Like b-c-c, it can perform a transform on the (materialized) DOM fragment.
This transformed fragment can become the template used for generating the custom element. The transform can be used to insert dynamic "parts" in the template.
So while c-c encourages a 100% JS-free web component, with not much support for SSR, carbon-copy allows an initial view based on SSR, but then it transforms the initial view into a general template used by web component instances.
## Viewing Your Element Locally
1. Install node.
2. Clone or for fork this git repo.
3. In a command prompt from the folder of this git repo:
```
$ npm run serve
```
4. Open browser to http://localhost/demo.