Web Components
Introduction
If you are writing web applications and you're allowed to use modern browser features, Web Components is a very powerful ally. A good introduction can be found on WebComponents.org, but we will give you a summary and how to use Web Components in Starcounter web apps.
Summary of Web Components
Web Components are a set of new features in HTML 5 and beyond. Each feature is useable on its own and is not dependent on the other features, but together they really have the potential to change the way web applications are developed.
For instance, Web Components allow us to render a list of products and their barcodes by executing this code in a web browser:
This is only a fraction of what would be required in traditional frameworks, such as Backbone.
<template> Tag
<template> TagStarcounter let's you create JSON view-models that expose the current application state. To render it in the UI, it is the simplest to use a client-side framework that provides two-way data binding between HTML and JSON.
The <template> tag that was added to HTML5 as part of the Web Components spec family. It allows to define reusable chunks of HTML that work with any framework that supports this new web standard. Because it is now an established standard, we decided to use it to power partials.
Custom Elements and Shadow DOM
We suggest to keep the business and application logic on the server. Yet, there is still plenty of room to use the capabilities of a modern web browser to run the view logic.
Custom Elements and Shadow DOM define how one can wrap a complex view functionality into a simple HTML tag, that requires no knowledge about the implementation details from the developer.
As can be seen in the above code snippet, to render a UPC-A barcode using SVG in a web browser, you can just import and use a MIT-licensed Custom Element called x-barcode. There is no learning curve and you don't need to care about the implementation details.
Thousands of open sourced Custom Elements can be found on customelements.io.
HTML Imports
Last but not least, the HTML Imports spec is the part of Web Components family that defines how to obtain fragments of code using a <link> tag. As can be seen on the above snippet, this is how a definition of a Custom Element is loaded.
In addition to loading Custom Elements, Starcounter takes benefit from HTML Imports to compose complex apps using small templates known as partials, but you don't need to care much about that because it is done behind the scenes.
Using Web Components
Web Components are loaded by browser with HTML Imports. HTML Import for Polymer in Starcounter should look like this:
Avoiding Loading the Same Files Multiple Times
Browser loads HTML Imports only once, not like scripts and styles, which are loaded as many times as many references page has.
How does the browser know which of the components has already been imported then? Browser distinguishes Web Components one from another by their location.
This will be loaded twice and then lead to a Polymer error:
It is a good practice to avoid double loading of external libraries. Hence, you need to use the same URL pattern as other apps. The recommended way is to use the pattern: /sys/<dependency-name>/<dependency-files>.
Starcounter has system folder called StaticFiles and located in the installation folder: C:\Program Files\Starcounter\ClientFiles\StaticFiles. There you can find sys folder, which includes some common components such as Polymer and Palindrom. You can also look at the code example under PartialToStandaloneHtmlProvider on the middleware page to see what client side libraries are included in that directory by default.
The benefit of this is that you can rely on having a specific version of Starcounter to include a specific version of Polymer, Palindrom, etc.
Adding External Dependencies to Your Apps
In order to add files that match this pattern, simply put a sys folder in your wwwroot folder that holds the static files for your project.
You should not do that automatically, but use Bower to install such dependencies. A correct Bower configuration consists of two files in your project: .bowerrc and `bower.json.
.bowerrc
The .bowerrc file contains the Bower configuration. It specifies the destination directory and what dependencies should be ignored, because they are delivered with Starcounter. An example of this can be found in the KitchenSink app.
To find the specific dependencies that are delivered with Starcounter, go to C:\Program Files\Starcounter\ClientFiles\bower-list.txt. For Starcounter 2.3.1.6694, it looks like this:
bower.json
bower.json file that keeps the list of your app's client side dependencies. This file should not be created and maintained manually. It should be modified using the command line tool: bower init, bower install paper-dialog --save.
A sample file can be found in the KitchenSink app.
Static File Server
The StaticFiles folder from Starcounter installation is automatically served as a static content folder. When Starcounter server receives a request for a static file, it searches for the file in all of the static content folders. The project folder has higher priority over internal folder.
Read more here.
Keep that in mind you can simply use another version of Polymer by putting it into your local sys folder. This will affect all other apps, though.
Last updated