README.md

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. ...