@page Plugins Developing Plugins @parent contributing 0
@body
In this guide you'll learn how to build a plugin for CanJS. As is standard with programming tutorials, we’ll build something that says "Hello World".
We'll be using Yeoman and a generator built to scaffold CanJS plugins. If you don't want to use Yeoman, you will have to create the files mentioned in this guide yourself. The canjs-hello-world repository is where you can grok all of the files the Yeoman generator creates.
The first thing you need to do is install Yeoman and generator-canjs-plugin which will allow you to quickly scaffold a CanJS plugin.
Install both by running the following on the command line:
npm install -g yo generator-canjs-plugin
For help installing or using Yeoman, there is the Yeoman getting started guide
Next create a directory for your plugin and cd into it:
mkdir canjs-hello-world && cd canjs-hello-world
Then run the generator:
yo canjs-plugin
After answering a series of questions about your plugin the generator will create the files and install all of the dependencies you need to develop, test and publish your CanJS plugin.
Now that you have a scaffold in place, you'll start building your plugin.
A single source file will be placed in the src directory. This is where you will add your plugin code. Here's what your plugin should look like:
can.hello = function() {
return 'Hello World';
};
Notice that the file includes bootstrapping that allows it to work with AMD loaders, Steal or stand alone with no dependency management tool.
A QUnit test file and runner are placed in the test folder. The *_tests.js file is where you will write tests for your plugin. Modify the Hello World test so it looks like this:
test('Hello World', function() {
equal(can.hello(), 'Hello World', 'Works!');
});
You can run these tests by opening test/qunit.html in a browser or by running grunt test on the command line. Do this now and make sure the test passes.
Examples for AMD, Steal and stand alone are placed in the example folder. Modify the index.html file in each folder to show people how to use your plugin.
In each of the 3 index.html files replace the line //Demo JS goes here with:
console.log(can.hello());
Open these files in a browser and look at the console to see "Hello World" being logged.
It's highly recommended that you create documentation for your plugin. You can use your plugin repo's wiki or generate a website for it using GitHub pages.
Now that you have developed a plugin, tests and examples, it’s time to build the plugin using Grunt. The following commands are available:
Run jsbeautifier and JSHint:
grunt quality
Run tests:
grunt test
Run tests and places distributable files in the dist folder:
grunt build
The easiest way to distribute your plugin is via Bower In order to create a bower package you'll need:
- A valid manifest file (bower.json) in the root of the project
- All code available at a Git endpoint (hosted at GitHub or BitBucket for example)
- To register your plugin with Bower
A valid bower.json file is created by the generator. If you are coding your plugin from scratch run bower init and answer the series of prompts to generate your own.
Be sure to include relevant keywords in your manifest. For CanJS plugins use can and any other keywords that are relevant. For can.Components add a keyword of can-components.
Each version of your plugin must have a semantic version number and a corresponding Git tag with the same version. You create a Git tag like this:
$ git tag -a vX.Y.Z -m 'vX.Y.Z'
Now that you have a valid manifest a Git endpoint and Git tag you are ready to register your plugin. To do this use the bower register command:
$ bower register [plugin-name] [git-endpoint]
[git-endpoint] is the URL to your repository, typically starting with git://.
Your plugin is now available via the bower registry!
That's all there is to it. In this guide you developed a CanJS plugin complete with tests and examples and learned how to distribute it via bower.
If you've created a CanJS plugin we'd love to hear about it over on BitHub IRC or our forums.