Skip to content

effective-ember/ember-showcase

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

68 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ember-showcase CI

A set of primitives to showcase interactive code examples

le demonstration a la gif

Compatibility

  • Ember.js v3.16 or above
  • Ember CLI v2.13 or above
  • Node.js v10 or above

Installation

ember install ember-showcase

Usage

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. As it is meant as a base for your own abstraction on top of it you can style it as you see fit. The follwing guide walks you through the existing components in ember-showcase and how you could 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

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.

Here's how you will be able to use it:

<Demo as |demo|>
  <div>
    Hello world!
  </div>
  <demo.ui.useSnippet @name="demo-usage.md" @title="template.hbs" @language="html" />
</Demo>

And here's how you would use ember-showcase to implement Demo:

<Showcase as |showcase|>
  <div>
    {{#each showcase.state.snippets as |snippet|}}
      <button
        type="button"
        {{on "click" (fn showcase.actions.activateSnippet snippet)}}
      >
        {{snippet.title}}
      </button>
    {{/each}}
  </div>
  <div>
    {{yield (hash
      ui=(hash
        useSnippet=showcase.ui.useSnippet
      )
    )}}
  </div>
  {{#if showcase.state.activeSnippet}}
    <showcase.ui.snippet
      @name={{showcase.state.activeSnippet.name}}
      @language={{showcase.state.activeSnippet.language}}
    />
  {{/if}}
</Showcase>

Bundled addons

ember-showcase bundles some addons to provide its functionality.

If you need to customize code-snippet or code-highlighting functionality please have a look at the documentation of both addons.

Contributing

See the Contributing guide for details.

License

This project is developed by effective-ember and contributors. It is licensed under the MIT License.