ember-showcase
allows you to showcase the usage of your components by
rendering the component with accompanying code snippets to show how the
component is configured. Say you have a <Greeting @name="..." />
component
and want to showcase its usage by demonstrating the possible arguments.
ember-showcase
allows you do that with an output like the following:
<Greeting @name />
component renders a
greeting (optionally uppercase) for the passed in @name
argument.
To install ember-showcase
use the regular ember-cli
-command to install an addon:
$ ember install ember-showcase
ember-showcase
is an addon that provides you with component abstractions
that you can build upon to showcase interactive code-samples in your
applications.
This can be useful for documenting an addon, a styleguide or when writing a blog.
ember-showcase
comes with no styling - the
components it provides are not meant to to be used as they come. The bundled
components of ember-showcase
are primitives that you will use to build your
own component abstraction for displaying interactive code samples that you
style to your liking.
The following guide walks you through the existing components in ember-showcase
and how you can use it to create your own component abstraction on top of it.
The Showcase
-component is a provider component that yields out everything you
need to build your own interactive code sample component.
Showcase
- yields a nested hash that holds the following properties:
ui
- a set of declarative components
useSnippet
- a component that you use to register snippets to the Showcase
snippet
- a component that renders a code snippetstate
- state of the Showcase
you can use to build your own code sample
abstraction
activeSnippet
- the currently active code snippet of all all the registered
snippets. By default this will be the first registered snippetsnippets
- all the registered snippets on the Showcase
actions
- a set of actions you can trigger on the Showcase
registerSnippet
- an action to register a code snippet on the Showcase
activateSnippet
- an action to switch out the currently active snippetThe Snippet
-component is a component that you can use to render code-snippets registered via
ember-code-snippets.
Highlighting code snippets is done via ember-prism.
In this example we will walk you through creating your own Demo
-component
that is based on ember-showcase
. Demo
will be able to show an interactive
code sample - i.e. an ui that shows the code to demo in action. You will also
be able to attach an optional set of code-snippets (based on
ember-code-snippet) that you can
toggle between to show other developers how the component you are demoing will
be used in code. Code highlighting is based on
ember-prism if you want to customize the theme used in code snippets please configure ember-prism
accordingly.
This guide is customizing ember-prism
in the following way for example:
Demo
And here’s how you would use ember-showcase
to implement Demo
- you don’t
need to do more than create your own component wrapper that uses Showcase
internally - the example uses tailwindcss for
styling but you can use whatever CSS authoring method you are comfortable with:
Demo
-UsageHere’s how you will be able to use the Demo
component: