open-element-template

0.4.0 • Public • Published

Open Element Template

Community Join the chat at https://gitter.im/apowers313/open-element-template This is a forkable respository MIT License
Package NPM version Bower version NPM downloads
Dependencies Dependencies Dev Dependencies
Build Build Status Sauce Test Status Coverage Status
Release Commitizen friendly semantic-release

Browser Support
Sauce Test Status


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

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

Readme

Keywords

Package Sidebar

Install

npm i open-element-template

Weekly Downloads

1

Version

0.4.0

License

MIT

Last publish

Collaborators

  • apowers313