Skip to content

Latest commit

 

History

History
259 lines (174 loc) · 8 KB

README.md

File metadata and controls

259 lines (174 loc) · 8 KB
Raw

Flat UI for Sass

flat-ui-sass is a SASS port of Designmodo's Flat-UI Free. flat-ui-sass also provides a rake task to convert and locally vendor Flat-UI Pro for use with Rails, Compass, and vanilla SASS.

This gem is currently under development! Things may be broken!

Dependencies

flat-ui-sass requires bootstrap-sass

flat-ui-sass depends on term-ansicolor right now for the logging functionality of the converter. This is on the roadmap for removal.

Flat-UI uses the Lato font as its base font. This gem does not vendor Lato. It is up to you to make sure Lato is available on your page.

Notice:

The preferred version of sass is v3.3.0+. Unfortunately, this version is not supported by sass-rails >= v4.0.2. If you run on sass v3.2.x, the only thing that will not work properly is the color swatch module in Flat-UI Free. The only other difference is in how the Flat-UI asset helper is discovered (see _variables.scss).

Installation

Rails

Add the following to your Gemfile:

gem 'flat-ui-sass', github: 'wingrunr21/flat-ui-sass'

Compass (no Rails, Flat-UI free only right now)

Install the gem:

gem install flat-ui-sass

or add it to your Gemfile:

gem 'flat-ui-sass', github: 'wingrunr21/flat-ui-sass'

For existing projects:

# config.rb:
require 'flat-ui-sass'

bundle exec compass install flat-ui

For new projects:

bundle exec compass create new_project -r flat-ui-sass --using flat-ui

The resulting Compass project will have all Flat-UI JS/fonts/images as well as the bootstrap JS/fonts.

The following SCSS files will also be created:

  • _variables.scss - all of the Flat UI variables (override them here).
  • styles.scss - primary SCSS file, import variables, flat-ui/variables, bootstrap, and flat-ui.

vanilla SASS (no Compass or Rails)

Install the gem:

gem install flat-ui-sass

or add it to your Gemfile:

gem 'flat-ui-sass', github: 'wingrunr21/flat-ui-sass'

Follow the JS and Fonts setup instructions for bootstrap-sass

In addition, you will need to copy font, image, and javascript assets out of flat-ui-sass if you are using Flat-UI Free:

mkdir public/images
cp -r $(bundle show flat-ui-sass)/vendor/assets/images/ public/images
cp -r $(bundle show flat-ui-sass)/vendor/assets/fonts/ public/fonts/
cp -r $(bundle show flat-ui-sass)/vendor/assets/javascripts/ public/javascripts/

If you are using Flat-UI Pro, you can copy or symlink the various assets out of the local vendor/assets directory in the root of your project.

Similar to bootstrap-sass, we provide Ruby methods to report the appropriate paths:

FlatUI.stylesheets_path
FlatUI.fonts_path
FlatUI.javascripts_path
FlatUI.images_path

Usage

Converting Flat-UI Pro

NOTE: Support for Flat-UI Pro (and converting to SASS) is currently only available under MRI 2.0 and above. Users on other Ruby versions can still use Flat-UI Free.

You can use the fui_convert command packaged along with flat-ui-sass to automatically convert and vendor Flat-UI Pro to your local application:

  1. Place the Flat-UI Pro directory (e.g. the one with the less, js, font, image, etc files in it) in a directory at the root of your app titled flat-ui-pro
  2. Run bundle exec fui_convert. You should see a lot of output regarding the conversion process. When it is finished, Flat-UI Pro should be converted and available in the vendor/assets/ directory.

See fui_convert --help for more advanced usage

SCSS

Import the Flat-UI variables, bootstrap, and then Flat-UI:

@import 'flat-ui/variables';
@import 'bootstrap';
@import 'flat-ui';

For Flat-UI Pro, simply import flat-ui-pro instead:

@import 'flat-ui-pro/variables';
@import 'bootstrap';
@import 'flat-ui-pro';

You must import the Flat-UI variables before bootstrap, otherwise bootstrap's variables will take priority!

Missing Modules

Flat-UI Pro does not include a few modules that exist in Flat-UI Free. Designmodo has stated this is because they are not yet mobile-ready. If you still wish to use these modules, you can import them from this gem's version of Flat-UI Free:

@import 'flat-ui/modules/footer';
@import 'flat-ui/modules/login';
@import 'flat-ui/modules/palette';
@import 'flat-ui/modules/share';
@import 'flat-ui/modules/tile';
@import 'flat-ui/modules/todo';

Javascript

Flat-UI has a lot of javascript dependencies. It is up to you to make sure the appropriate javascript files are available in your application. For a reference, check out the bottom of the index.html example page for your version of Flat-UI or the list below.

If you are using Rails or Sprockets, you may require the manifest for all javascript assets:

Free:

//= require flat-ui

Pro:

//= require flat-ui-pro

Alternatively, you may require individual modules as well

Free:

//= require flat-ui/flatui-checkbox
//= require flat-ui/flatui-radio

Pro:

//= require flat-ui-pro/flatui-checkbox
//= require flat-ui-pro/flatui-radio
//= require flat-ui-pro/flatui-fileinput

Here's a list of javascript dependencies in Flat-UI Free:

  • jquery
  • jquery.ui.core
  • jquery.ui.widget
  • jquery.ui.mouse
  • jquery.ui.position
  • jquery.ui.slider
  • jquery.ui.tooltip
  • jquery.ui.effect
  • jquery.ui.touch-punch.min
  • bootstrap
  • bootstrap-select
  • bootstrap-switch
  • jquery.tagsinput
  • jquery.placeholder
  • jquery.stacktable
  • video.js

In addition, Flat-UI Pro also requires:

  • jquery.ui.button
  • jquery.ui.datepicker
  • jquery.ui.spinner
  • typeahead.js
  • holder.js

Icon Helper

A Rails helper is also included to aid with using the Flat-UI glyph icons:

fui_icon "heart"
# => <i class="fui-heart"></i>

fui_icon "heart", tag: :span
# => <span class="fui-heart"></span>

fui_icon "heart", text: "Flat-UI!"
# => <i class="fui-heart"></i> Flat-UI!
fui_icon "arrow-right", text: "Get started", right: true
# => Get started <i class="fui-arrow-right"></i>

fui_icon "photo", class: "pull-left"
# => <i class="fui-photo pull-left"></i>

fui_icon "user", data: { id: 123 }
# => <i class="fui-user" data-id="123"></i>

content_tag(:li, fui_icon("check", text: "Bulleted list item"))
# => <li><i class="fui-check"></i> Bulleted list item</li>

Roadmap

  1. bower support
  2. Tests

Development and Contributing

This gem uses a modified version of the converter utilized in bootstrap-sass. The converter runs over the checked-out Flat-UI git submodule and vendors the resulting files in vendor/assets. The converter does the following:

  • Converts the LESS to SASS, fixing @import orders to load correct under SASS.
  • Generates a flat-ui.scss or flat-ui-pro.scss manifest
  • Copies Flat-UI javascript files and generates a flat-ui.js or flat-ui-pro.js manifest
  • Copies the Flat-UI Icons font
  • Copies supporting Flat-UI images

The converter is located in lib/tasks/

Version numbers for the current versions of Flat-UI and Flat-UI Pro that the converter works against are in version.rb

Developing

  1. Clone this repository to a working directory
  2. Initialize the Flat-UI submodule (git submodule update --init)
  3. Create a new topic branch for your changes (git checkout -b my_new_feature)
  4. Make some changes
  5. Run rake flat_ui:convert to convert Flat-UI and vendor it

Credits

The conversion scripts and general gem structure rely upon and are heavily influenced by the work done on bootstrap-sass. This gem would not be possible without all of the hard work put into that project.

Thanks also go to Designmodo for creating and publishing Flat-UI.