gls-twisty v0.0.8

Glass Twisty Web Component

A web component that creates a collapsed section of content, which can be interactively and programmatically opened or closed.

I created this component as a way to study how to build web components using the Stencil web component compiler. My goal is to build up to something much more sophisticated such as a tree control and my current idea is that this component, while useful alone, might play a part in a tree control. 'Glass' is just a potential name for a family of components in case I end up developing more as a set.

Rendered Example (closed)

Rendered Example (open)

Rendered Example (cascade)

The twisty cascades nicely when included within itself. With an icon added to the start slot, we have the basis for a tree control.

Usage

Using the web component on your own site

You can include the component via script tag or node_modules as described below.

Script tag

1. Put this script tag (<script src="https://unpkg.com/gls-twisty@latest/dist/gls-twisty.js"></script>) in the head of your index.html file.
2. Then you can use the element anywhere in your template, JSX, html etc.

Node modules

1. Run npm install gls-twisty --save
2. Put a script tag similar to this (<script src="node_modules/gls-twisty/dist/gls-twisty.js"></script>) into the head of your index.html
3. Use the element anywhere in your template, JSX, html etc.

In a Stencil starter app

To use the component in a Stencil starter app... 1. Run npm install my-name --save 2. Then you can use the element anywhere in your template, JSX, html etc

HTML Element

<gls-twisty>
  <!-- Your HTML content here... -->
  <p>Lorem ipsum dolor sit amet.</p>
  <p>Praesent facilisis nunc et varius blandit.</p>
</gls-twisty>

Element attributes

• label - optional string label; defaults to "More..." if not provided.
• state - optional render state; specify either "open" or "closed"; defaults to "closed" if not provided.

API Methods

• getState() - returns the internal state of the component ("open" or "closed"); this may differ from the value given through the state attribute of the element once the state has been changed through user interaction or programmatically through the API.
• open() - opens the twisty and sets the internal state to "open"
• close() - closes the twisty and sets the internal state to "closed"

Usage examples

To specify your own label, use the label attribute...

<gls-twisty label="Click for more details...">
  <!-- ... -->
</gls-twisty>

To render the twisty opened, use the state attribute with a value of "open"...

<gls-twisty label="Click for more details..." state="open">
  <!-- ... -->
</gls-twisty>

The twisty can be opened or closed programmatically using the open() and close() API methods of the element...

<gls-twisty id="twisty">
    <p>Hello World!</p>
</gls-twisty>

<button onclick="toggleTwistyState()">Toggle programmatically</button>

<script>

  function toggleTwistyState() {
    var twisty = document.getElementById('twisty');
    var state = twisty.getState();
    if(state == "closed") {
      twisty.open();
    } else {
      twisty.close();
    }
  }

</script>

To insert an element after the twisty icon and before the label, give the element the slot="start" attribute. As an example, we are inserting a folder icon from the Ionic framework in the start slot below.

<gls-twisty id="twisty" state="closed">
  <ion-icon name="folder" slot="start"></ion-icon>
  <div>Lorem ipsum dolor sit amet</div>
</gls-twisty>

Browser support

Tested and verified to be compatible with:

• Chrome (66)
• Firefox (59)

Compatibility notes

CSS flex-box is within the component and currently, no attempt has been made to honor old specifications of the flexbox spec with browser-specific prefixes in the CSS.

Developer guide

You can contribute to this component or fork it as a basis for your own.

To start, clone this repo to a new directory:

git clone https://github.com/codyburleson/gls-twisty.git gls-twisty
cd gls-twisty
git remote rm origin

and run:

npm install
npm start

To watch for file changes during develop, run:

npm run dev

On some browsers, you may have to run

npm run dev --es5

To build the component for production, run:

npm run build

To run the unit tests for the components, run:

npm test

Need help? Check out Stencil docs here.

TO DO

• Give the widget a nice default style
• Figure out a way and document how you can override the internal styles.
• Write the spec tests. For an example, see: my-component.spec.ts
• Figure out how to build all glass components in one project, but deploy independently to npm.
• Consider adding an attribute for styling sizes (sm,md,lg)
• Consider adding an attribute for iOS, Android (material) styling
• Develop and test support for IE11.
• Add and test support for Section 508 Accessibility
• Test across all other evergreen browsers