Skip to content

Create fancy, chrome-look-alike settings for your Chrome or Safari extension in minutes!

License

Notifications You must be signed in to change notification settings

LiminalSoftware/fancy-settings

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

80 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Fancy Settings 1.2

Create fancy, chrome-look-alike settings for your Chrome or Safari extension in minutes!

Rationale

The goal of this project is to provide a simple way to generate native-chrome-like settings pages for use in projects like chrome extensions. Settings are defined entirely using a javascript object, the "manifest," and event binding can be easily customized via javascript.

Ideally, this framework contains enough variety of setting types that one need only to edit the "Manifest" (/source/manifest.js) and the settings initialization script (/source/settings.js) to populate the settings page with the right controls.

How It Works

Project Structure

├── css ─────────────────────────├─( framework css; if you're extending the framework you should add to these )
│   ├── main.css ────────────────├─( main layout )
│   └── setting.css ─────────────├─( styles for each "setting" [ListBox, Button, etc.] )
├── custom.css ──────────────────├─( your css should go here, probably overriding default styles  )
├── i18n.js ─────────────────────├─( your internationalization data )
├── icon.png ────────────────────├─( favicon shown on the settings tab in chrome )
├── index.html ──────────────────├─( index page; loads all javascript and establishes main layout )
├── js ──────────────────────────├─( framework javascript; if you're extending the framework you should add to these )
│   ├── classes ─────────────────├─( mootools-backed framework classes )
│   │   ├── fancy-settings.js    ├─( main entry point; contains `FancySettings.initWithManifest` function, used to 
│   │   │                        │       build all settings and add them to the DOM )
│   │   ├── search.js ───────────├─( provides management interface for the search index )
│   │   ├── setting.js ──────────├─( classes for all setting types (e.g. ListBox, Button, etc.) and the Setting class
│   │   │                        │       itself; includes DOM creation and event logic )
│   │   └── tab.js ──────────────├─( class for `Tab`; includes DOM creation and tab switching )
│   └── i18n.js ─────────────────├─( internationalization interface; retrieves i18n values registered in `/source/i18n.js` )
├── lib ─────────────────────────├─( dependencies
│   ├── default.css ─────────────├─( base css for elements and utility classes )
│   ├── mootools-core.js ────────├─( mootools )
│   └── store.js ────────────────├─( localStorage interface )
├── manifest.js ─────────────────├─( your settings manifest; see [The "Manifest"](#the--manifest)
└── settings.js ─────────────────└─( your settings pre-initialization; `FancySettings.initWithManifest` is called here 
                                         after any prerequisite async event (e.g. domready, retrieving values from 
                                         `chrome.storage`, etc.); see [Settings Initialization](#settings-initialization) )

The "Manifest"

The "Manifest" (/source/manifest.js) is a simple javascript file which registers a global object: manifest. This object contains the following properties:

  • name: Name of the manifest

  • icon: Filename of the favicon to show for the options tab in chrome

  • alignment (optional): WIP - not sure how to explain this yet

  • settings:

    An array containing a "flattened" list of settings. Each element in this array describes one setting. All setting objects, regardless of type, have the following properties:

    • tab: The name (and text) of the tab where the setting will be shown; settings with the same tab value will be rendered on the same tab
    • name: The name of this setting; this name will be used to reference it later via javascript, usually as the key of an object
    • type: The type of setting, see setting types below
    • label (optional): The text of a <label> element which will be rendered before the setting element
    • group (optional): The name (and text) of the group (a section within a tab) where the setting will be shown; settings with the same group value will be rendered in the same group

Events

(WIP)

Setting Types

Type Description Additional Properties Events
description renders a <p> element containing a block of text
  • text: the text content of the <p> element
button renders a <button> element
  • text: the text of the <button> element
  • action: fires on button click
text renders an <input> element with a type attribute of either text (default) or password
  • text: the value of the placeholder attribute of the <input> element
  • masked: a boolean property; if true, sets the type attribute of the <input> element to password
textarea renders an <input type='textarea'> element
  • text: not sure what this does yet
  • value: not sure what this does yet
action: fires on textarea change & keyup
checkbox renders an <input type='checkbox'> element HINT: use label with this setting type
  • action: fires on checkbox change
slider renders an <input type='range'> element
  • min: sets the min attribute
  • max: sets the max attribute
  • step: sets the step attribute
  • display: a boolean property; if true (default), renders the current value of the slider beside it (unless modified by displayModifier)
  • displayModifier: a function which receives the value of the range and whose return value is rendered beside the range if display is true
  • action: fires on range change
popupButton a bit of a misnomer; render's a <select> element with <option> childred corresponding to the options array
  • options: an object with groups and values properties
    • groups: an array of strings; each renders an <optgroup> element whose label attribute is the value of the string
    • values: array of objects which correspond to the <option> elements to go inside the <optgroup>s; each object should have a text property which renders as the text node inside of the <option>, a value property which is the value of the value attribute on the <option> element, and a group property which detmines which <optgroup> a given <option> is placed
action: fires on select change
listbox renders a <select> element in listBox mode with <option> elements corresponding to the options array
  • multiple: adds the multiple attribute, allowing for multiple options to be selected simultaneously
  • options: an array of objects which correspond to the <option> elements to go inside the <select>; each object should have a text property which renders as the text node inside of the <option> and a value property which is the value of the value attribute on the <option> element<\li><\ul>
  • action: fires on select change
radioButtons renders a set of <input type='radio'> elements corresponding to the options array
  • options: an array of objects which correspond to the <input type='radio'>; each object should have a text property which renders as the text node inside of the <input type='radio'> and a value property which is the value of the value attribute on the <input type='radio'> element
  • action: fires on select change
modalButton renders a button which, when clicked, opens a modal over the current settings tab, containing nested settings
  • text: the text of the <button> element
  • modal: an object with title and contents properties
    • title: the text which is rendered in an <h2> at the top of the modal
    • contents: an array of nested settings which will be rendered inside the modal
  • action: fires on button click
  • modal_done: fires on "done" button click (inside modal)
fileButton WIP

Settings Initialization

(WIP)

Using Settings Values

All values in the settings page are automatically persisted via localStorage objects with the prefix of store.settings. (e.g. store.settings.myButton). You can retrieve the values via javascript, operate on them and ultimately store your chrome extension settings via chrome.storage for use in your extension.

In the sample code of this repo, this logic resides in the settings file as well but could just as easily be factored out.

How To Use (WIP)

  1. npm i --save or something...
  2. add things to your build process...
  3. customize manifest.js
  4. customize settings.js
  5. ...

About

Create fancy, chrome-look-alike settings for your Chrome or Safari extension in minutes!

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 93.7%
  • CSS 5.4%
  • HTML 0.9%