Reform - HTML forms the way you want them
Have you spent the last 15 years wishing browsers wouldn't force their style on your HTML elements? How many times did you want to style a check box or a select box as if they were divs? I thought so.
Instructions
All the files you need are in the build
folder.
- Download
reform.js
(orreform.min.js
) and include it in your HTML file. - Optionally, download and include
reform.css
for default style (recommended). - Whenever you want custom form elements, do this:
- Add
reform-checkbox
class toinput[type=checkbox]
elements - Add
reform-selectbox
class toselect
elements - Add
reform-multilineselectbox
class toselect
elements - Add
reform-autocompletebox
class toinput[type=text]
elements - Add
reform-autocompletecombobox
class toinput[type=text]
elements
- Define your own CSS for "reformed" form elements or override the defaults in
reform.css
Dependencies
- jQuery 1.7+
How it works
Reform will hide original elements and wrap them in "fake" elements, which are just plain divs. It will copy all your classes from the original to the fake element and replicate the behavior of the original element by setting special classes on the fake element (e.g. checked
, selected
, disabled
). The state is automatically synchronized between the fake and the original, so you can trigger events and set values on the original elements without worrying about the fake element.
Check box
Original:
will become:
For disabled original elements, fake elements will get the disabled
class. For checked original elements, they will get the checked
class.
checked
state changes
Handling ;
Select box
Original:
One Two
will become:
One Two Pick a number
Again, for disabled original elements, fake elements will get the disabled
class.
Another div -- options container -- is attached to the body
element and initially hidden.
Once the fake element is clicked, the options container is populated and shown:
One Two
The options container div is automatically positioned. When an item is selected, it gets the selected
class. You may have also noticed that, if you specify the attribute data-options-class
on the original element, the value of that attribute will be set as a class on the options container div.
Multiline select box
The multiline select box is basically a select box with support for a description line in the list of options. Simply add a data-desc attribute to the option tag.
Autocomplete box
Original:
Will become:
Optional input field parameters:
- data-url
- data-placeholder-text
- data-case-sensitive
- data-highlight-titles
- data-highlight-selection
- data-min-chars
- data-delay
- data-show-arrows
Default json format is:
For performance reasons results retrieved from a server are cached. Also delay is used if dooing ajax requests.
Once autocomplete detects results the options container is shown:
example1 example2 ...
Autocomplete combobox
Original:
Will become:
Select an item...
Optional input field parameters:
- data-url
- data-placeholder-text
- data-case-sensitive
- data-highlight-titles
- data-highlight-selection
- data-min-chars
- data-delay
- data-show-arrows
- data-empty-selection-text
- data-empty-text
Default json format is:
Once autocomplete detects results the options container is shown:
Select an item... example1 example2 ...
The Autocomplete combobox acts like a regular combobox with an addition to filter options. Just like with comboboxes only availbale options can be selected while custom inputs are not possible. If you need custom inputs you should use the Autocomplete box instead.
NPM package
To use Reform as a CommonJS module (e.g. to use some Node.js tool, such as Browserify, to package your app), you should install the NPM module:
npm install reform
You can then require Reform:
Reform = ;
To use it in your application, you should instantiate a Reform object:
reform = ;
You can then either process nodes individually:
reform;
The easy way is just to "observe" the DOM for any custom controls being inserted:
reform;
You can register new extended component before observing:
reform;
Development
- You need Node.js
- Install
gulp
withnpm install -g gulp
- Run
npm install
to install all the dependencies - Source files are located in
src
andless
for CoffeeScript and LESS, respectively. - Tests are located in
test
. You can run them by openingtest/index.html
in the browser. Before you'll ned to rungulp test
to build test scripts. - Run
gulp
to buildreform.js
andreform.css
and watch for changes - Before pushing new build to
npm
repository, rungulp build
.
Themes branch
In the themes branch we have additional themes for input components.
Check out the branch and see how it's done.
Example structure for pure theme:
/less
|-/themes
/pure
|- index.less
|- checkbox.less
|- ...
|- theme-pure.less
Be sure to add compiling of a theme in gulpfile.coffee
and include it to demo/html file to see the results.
Deploy new version to GitHub
Workflow
git checkout npmgit merge master # or the branch you want to deploy gulp buildgit push origin npm
Static Ruby server
You can add this alias to your dotfiles.
alias server='ruby -run -e httpd . -p5000'
And from here you can run server
from this directory and open
http://localhost:5000/demo/index.html for Reform demo.