Skip to content

Latest commit

 

History

History
147 lines (109 loc) · 8.64 KB

README.md

File metadata and controls

147 lines (109 loc) · 8.64 KB
Raw

Tommy

Buy Me A Coffee

Tommy is a pure JavaScript-based speech navigation system for websites. It focuses on providing easy page-to-page speech navigation in a highly-readable way.

Check out a live demo here!



Installation

Installation through popular package managers is coming soon! In the meantime, simply clone / save tommy.js from the src/ folder into your library, and import the file into your HTML page.

Within your HTML, also add the following line in your body:

<tommy-container id="tommy"></tommy-container>

That's it!

Quick Example

Assuming you installed Tommy as detailed above, we can easily startup the Tommy service with a given configuration and settings. In it's simplest form, Tommy can be configured as follows:

// Provide a list of definitions, which Tommy uses as a basis to make recommendations
var definitions = [
    {
        path: "/contacts.html",
        keywords: "contacts contact email phone team",
        title: "Contact Us",
        description: "View contact information for the Tommy project"
    }
]

// Construct and configure the Tommy object
var t = Tommy('tommy', definitions)

The constructor for Tommy takes in the HTML id of the Tommy object (remember id="tommy" from the Installation section), a configuration object, and a settings object (ommitted here, so the default settings are used).

Full API

In it's most basic form, Tommy works by keeping track of a set of definitions, which it uses to generate suggestions to the user. When Tommy is given a payload from the user (either from typed text or spoken speech), it processes this payload and then finds relevant suggestions by finding defitions which have matching keywords. Simple, right?

Configuring Definitions

When giving Tommy a set of definitions, you can provide the most basic items (shown in the Quick Example above), which is simply a path, keywords, title, and description (in fact, you can even omit most of these; more on that later).

The full list of options is:

  • path - The path destination when the suggestion from this definition is clicked. If omitted, nothing happens when clicked.
  • keywords - The words that Tommy uses when searching for relevant suggestions. If omitted, uses title as keywords.
  • title - The title for the generated suggestion. This field is required (unless titleFunction is used).
  • description - The description for the generated suggestion. If omitted, just the title is shown.
  • icon - The path to the icon for the suggestion, which is displayed next to the title. If omitted, no icon is shown for the generated suggestion.
  • titleFunction - A function which takes in a payload (the string received from the user input), and returns a title as a string. Useful for when the title should be modified based on user input. Takes precedence over title, and unused if omitted.
  • descriptionFunction - A function which takes in a payload (the string received from the user input), and returns a description as a string. Useful for when the description should be modified based on user input. Takes precedence over description, and unused if omitted.
  • iconFunction - A function which takes in a payload (the string received from the user input), and returns a path to an icon as a string. Useful for when the icon should be modified based on user input. Takes precedence over icon, and unused if omitted.
  • displayHTML - A function which takes in a payload (the string received from the user input), and returns an HTMLElement that is used as the generated suggestion. Useful for when full control is needed over the display. Takes precedence over all other properties, and unused if omitted.

Available Properties for Settings

In addition to the customizability provided for each suggestion generated by Tommy, you can also customize Tommy overall with an additional JavaScript object. The full list of options is:

  • buttonColor - Color of the Tommy button (as a valid CSS color string).
  • iconColor - Color of the Tommy button icon when not recording (as a valid CSS color string).
  • iconRecordingColor - Color of the Tommy button icon when recording (as a valid CSS color string).
  • visualizerColor - Color of the audio volume visualizer behind the Tommy icon when recording (as a valid CSS color string).
  • panelTitle - The title to show at the top of the Tommy suggestion panel.
  • font - The font family to use for all text that Tommy displays.
  • debug - If true, debug information will br printed to the console during use.
  • disabled - If true, Tommy will be shownm but will not be usable.
  • hidden - If true, Tommy is completely hidden and cannot be used.
  • preClick - A function that gets called when the Tommy button is clicked to start listening or receiving input. This is best used in scenarios where your website frontend needs to commit an action before Tommy begins receiving input.
  • fullscreenIfMobile - If true, Tommy's suggestion panel will be fullscreen when used on mobile phones.
  • fullscreen - If true, Tommy will always display suggestions fullscreen. Takes precendent over fullscreenIfMobile.
  • emptyText - Text to display when Tommy has no suggestions for the current input.
  • emptyHTML - Function that returns HTML to be displayed when no suggestions are found for the current input. Takes precendence over emptyText.
  • speechEnabled - Allows the user to provide speech as a form of input.
  • textEnabled - Allows the user to provide typed text as a form of input.
  • position - Defines the position of Tommy on the screen. Possible combinations are "top start", "top end", "bottom start", or "bottom end".
  • preview - Text to display as a preview before the user starts providing input.
  • previewFunction - A function that returns a string to be used as a preview before listening. Takes precedent over any set preview text.
  • feelingLucky - If true, the user will automatically be redirected to the top suggestion that Tommy for the current input (if that suggestion has a path).
  • algorithm - A string representing which algorithm to use. See more details on this in the algorithm section.

The defaults for all of these properties is shown below (note that undefined simply indicates that Tommy will ignore that property):

var defaultSetting = {
    buttonColor: "#3F51B5",         // Material Indigo 500
    iconColor: "#FFFFFF",           // White
    iconRecordingColor: "#F44336",  // Material Red 500
    visualizerColor: "#7986CB",     // Material Indigo 300
    panelTitle: "Welcome to Tommy",
    font: "Open Sans",              // Google Font included in library
    debug: false,
    disabled: false,
    hidden: false,
    preClick: undefined,
    fullscreen: false,
    fullscreenIfMobile: true,
    emptyText: undefined,
    emptyHTML: undefined,           // Defaults to some custom HTML
    speechEnabled: true,
    textEnabled: true,
    position: "bottom end",         // For LTR locales, bottom right of the screen
    preview: "Say what you are looking for",
    previewFunction: undefined,
    feelingLucky: false,
    algorithm: "inclusive_one",     // Basic algo that uses keywords, titles, and descriptions for suggestions
}

Always-included Definitions

At the moment, there are no automatically-included definitions, such as a suggestion that appears to visit the Tommy home page, or make a donation. This may arise in the future, however.

Included Resources

One of the design goals is to minimize the number of dependencies needed for the Tommy library. However, some items such as fonts and icons needed to be included. Below is a list of dependencies that are attached to your HTML pages when Tommy is loaded:

  • https://fonts.googleapis.com/icon?family=Material+Icons
  • https://fonts.googleapis.com/css?family=Open+Sans
  • https://cdnjs.cloudflare.com/ajax/libs/animate.css/3.5.2/animate.min.css

Contributors

A huge thank-you to the developers, contributors, and donators of the Tommy project!

Primary Developers

Contributors

  • Chris Wilson - Indirect contributor, as we used his volume-meter project for audio visualization

Donators

No current donators. Please consider donating to the project!