18f / glossary Goto Github PK

A glossary panel for your site to help readers understand jargon

License: Other

JavaScript 85.36% HTML 8.77% CSS 5.86%

glossary's Introduction

Glossary panel

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:

https://www.fec.gov/data/ - click on the Glossary book icon in the header
https://www.fec.gov/help-candidates-and-committees/registering-candidate/ - click on contributions
https://revenuedata.doi.gov/ - click on royalties

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

Stargazers

Watchers

glossary's Issues

Namespace CSS classes

It would probably be helpful to namespace our CSS classes, right?

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:

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

Get accessibility review before publishing to NPM

I'm pretty sure we're good on this, but just to be safe, I'm going to ask Nick to do an accessibility review before we publish to NPM.

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

Minor spelling issues in README.md

Hello 18F,

In reading the README.md I and a friend noticed two instances of miss-spelled words.

https://github.com/18F/glossary/blob/master/README.md#configuration
glossaryItemClass: Single class applied to the

that contains the term and deffinition. Default: glossary__item

https://github.com/18F/glossary/blob/master/README.md#styling
To style the glossary terms and defintions in the accordion list,

Keep up the good work!

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

Select terms based on data attribute

We currently look for class="term" to select terms in the body of the document, but this requires users to add a class and a data attribute to each term. Instead, let's just query for terms with data-term set here: https://github.com/18F/glossary/blob/master/src/glossary.js#L106

Replace accordion

Consider replacing the accordion with something simpler than https://github.com/jmcarp/accordion, which is an extract from https://github.com/18f/fec-style, which borrowed the relevant code from a source I can't remember at this point. We might want to use the USWDS accordion, or just implement a tiny accordion within this library, since our needs are minimal.

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.

Add USAJOBS Help Center example in the readme

Update the readme to add the following example.

The 18F Glossary is used in the USAJOBS Help Center too, which you can see on competitive service at https://www.usajobs.gov/Help/working-in-government/appointments/examination/.

Source: https://gsa-tts.slack.com/archives/C3F14AHSQ/p1585226486012200?thread_ts=1584715110.163600&cid=C3F14AHSQ

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.