Ember Freestyle is an Ember addon that allows you to quickly create a component explorer for your Ember app.
http://chrislopresto.github.io/ember-freestyle/
- For Ember versions >= 2.8, use the latest published version
- For Ember versions 1.13.0 through 2.7, use ember-freestyle 0.3.0
This installation process is opinionated in order to get you going quickly. We want to make everything much easier to use in the near future. Please report any problems, and as always, PRs are welcome.
-
ember install ember-freestyleThis will do the following:
- Install the
ember-freestyleaddon itself - Add a
freestyletemplate in your app - Add a
freestylecontroller in your app
Note: Ember CLI versions < 0.2.3 should use
ember install:addoninstead ofember install - Install the
-
Add
this.route('freestyle');to yourrouter.jsfile -
Navigate to
/freestyle. You should now see something like:
Here is a simple style guide, where {{loading-spinner}} is a hypothetical component in your application.
Here's a brief rundown of the components Ember Freestyle provides for adding a living style guide in your app:
The freestyle-guide component provides the user interface for a style guide. It includes a header section and
navigation controls.
The freestyle-usage component is the workhorse. Wrap your application's components with a freestyle-usage
component, being sure to provide a unique slug (positional param) as follows:
The snippet above will render your app's x-foo component as well as a handlebars snippet demonstrating how to use it.
Optionally group your freestyle-usage-wrapped components into sections using the freestyle-section component. The
freestyle-section component registers itself in order to appear in the navigation provided by the freestyle-guide
component.
Optionally divide your style guide sections into subsections using the freestyle-subsection component.
The snippet above will create a style guide with one 'Visual Style' section with separate subsections for
'Typography' and 'Colors'. Your app's x-foo-typography and x-fie-colors components would show up in the
appropriate subsections.
NOTE: For subsection navigation to work properly, the freestyle-section component must yield itself as Showcasing
in the above snippet. This limitation will be removed in a forthcoming release.
Use the freestyle-collection component with nested freestyle-variant components to present multiple versions
of a component. This is very useful for presenting and testing a component in each state it must handle
in your application.
By default, variants will be stacked. If you wish to view variants side by side, set the inline property of
freestyle-collection to true.
TODO: Simplify Technique for Including Notes
Use the freestyle-note component to add a markdown note for a specific freestyle-usage. Note that the freestyle-note slug must match the freestyle-usage slug followed by --notes.
Use the freestyle-annotation component to add a general purpose note.
Both the freestyle-note and freestyle-annotation components respect the
Show Notes usage controls preference.
We recommend blacklisting Ember Freestyle for production builds using Ember CLI's addon blacklist feature.
var environment = process.env.EMBER_ENV;
var pluginsToBlacklist = environment === 'production' ? ['ember-freestyle'] : [];
module.exports = function(defaults) {
var app = new EmberApp(defaults, {
addons: {
blacklist: pluginsToBlacklist
}
};
}You should include Ember Freestyle as a devDependency so that apps using your addon will not include Ember Freestyle CSS and JavaScript in their production payloads.
You will need to tell the build where to search for code snippets as follows:
var app = new EmberAddon(defaults, {
// ...
freestyle: {
snippetSearchPaths: ['addon', 'tests/dummy/app']
}
});This project uses https://github.com/skywinder/github-changelog-generator to generate its changelog.
github_changelog_generator --future-release=x.y.z
ember serve- Visit your app at http://localhost:4200.
npm test(Runsember try:eachto test your addon against multiple Ember versions)ember testember test --server
ember build
For more information on using ember-cli, visit https://ember-cli.com/.