Open Element Template

Browser Support

About

Want to create your own custom HTML tag? Big fan of open source? Sleep better when you have automation watching over your code to make sure it isn't embarassingly broken? This is the project for you...

Much like Polymer boilerplate, Polymer seed-element, generator element, and others, this is a template for creating new custom web elements. (Sorry for calling it "template" -- I realize that has other meanings for web components.)

So why another template for Polymer elements? This one has three ideas behind it:

1. It has built-in support for the most important services that are free open source projects , such as Travis for testing, SauceLabs for cross-browser testing, some badges and other stuff. Figuring out how to setup and integrate these services can take time and isn't fun or productive.
2. If you fork or clone from this repository, you can merge in new services and features into your component as they become available. You don't have to figure it out, just git pull to merge in new features and services and you will get anything new that has been added. This can be new features, new documentation, new badges, etc.
3. You are probably going to have a lot of similar web components (the Polymer Project has 93 at last count) and trying to maintain their core structure is going to be a boring waste of time. Wouldn't it be great if they can all share a common structure and be updated in an easy and effective way?

Features

• Travis CI integration for automatic testing
• SauceLabs integration for multi-browser testing
• Web Component Tester for Polymer testing
• YUIDoc for document generation
• GitHub Pages for hosted API documentation, for example see the sample docs for open-element-template
• Istanbul and WCTI code coverage, for exmaple see the code coverage report for open-element-template. (Currently only works for .js files, not JavaScript embedded in HTML)
• Coveralls code coverage reporting, based on the Istanbul report
• semantic-release for automatic versioning, change log creation, and publishing
• Commitizen for conventional commit messages and change logs
• customelements.io keywords to publish the element where people can see it
• David dependency status
• Gitter for online conversation about your element
• Nifty badges for many of the projects above
• Forking this repo means that as new features are added, they can be included in your project with a simple git pull request

If there are features or services that you think should be here, I am happy to take requests. Feel free to submit an issue or send in a pull request.

Install

npm install open-element-template

...but you already knew that, right? The trick here is that there is a postinstall script that runs through a series of questions to configure all the services. This involves setting up a new repo on GitHub, enabling builds on Travis CI, and optionally setting up other services. It then overwrites the files in this package with configuration files that tie together all the services. It's awesome when you have a configuration management system that just works together. Especially when you don't have to spend two weeks setting it up.

Things to Try After You Install

• npm test -- uses the web component tester to open browsers at SauceLabs and test your element on each of them (requires SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables to be set, see above)
• npm run demo -- shows your new element in action
• npm run testdebug -- runs a single pass of the tests using your local copy of Chrome, and keeps Chrome open so that you can see the debug console and refresh to re-run tests
• npm run localtest -- runs tests in all browsers that are installed on your system
• npm run viewcoverage -- view your code coverage report (caveats: requires a successful test run, currently only works for standalone .js files, not JavaScript embedded in .html files)
• npm run docs -- generate docs for your components and store them in the ./docs directory
• npm run deploydocs -- deploy your documentation to GitHub (requires that the GH_TOKEN environment variable be set to your GitHub personal token, created above)
• npm run testdocs -- generate docs for your components, and fire up a webserver and a browser to view them -- great for testing your docs as you are writing them
• npm run config -- if you didn't complete configuration during installation, this is how you can kick it off again
• git cz -a -- commit all changes using Commitizen
• Check in your code to automatically test it, build documentation, and deploy documentation

How to Develop Your Custom Element

1. Edit open-element.html. Add some HTML between the <template> tags to include new HTML in your element. Customize the Polymer() JavaScript to add new properties or functionality to your element. Want some help getting started? Check out the Polymer Developer Guide or see some examples from the polymer-example-element.
2. Now if you run npm run demo you'll see your changes. And if you run npm test you'll notice... whoops! You broke the tests! Edit test/open-element.html to update your tests. Tests are using the Web Component Tester, which uses Mocha as a test framework, Chai for assertions, and Sinon for other stuff -- especially mocking servers. Don't forget to use npm run testdebug if your tests aren't doing what you expect.
3. Repeat #1 and #2 until you have something cool. Or #2 then #1. It's up to you. Have fun!
4. Add documents to your code. It's pretty simple, but check out the YUIDoc Syntax Reference if you get stuck.
5. Run git cz -a (make sure that you have Commitizen installed) and follow the instructions
6. git push origin master to push your changes back to GitHub. Watch with delight as Travis and SauceLabs test your element on a wide variety of browsers, and semantic-release automatically bumps-up your version number, creates a change log and publishes the package to npm.
7. Pat yourself on the back and drink a beer.

Updating

Are there new features in this repo that you wish you had? If you forked or cloned from this project, here's how to merge them into your project:

1. cd YourProject -- get ready...
2. git checkout master -- make sure your project is up to date and you are working on the master branch
3. git pull https://github.com/apowers313/open-element-template master -- fetch and merge the latest version of this project into your master branch
4. If necessary, resolve any merge conflicts. For help, check this out https://help.github.com/articles/merging-an-upstream-repository-into-your-fork/
5. git commit -am 'Merged latest version of open-element-template' -- commit merge changes
6. git push origin master -- push the entire project back to GitHub