npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pillbox

v1.0.0-beta2

Published

Small library for creating lists of tags in containers.

Downloads

5

Readme

Pillbox.js

Build Status

Pillbox.js is a UI container for your (optionally pill-styled) tag labels. The pillbox contains pills (tags), and each pill is aware of its state. Events are emitted whenever something interesting happens.

Usage

Installation

Pillbox.js is available as a CommonJS module. Soon, it will be available via npm, like so:

npm install --save pillbox

And you can require it in your project:

var Pillbox  = require('pillbox');

Contstruction

The Pillbox variable above is a constructor that takes an object with the following properties:

  • container -- The parent DOM element that will contain each "pill"
  • pills -- An optional array containing the initial collection of pills

Pills are created with the following options:

  • key -- String, used to identify the pill, must be unique
  • value -- String that will be displayed on the rendered pill
  • remove -- Optional boolean, determines if pills should have close buttons when no template is present.
  • template -- An optional function, should return a string of HTML given an object parameter with a value property.
  • states -- An optional array of strings to be used as initial states
var pb = new Pillbox({
  container: document.querySelector('.pill-container'),
  pills: [{/* see pill options above */}]
});

Pillbox Methods

addPill( options )

You don't have to add pills initially, though. You can easily add them after creating pb.

pb.addPill({
    key: 'roots',
    value: 'Root Vegetables',
    template: require('tag.jade'),
    states: ['disabled']
});

removePill( key )

You can also remove a pill if you know its key:

pb.removePill('roots');

getPill( key )

You can retrieve an instance of a pill if you know its key. This allows you to check or set a pill's state.

pb.getPill('roots').removeState('disabled');

keys()

You can also request an array of all keys, which would allow you to iterate over each pill and remove it or modify its state:

var pillKeys = pb.keys();
_.each(pillKeys, function (key) {
  pb.removePill(key);
});

Pill Methods

Managing State

Each pill has an array of states. States translate to classes in the DOM, and they can be modified and queried with the following methods.

  • setState(state) -- Adds a new state based on the given string
  • removeState(state) -- Removes an existing state
  • hasState(state) -- returns true or false depending on the existence of a given state
  • cleanState() -- removes all states from the pill

Interacting with the DOM

  • draw(parent) -- Appends an element representing the pill into the given parent
  • erase() -- Removes the pill's element from the DOM

Events

Pills emit several events:

  • "click" -- When a pill is clicked
  • "state:add" -- When a state is added to a pill
  • "state:remove" -- When a state is removed from a pill
  • "request:remove" -- When a pill requests to be removed (e.g. when the x is clicked)

However, getting pill instances is a hassle, so all pill events are also forwarded through Pillbox with a "pill:" prefix. Instead of listening for "request:remove" on each pill instance:

_.each(pb.keys(), function (key) {
  pb.getPill(key).on('request:remove', function () {
    pb.removePill(key);
  });
});

You can instead listen for the event on pb directly, which is more concise:

pb.on('pill:request:remove', function (pill) {
  pb.removePill(pill.key);
});

In addition to forwarding Pill events, Pillbox emits two events of its own:

  • "pill:add" -- Emitted after a new pill is added. The pill object is passed to the callback.
  • "pill:remove" -- Emitted after a pill is removed. The pill's key is passed to the callback.

Development

With npm and gulp installed globally, you can run a development build (which includes file watching) by running the following in the project directory:

npm install
gulp