showcase

What is this?

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:

How to install

To install ember-showcase use the regular ember-cli-command to install an addon:

$ ember install ember-showcase

How to use

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.

Components

Showcase

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 snippet
• state - 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 snippet
  • snippets - 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 snippet

Snippet

The 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.

Example

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:

Implementing 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-Usage

Here’s how you will be able to use the Demo component: