mdb-ui-kit/README.md

176 lines
8.5 KiB
Markdown
Raw Normal View History

[![build status](https://travis-ci.org/FezVrasta/bootstrap-material-design.svg?branch=master)](https://travis-ci.org/FezVrasta/bootstrap-material-design)
2014-11-28 15:09:57 +03:00
[![gratipay](https://img.shields.io/gratipay/FezVrasta.svg)](https://gratipay.com/FezVrasta)
2014-10-03 17:52:14 +04:00
[![banner](demo/imgs/banner.jpg)](#)
2014-08-21 11:48:39 +04:00
This Bootstrap theme is an easy way to use the new [Material Design guidelines by Google](http://www.google.com/design/spec/material-design/introduction.html) in your Bootstrap 3 based application.
Just include the theme, after the Bootstrap CSS and include the javascript at the end of your document (Just before the end of the `<body>` tag), and everything will be converted to Material Design (paper) style.
2014-08-21 11:48:39 +04:00
2014-11-17 15:39:37 +03:00
**NOTE**: This theme is in early development and is not ready for production.
2014-08-21 11:48:39 +04:00
2014-11-17 15:39:37 +03:00
Check out [the demo at this link](http://fezvrasta.github.io/bootstrap-material-design/) (this demo may not be even with the `master` branch).
2014-08-21 11:48:39 +04:00
2014-09-10 11:36:44 +04:00
## How to install
2014-10-03 15:58:24 +04:00
BOWER: bower install bootstrap-material-design --save
2014-10-31 12:06:45 +03:00
## Use our CDN
2014-10-31 16:37:38 +03:00
You can find the CDN of this library at [CDNJS.com](https://cdnjs.com/libraries/bootstrap-material-design) and at [JSDelivr.com](http://www.jsdelivr.com/#!bootstrap.material-design)
2014-10-31 12:06:45 +03:00
2014-10-03 15:58:24 +04:00
### LESS & SASS
We decided to merge the SASS fork in to the main repository instead of having two seperate ones, [#40](https://github.com/FezVrasta/bootstrap-material-design/issues/40). The default grunt
task will compile the LESS source. To use the SASS base use the SCSS task ```grunt scss```.
**NB** The LESS and SASS bases should reflect each other, right now this project is unstable and under heavy development
so this might not be true before the first stable release.
2014-09-10 11:36:44 +04:00
## Getting started
2014-10-28 14:39:33 +03:00
Navigate to the `dist/` folder in this repository, and you will see the `test.html` file, which has the CSS include statements, in the `head` section and the JS includes just before `body` section closes.
You need to copy the `dist/` folder to the root of your project, ensuring that all the files in your project can access the files through the relative URL, supplied in the CSS and the JS includes.
2014-09-10 11:36:44 +04:00
## Development
We are using grunt to automate the workflow and build process. Ensure you have nodejs installed and grunt-cli installed globally.
After cloning the repo, run `npm install` to ensure you have all dev dependencies.
2014-11-17 15:39:37 +03:00
Run the `grunt build` command to run the tests and compile the less/sass. See [Gruntfile.js](Gruntfile.js) for details on targets.
Run the `grunt test` command for browser based jasmine unit tests.
Run the `grunt serve` command to build and fire up a http server with live-reload and a watch for development purposes.
2014-10-03 12:02:21 +04:00
## Todo
2014-09-07 19:37:32 +04:00
- Morphing icons
- [Icons/grids/chips to card/fullscreen transitions](http://www.polymer-project.org/components/core-animated-pages/demo.html)
- [Headers](http://www.polymer-project.org/components/core-header-panel/demo.html)
- [Icon button](http://www.polymer-project.org/components/paper-icon-button/demo.html)
- [Tabs](http://www.polymer-project.org/components/paper-tabs/demo.html)
- [Toggle buttons](http://www.polymer-project.org/components/paper-toggle-button/demo.html)
2014-10-03 15:58:24 +04:00
I'll try to write every component without the need of Javascript but just CSS, and use JS only if strictly needed.
2014-10-03 12:02:21 +04:00
More "todo" things can be found in the ISSUES of this repository.
2014-09-07 19:37:32 +04:00
2014-08-22 17:04:38 +04:00
# Support me
If you like this project you may support me by donating something on Gittip, starring this repository or reporting bugs and ideas in the issue section.
2014-08-22 17:04:38 +04:00
2014-10-31 11:20:24 +03:00
[![gittip](demo/imgs/gittip-button.jpg)](https://www.gratipay.com/FezVrasta/)
[![issues](demo/imgs/issues-button.jpg)](https://github.com/FezVrasta/bootstrap-material-design/issues)
2014-08-21 11:48:39 +04:00
2014-10-02 13:36:05 +04:00
# Contribute
2014-11-17 15:39:37 +03:00
Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
2014-10-03 12:02:21 +04:00
2014-08-21 11:48:39 +04:00
# Documentation
Material Design for Bootstrap provides some additional stuff to get the best from Material Design.
### Variations:
There are 17 additional color variations (in addition to the classic 4 variations) for buttons, inputs, checkboxes, radios, alerts, navbars, tabs, labels, paginations, progress bars and more.
They can be used by adding the class suffix `-material-color` to the desired element and replacing `color` with the desired one.
2014-08-21 11:48:39 +04:00
Example:
<button class="btn btn-material-deeppurple">Deep purple button</button>
These colors are taken from the Material Design color palette and are reported below:
2014-08-21 11:48:39 +04:00
2014-10-31 11:20:24 +03:00
![palette](demo/imgs/palette.jpg)
2014-08-21 11:48:39 +04:00
### Buttons:
2014-09-07 19:13:34 +04:00
Add `.btn-flat` to a button to make it flat, without shadows.
2014-08-21 11:48:39 +04:00
Add `.btn-raised` to a button to add a permanent shadow to it.
### Inputs:
Add `.floating-label` to an input field with a `placeholder` to transform the placeholder in a floating label.
Add `data-hint="some hint"` to show an hint under the input when the user focus it.
2014-08-21 11:48:39 +04:00
Remember to use the proper HTML markup to get radio and checkboxes styled correctly (choose between *radio* or *checkbox*):
<div class="radio/checkbox radio-primary">
<label>
<input type="radio/checkbox" checked>
Option one is this
</label>
</div>
2014-09-07 19:13:34 +04:00
2014-08-26 12:50:52 +04:00
### Icons:
2014-09-07 19:13:34 +04:00
Material Design for Bootstrap includes 490 original Material Design icons!
These icons are extracted from the original Google sources and are licensed under the BSD license.
They are provided as an iconic and easy to use font.
2014-08-26 12:50:52 +04:00
Variations are available for every icon, including the original Bootstrap icons.
2014-08-26 12:50:52 +04:00
The syntax to add a Material icon is:
<i class="icon icon-material-favorite"></i>
2014-10-28 14:39:33 +03:00
2014-10-18 20:12:02 +04:00
# Material.js
2014-11-17 15:39:37 +03:00
`Material.js` is a jQuery plugin that add some magic to your markup and allows Material Design for Bootstrap to style some elements like inputs, checkboxes, radios etc.
2014-10-18 20:12:02 +04:00
### Functions:
This plugin exposes some functions, them are:
2014-10-29 21:59:15 +03:00
`$.material.init()` is a shortcut to run all the following commands.
2014-10-28 14:39:33 +03:00
`$.material.ripples()` will apply ripples.js to the default elements.
`$.material.input()` will enable the MD style to the text inputs, and other kind of inputs (number, email, file etc).
`$.material.checkbox():` will enable the MD style to the checkboxes (remember to follow the markup guidelines explained in the Inputs chapter.
`$.material.radio():` will enable the MD style to the checkboxes (remember to follow the markup guidelines explained in the Inputs chapter.
2014-10-18 20:12:02 +04:00
### Apply Material.js only to specific elements:
2014-10-19 21:49:34 +04:00
Every function expects an optional value that will be used as selector for the function, for example
2014-10-28 14:39:33 +03:00
`$.material.ripples("#selector, #foobar")` will apply Ripples.js only to `#selector` and `#foobar`.
The functions that allows an optional selector are `$.material.ripples`, `$.material.input`, `$.material.checkbox` and `$.material.radio`.
2014-10-19 21:49:34 +04:00
You can even override the default values using the `$.material.options` function, the default values are:
2014-10-28 14:39:33 +03:00
2014-10-18 20:12:02 +04:00
$.material.options = {
"withRipples": ".btn:not(.btn-link), .card-image, .navbar a:not(.withoutripple), .nav-tabs a:not(.withoutripple), .withripple",
"inputElements": "input.form-control, textarea.form-control, select.form-control",
"checkboxElements": ".checkbox > label > input[type=checkbox]",
"radioElements": ".radio > label > input[type=radio]"
}
2014-10-28 14:39:33 +03:00
2014-10-19 21:49:34 +04:00
### Arrive.js support
2014-10-18 20:12:02 +04:00
2014-11-17 15:39:37 +03:00
If you need to dynamically add elements to your DOM then you may need to include `Arrive.js` before `Material.js`, this will automatically apply `Material.js` to every new element added by you using JS.
2014-08-22 17:04:38 +04:00
2014-08-21 11:48:39 +04:00
# Plugins
2014-10-03 17:15:42 +04:00
Material Design for Bootstrap comes with styling support for various external scripts:
2014-08-21 11:48:39 +04:00
### SnackbarJS
Create snackbars and toasts with [SnackbarJS plugin](https://github.com/FezVrasta/snackbarjs). The default toast style is the squared one (snackbar style). If you like to use the rounded style (toast style), please add the `toast` class to the `style` option of SnackbarJS.
2014-08-21 11:48:39 +04:00
### RipplesJS
2014-09-07 19:13:34 +04:00
This is part of Material Design for Bootstrap project and is a plain Javascript script which creates the ripple effect on click of the defined elements.
At the moment RipplesJS does not have its own repository but it will probably have one in the future.
2014-08-25 19:14:52 +04:00
### noUiSlider
2014-09-07 19:13:34 +04:00
Make cross-browser sliders and get them styled with Material Design thanks to the support provided by this theme.
2014-09-29 00:58:04 +04:00
Read more about [noUiSlider here](http://refreshless.com/nouislider/)
2014-08-25 19:14:52 +04:00
2014-10-03 17:15:42 +04:00
### Selectize.js
2014-10-08 02:09:42 +04:00
Transform select and multi select inputs in advanced text inputs. Material Design for BS provides a full replacement of the plugin's CSS, so don't include it.
2014-10-03 17:15:42 +04:00
Read more about [selectize.js](http://brianreavis.github.io/selectize.js/)
2014-08-21 11:48:39 +04:00
# Compatibility
2014-12-01 13:40:50 +03:00
Currently Material Design for Bootstrap supports Google Chrome (tested v37+), Mozilla Firefox (tested 30+), and Internet Explorer (tested 11+). Mobile browsers are not currently tested but it may work.