Umbra JS is a very simple, straight-forward and easy to use jQuery plug-in for creating a modularized html presentation. HTML Custom Elements is a capability for creating your own custom HTML tags and elements. Browsers with Custom Elements support recognize any invalid html tag you write in your html file, which means you retain the ability to control that invalid element, however on non-supporting browsers, elements with invalid tag will be just completely ignored.

Umbra JS combines custom elements with templating system. With it, you can attach a template to each custom elements you defined in your html.

What makes Umbra JS different to other implementations like completely replacing the element with a new one?

Umbra JS is using a fairly new APIs to do things. That includes detecting if there are newly created/added elements to the DOM and also on how the template element behaves on top of the target custom element.

In Umbra JS, there are no setIntervals running forever, and the target elements are not really replaced. That means, Umbra JS is fast since it is using native implementations. Whenever you add a new custom element into the DOM dynamically, the template is automatically applied to the element, so there's no weird behaviors like the users are able to see the original element then replaced with the template. Umbra JS also have few methods to enable you to change templates on the fly and quickly update the existing custom elements with the new template and to totally destroy Umbra JS instance like nothing happened!

How to use?

Duhh?! It's never been so easy!

Let's say you have a div with a span inside and want to represent it as a single custom element named "my-element"

Your HTML should look like:

<my-element>John</my-element>

And your javascript should look like:

<script>
         $(document).umbra({
              tag: {
                  "my-element" : "<div>My name is: <span>{{content}}</div>"
              }
         });
</script>

Umbra JS also supports external file templates.

<script>
         $(document).umbra({
              tag: {
                  "my-element" : "external-template.html"
              }
         });
</script>

And also supports closures for much more advanced manipulation. The context of the closure is the current custom element being processed. Take note that the closure should return either html text or jquery object!

<script>
         $(document).umbra({
              tag: {
                  "my-element" : function() {
                        var $sample = $("<div>");

                        $sample.html( "My name is: "+ $(this).html() );

                        return $sample;
              }
         });
</script>

Now, let's combine html and javascript part:

<html>
    <head>
        <title>Hey Umbra JS!</title>
        <script src="jquery.min.js"></script>
        <script src="umbra.jquery.js"></script>
        <script>
                $(document).umbra({
                  tag: {
                      "my-element" : "<div>My name is: <span>{{content}}</div>"
                  }
                });
        </script>

    </head>
    <body
        <my-element>John</my-element>
    </body>
</html>

But to see is to believe right?

Then you got it right here!

(Check the source code for the implementation)

Umbra can support multiple custom elements too!!!

(Check the source code for the implementation)

Check it out here!

Methods

Umbra JS have tag and destroy methods.

Tag

The tag method is used to change the registered template on the fly. Any change to the template using the tag method, the change will automatically propagate to all affected elements!

usage:

        <script>
                $(document).umbra("tag", "my-element", "<div>This is a new {{content}}!</div>");
        </script>

Destroy

The destroy method is used to destroy the Umbra JS instance and remove some associated data.

usage:

        <script>
                $(document).umbra("destroy");
        </script>

Bad News!

Umbra JS is natively supported only by Google Chrome. :(

But wait! there's a workaround! I don't want you to feel bad for not having Umbra JS in different browsers. So I'll tell you how to make it work on other browsers.

You need to download Web Components Polyfills library and include the webcomponentsjs.js just above the umbra.jquery.js like this:

<html>
    <head>
        <title>Hey Umbra JS!</title>
        <script src="jquery.min.js"></script>
        <script src="webcomponentsjs/webcomponents.js"></script>
        <script src="umbra.jquery.js"></script>
        <script>
                $(document).umbra({
                  tag: {
                      "my-element" : "<div>My name is: <span>{{content}}</div>"
                  }
                });
        </script>

    </head>
    <body
        <my-element>John</my-element>
    </body>
</html>

And voila! Umbra JS is now working on other browsers! :D

For suggestions and improvements. Please feel free to fork Umbra JS and submit a pull request to the repository.