Git Product home page Git Product logo

glossary's Introduction

Glossary panel

CircleCI Test Coverage

About

Add a simple glossary panel to your site to help your users understand jargon-y terms. As seen on FEC.gov and DOI's Natural Resources Revenue Data.

For example:

Getting started

To run the example locally:

npm install -g parcel-bundler
npm start
open http://localhost:1234

Note: if you are a contributor, please see CONTRIBUTING for additional help.

Download

Via npm

npm install glossary-panel

Set up your HTML

The following is the bare minimum HTML needed in your document:

<button class="js-glossary-toggle">Glossary</button>
<div id="glossary" aria-describedby="glossary-title" aria-hidden="true">
  <button title="Close glossary" class="js-glossary-close">Hide glossary</button>
  <h2 id="glossary-title">Glossary</h2>
  <label for="glossary-search">Filter glossary terms</label>
  <input id="glossary-search" class="js-glossary-search" type="search" placeholder="e.g. Committee">
  <ul class="js-glossary-list"></ul>
</div>

It includes a toggle button, a div for the glossary, a close button inside the glossary, a title, a search input and label, and a <ul> for the terms.

Then, to add glossary terms to the body of the page, add a data-term attribute to the terms. For example:

A <span data-term="committee">committee</span> is a thing.

The data attribute must match the text of the term in your JSON file exactly, but it is not case-sensitive.

Initialize

In whichever file you initialize your JavaScript components, initialize the glossary like so:

var Glossary = require('glossary-panel');

// JSON file of terms and definitions
var terms = require('./terms');

// Optional configuration objects
var selectors = { ... };
var classes = { ... };

new Glossary(terms, selectors, classes);

Configuration

The constructor expects an array of objects (terms) that follows this pattern:

[
  {
    "term": "Glossary",
    "definition": "A useful tool for finding the definitions of terms"
  }
]

The constructor also accepts an optional hash of selectors as its second parameter:

  • glossaryID: ID of the glossary panel that will be shown and hidden. Default: #glossary
  • close: ID or class of the close button inside the glossary panel. Default: .js-glossary-close
  • listClass: Class of the <ul> that will be populated with terms. Default: .js-glossary-list
  • searchClass: Class of the <input> that will be used to filter the list. Default: .js-glossary-search
  • toggle: ID or class of the element that will be used to open and close the glossary in the main body of the document. Default: .js-glossary-toggle

And you can pass an optional hash of classes to be applied to to the DOM:

  • definitionClass: Single class applied to the <div> that contains the term's definition. Default: glossary__definition
  • glossaryItemClass: Single class applied to the <li> that contains the term and definition. Default: glossary__item
  • highlightedTerm: Single class applied to terms in the body when they are highlighted. Default: term--higlight
  • termClass: Single class applied to the <button> element that opens the definition. Default: glossary__term

Methods

  • Glossary.show(): Show the glossary
  • Glossary.hide(): Hide the glossary
  • Glossary.toggle(): Toggle the glossary open or closed
  • Glossary.destroy(): Completely remove the glossary from the DOM
  • Glossary.findTerm(term): If the glossary is opens, filters the list down to the term called, expands the term, and highlights the associated term in the DOM

Styling

To style the glossary terms and definitions in the accordion list, either use the default classes or whichever ones you passed in. To change the style of the buttons when the accordion elements are expanded, you can select for [aria-expanded="true"].

You will need to add styles for [aria-hidden="true"] in order to hide the glossary panel and the glossary definitions.

License

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

glossary's People

Contributors

adborden avatar afeijoo avatar afeld avatar dependabot[bot] avatar el-mapache avatar hursey013 avatar jeremiak avatar jessecodescode avatar jmcarp avatar kinow avatar kobekoto avatar mvattuone avatar rossettistone avatar tbaxter-18f avatar toolness avatar waynel avatar xtine avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

glossary's Issues

Add an animated screenshot to the README

This is related to #9, except it's a shorter-term interim solution that involves just adding an animated GIF of the glossary on an existing site, rather than setting up a separate example site and recording it.

Here's an animated GIF I just took of the panel in action on the EITI site that can be used:

18f-glossary

Wow, that is a lot bigger than I thought it'd be.

Feature: close glossary drawer by clicking outside of it

User testing for EITI has demonstrated that people instinctively want to close the glossary drawer by clicking outside of it. So...drumroll...new feature suggestion!

