diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fde344f --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Webstorm workspace files, etc. +.idea \ No newline at end of file diff --git a/README.md b/README.md index 9fe20c9..bea6357 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,111 @@ -# [Fancy Settings 1.2](https://github.com/frankkohlhepp/fancy-settings) +Fancy Settings 1.2 +================== + *Create fancy, chrome-look-alike settings for your Chrome or Safari extension in minutes!* -### Howto -Welcome to Fancy Settings! Are you ready for tabs, groups, search, good style? -Let's get started, it only takes a few minutes... -[Getting started](https://github.com/frankkohlhepp/fancy-settings/wiki) -[View Sample](http://frankkohlhepp.github.com/fancy-settings/) +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](#setting-types) that one need only to edit [the "Manifest" +(`/source/manifest.js`)](#the-manifest) and the [settings initialization script (`/source/settings.js`)](#settings-initialization) +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](#setting-types) below + * `label` _(optional)_: The text of a `