Running Basic Web Component demos

NOTE: These instructions cover early versions of Basic Web Components up to 0.5. For versions 6.0, please see the consolidated Basic Web Components repository.

---

Creating a sample project to try out a component

If you just want to try out a component like basic-list-box, the simplest way is to create a trivial sample project that includes that component.

Prerequisites: You'll need Node, Bower (best installed globally), and a local web server (Apache, etc.).

1. Create a new folder in a file system location accessible by your locally-installed web server.

2. In that folder, create a file called bower.json, and paste the following text inside it:

   {
     "name": "test",
     "dependencies": {
       "basic-framed-content": "basic-web-components/basic-framed-content#master",
       "basic-list-box": "basic-web-components/basic-list-box#master"
     }
   }
   

   The first dependency is basic-framed-content, a component used in many of the Basic Web Component demos so that those demos can be shown inline on Component Kitchen.

   The second dependency is the name of the component you want to try. If you want to try something other than basic-list-box, replace both occurrences of that string in that line with the name of the component you want.

3. From a command line, navigate to this folder and run bower install. This will install the component you want and all its dependencies.

4. You can find the demo file for the component in question inside <your_folder>/bower_components/basic-list-box/index.html. (Replace basic-list-box with the name of the component you're trying.)

5. Use your browser to open that page through your local web server.

Why the Basic Web Components repositories are set up this way

The components in the Basic Web Components are set up for distribution via the Bower package manager, which presents a limitation: it is hard to organize files so that the component repository can be used in both of the following ways.

1. As a component installed with Bower. When a component is installed with Bower, the contents of the component repo generally end up inside a folder called bower_components (or, often, just components). This means the component, the component demo, and any other auxiliary imports all expect to find the component's dependencies in peer folders. If a component called basic-list-box has a dependency on another component called basic-element, it expects to find that dependency at the peer location "../basic-element/basic-element.html".

2. As a component repository cloned directly with git. This is often a quick way to get a component's source on to your machine, e.g., so that you can try out a component and confirm it does what you want.

For now, the project repositories are optimized for scenario #1 (installation with Bower), since that's the most common way people will pick up these components.

This means that trying to do #2 (cloning a Basic Web Component repository) and running bower install inside the top folder will not give you what you want. You'll end up with the component's dependencies installed inside a new bower_components subfolder, which is not where the component and the demo are expecting to find their dependencies.

Instead, follow the steps above to create a simple test project.