I added this to EITI, but as I had time to add the new 18F/glossary to our site, my additions are wrapped up in our bespoke version of the glossary. Eventually I would like to add this glossary, at which time it would be nice to have this feature available.

Another open source Glossary project

Hey!

I'm a developer with the US Fish and Wildlife Service based out of Atlanta, GA. We're currently re-designing our website and have decided to build a glossary to help our readers navigate regulatory jargon. The glossary downloads terms via AJAX so the terms can be cached. A sub-module of the project searches the current page for any terms and wraps them in a span with a class so they can be highlighted/hooked into w/JavaScript. Clicking a term summons the glossary from off screen. Full text search support is provided by lunr.js.

It's a modular application built with browserify. It's pretty easy to integrate into an existing website (just modify the index.js entry file) and currently weighs in at 39.7kb when minified. If you have any interest you can see the github repo or the relatively unstyled demo.

Suggestion: improve readme to help people reuse this

It'd be nice to add some basic info to this readme since people inside and outside 18F may be interested in reusing a glossary widget for future projects. Suggestions:

  • Add brief introduction to what this does
  • Explain the status of the code (is this usable? still experimental? an experimental forked version of a usable thing found elsewhere?)
  • Link to examples of the glossary in use (such as beta FEC and US EITI)
  • Ideally link to the files in those projects where those versions of the glossary code are living

Remove underscore dependency

Underscore is a bit heavy for a dependency. We're only using it for it's template function and extend. Should be straight forward to remove.

Description for the repo

The repository could use a description, in its project fields at the top of its homepage, and its README.

Code coverage is unknown

May need to include codecov in dependencies (with repository upload token) for codecov render a coverage %.

A Plain Example

I am a javascript noob so the example you have provided doesn't make a lot of sense to me. You require terms.json, but then do not use it because the terms are hardcoded into main.js. However if you remove the reference, nothing works. Is there a plain example that separate the various js pieces (panel, terms, accordion, etc.) into those that are actually used? The ability to link an external json file or call to an api and have terms returned based on a category is how I would like to use this.

Parameterize hard-coded class names

We've moved many hard-coded class names into configurable selectors, but we still have some hard-coded names. Even better would be removing these if we don't need them. A few examples:

  • term--highlight
  • accordion--collapsed
  • accordion__button

cc @noahmanger

problem with require

For some reason, I don't manage to successfully run the following line: var Glossary = require('glossary-panel');

After running the code and looking at the console, I get the following error:
Uncaught ReferenceError: require is not defined

When I instead try to use the whole path, I get the following error:
Not allowed to load local resource: _nameofwholepath_

Does anyone know by any chance why this is caused and how this can be solved.

Remove dependency on lodash.template

The lodash.template library uses eval to get its job done. This is fine-ish, except for when we want to implement a Content Security Policy (CSP) (which should be most of the time, if not always). It throws an error and wants the CSP to contain 'unsafe-eval' but that significantly relaxes the effect of the CSP since eval can be dangerous.

Looking through the codebase, it looks like we're just using the lodash template function to build out the term list (source) so we should refactor that out and remove the use of eval.

Move to a new CI/CD system

This repository has been using Travis CI, however access to Travis CI is now turning off. When you need to use this repository again, convert it to a CI/CD system which is in the ITSP such as Circle CI.

Suggestion: Remove mochify

Mochify relies on PhantomJS, which is more or less deprecated and currently doesn't support ES2015 syntax, which makes it somewhat challenging to reduce reliance on utility libraries like Underscore or Lodash. I discovered this while attempting to remove Underscore in #29 (see issue #27) -- while the merged solution does reduce overall size, it doesn't feel quite like the right fix.

There are a few ways to potentially circumvent the PhantomJS issue, but I think a good, long-lasting solution would be to remove Mochify entirely, replacing it with standalone mocha running Headless chrome, maybe using Puppeteer.

Alternatively, it might be worth submitting a PR to solve mantoni/mochify.js#159, as that would this issue for you and other uses of the library as well.

set up example site

...or at least add screenshots in the README. As a potential user, I want to see it in action!

Feature: Allow for multiple glossary toggles

Currently, we only expect a single glossary toggle per page. But there are times when you may want multiple (such as on the home page of beta.fec.gov when you want to be able to trigger the glossary from a non-term link in the body).

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.