Open Element Template
Want to create your own custom HTML tag? Big fan of open source? Enjoy it when you have a mature development process? 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:
- 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.
- 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 pullto 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.
- You are probably going to have a lot of similar web components 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?
- 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
- 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
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.
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 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_TOKENenvironment 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
- Edit open-element.html. Add some HTML between the
<template>tags to include new HTML in your element. Customize the
- Now if you run
npm run demoyou'll see your changes. And if you run
npm testyou'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 testdebugif your tests aren't doing what you expect.
- Repeat #1 and #2 until you have something cool. Or #2 then #1. It's up to you. Have fun!
- Add documents to your code. It's pretty simple, but check out the YUIDoc Syntax Reference if you get stuck.
git cz -a(make sure that you have Commitizen installed) and follow the instructions
git push origin masterto 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.
- Pat yourself on the back and drink a beer.
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:
cd YourProject-- get ready...
git checkout master-- make sure your project is up to date and you are working on the master branch
git pull https://github.com/apowers313/open-element-template master-- fetch and merge the latest version of this project into your master branch
- If necessary, resolve any merge conflicts. For help, check this out https://help.github.com/articles/merging-an-upstream-repository-into-your-fork/
git commit -am 'Merged latest version of open-element-template'-- commit merge changes
git push origin master-- push the entire project back to GitHub