Skip to content

Using our Web Components in Your Application

Jump to bottom Edit New page
Arron Schaar edited this page Jul 10, 2014 · 4 revisions

Getting started with X-Tags in your application

Requirements:

Node.js and NPM

Bower Package Manager

Gruntjs

Adding X-Tag to your project

X-Tag uses Bower Package Manager and Gruntjs to download and build the script dependencies.

First, ensure you have a file called package.json in the root of your project. If you have been using any other node.js tool for this project, you might have it already. Otherwise, you can create an almost empty one that looks like this:

{
}

Using NPM, download and install the following tools and dependencies by running:

$ npm install bower -g   // install globally since you'll probably be using this tool in more than one project
$ npm install grunt-cli -g  // install globally too, it's that cool!
$ npm install grunt --save-dev -g  //  save to devDependencies in package.json and global
$ npm install grunt-smush-components --save-dev   // This is our grunt helper that builds all of your components
$ npm install grunt-contrib-concat --save-dev  // Concatenation tool
$ npm install grunt-contrib-jshint --save-dev  // Keep your code lint free

(the reason for ensuring we have a package.json is because otherwise npm will silently ignore our requests for having packages added to the devDependencies section)

Now that you're armed with these tools, let's add X-Tag to your project.

$ bower install x-tag-core    // this will download our core library and the document.register polyfill library.

Bower downloads these libraries to ./bower_components/ and while you could make that entire directory public on your website and reference them, it's messy and probably not a good idea. So let's build x-tag-core and place it in a reasonable location within your application.

In this case, I'm going to assume that you have a ./public/ directory where you host your js/css/img and other static assets from.

Let's use the Grunt library grunt-smush-components to build these dependencies.

Inside your ./Gruntfile.js add the following:

grunt.initConfig({
 'smush-components':{
  options:{
   fileMap:{
    js: './public/js/x-tag-components.js',
    css: './public/css/x-tag-components.css'
   }
  }
 }
});
grunt.loadNpmTasks('grunt-smush-components');

Or, if you don't have a Gruntfile yet, create one in the root of your project so that the resulting file looks like this:

module.exports = function(grunt) {
    
    grunt.initConfig({
        'smush-components':{
            options:{
                fileMap:{
                    js: './public/js/x-tag-components.js',
    css: './public/css/x-tag-components.css'
                }
            }
        }
    });

    grunt.loadNpmTasks('grunt-smush-components');

};

Now, if you run grunt smush-components from the root of the project, it will crawl all of your installed components (not just x-tag related) and append those scripts and css to the targets defined within the fileMap. Note: It does not minify or use requirejs.

Next, inside your application add js and css references to those files in the <head> of your index.html or main template. That is it!

For example:

<link rel="stylesheet" href="css/x-tag-components.css" type="text/css" />
<script src="js/x-tag-components.js"></script>

How do I add a new component?

If you followed the steps above, then you all you have to do is find a component that you would like to use and run the following commands:

$ bower install x-tag-accordion  // downloads x-accordion to ./bower_components/
$ grunt smush-components       // rebuilds the components files including x-accordion

How do I find more X-Tag components?

Use Bower search:

$ bower search x-tag   // lists all x-tag components

Visit our official X-Tag Registry

Visit Custom Elements dot IO

Add a custom footer
Add a custom sidebar
Clone this wiki locally