![Edge Framework](http://cdn.setyono.net/edge/logo.jpg)

EDGE FRAMEWORK
==========================

Edge is a light-weight responsive Sass framework. No gimmick, just the barebone to build modern website.

It is based on [Foundation by ZURB](http://www.zurb.com).

**OUR PHILOSOPHY**

My personal preference is to have a framework not do something and implement it myself than have a framework do something and figure out how to do the opposite.

INSTALLATION
-----------------

    gem install edge_framework

Windows PC doesn't come with Ruby pre-installed, so you can follow [this Ruby installation guide](https://docs.google.com/document/d/155e-Dx4SnQj_bMrM24kI4_ZEmBp-TQ_tuinhMvZsIhM/edit?usp=sharing) we wrote.

After you installed Ruby, type in the command above on `cmd` (command prompt).

BROWSER SUPPORT
------------------

All modern browsers:

- Chrome, Firefox, Safari, Opera
- Android 4.0 and above
- IE 9 and above

GRID SYSTEM
==================
    .row
    .column
    .large-x
    .small-x

Our Grid is divided into **12 columns**. Start with "row" followed by "column" used in conjunction with its width.

    <div class="row">
      <div class="large-8 column"></div>
      <div class="large-4 column"></div>
    </div>

![Edge Grid - Large only](http://cdn.setyono.net/edge/grid-large.jpg)

    <div class="row">
      <div class="large-8 small-6 column"></div>
      <div class="large-4 small-6 column"></div>
    </div>

![Edge Grid - Large and Small](http://cdn.setyono.net/edge/grid-large-small.jpg)

The element doesn't have to be div, it can be section, article, header, etc.

Sizing:

- Large - above 768px

- Small - below or equal to 768px, width will be 100% if not specified.

**Convention**:

- Don't add your own style to the `.row` and `.column` elements.

Nesting
-----------

    <div class="row">
      <div class="large-8 column">
        <div class="row">
          <div class="large-2 column"></div>
          <div class="large-10 column"></div>
        </div>
      </div>
      <div class="large-4 column"></div>
    </div>

![Edge Grid - Nesting](http://cdn.setyono.net/edge/grid-nesting.jpg)

Collapse
-----------

    .row.collapse

Remove the gutter.

    <div class="row collapse">
      <div class="large-9 small-6 column"></div>
      <div class="large-3 small-6 column"></div>
    </div>

All nested rows inside collapsed one will be collapsed too.

![Edge Grid - Collapse](http://cdn.setyono.net/edge/grid-collapse.jpg)

Centering
-----------

    .centered
    .small-centered

Horizontally centering a column.

It is inherited on small screen.

    <div class="row">
      <div class="large-7 small-7 centered column"></div>
    </div>

![Edge Grid - Centered](http://cdn.setyono.net/edge/grid-centered.jpg)

Offset
-----------

    .offset-x
    .small-offset-x

Offset leaves a **gap** before the column.

It is ignored on small screen unless the small sizing is specified.

    <div class="row">
      <div class="large-2 column"></div>
      <div class="large-6 offset-4 column"></div>
    </div>

![Edge Grid - Offset](http://cdn.setyono.net/edge/grid-offset.jpg)

Column Ordering
-----------------

    push-x
    pull-x

**Push** pushes the column to the right, while **Pull** pulls it to the left.

They are ignored on small screen.

**Example**:

Create a sidebar that is located on the left. But if viewed with phone, it is on the bottom.

    <div class="row">
      <main class="large-8 push-4 column"></main>
      <aside class="large-4 pull-8 column"></aside>
    </div>

The snippet above will look like this:

![Edge Grid - Ordering](http://cdn.setyono.net/edge/grid-ordering.jpg)

GRID SYSTEM - TILE
=================

    ul.tile-x
    ul.small-tile-x

Evenly divides the list into block size.

    <ul class="tile-3 small-tile-2">
      <li>1</li>
      <li>2</li>
      <li>3</li>
      <li>4</li>
      <li>5</li>
    </ul>

![Edge Grid - Tile](http://cdn.setyono.net/edge/grid-tile.jpg)

Each tile will expand 100% on small screen when the small size is not specified.

Just like row, you can collapse it:

    <ul class="tile-7 collapse"> ... </ul>

**Convention**:

- In your own stylesheet, don't name a class that contains the word "tile".

- Don't add your own style to the `.tile` and `.tile > li` elements.

TYPOGRAPHY
======================

Outside of CSS reset, we don't offer much feature regarding Typography.

Default Unordered list (ul) has bullet point, but most of the time we don't need it. So, we made a convention on how to write `ul`.

Without class

    <ul>...<ul>
    
    Result:
    • List 1
    • List 2
    • List 3

With any class

    <ul class="something">...</ul>
  
    Result:
    List 1
    List 2
    List 3

If you want horizontal list, add `.inline-list` class.

    <ul class="inline-list">...</ul>
    
    Result:
    List 1 List 2 List 3

VISIBILITY
==================

    .hide-for-<size>
    .show-for-<size>

    <size> = large / small / mini

**Hide** means hidden only on that size. **Show** means visible only on that size.

Sizing:

- Large - above 768px

- Small - below or equal to 768px

- Mini - below or equal to 480px

**VISIBILITY SCALE**

    0-----480-----768------------->

    |-mini-|

    |----small-----|

                   |----large----->

Notice that small size includes the mini portion too.

**VISIBILITY TABLE**

    ✓ = visible

                       Large  Small  Mini

    .hide-for-large      -      ✓     ✓
    .hide-for-small      ✓      -     -
    .hide-for-mini       ✓      ✓     -

    .show-for-large      ✓      -     -
    .show-for-small      -      ✓     ✓
    .show-for-mini       -      -     ✓

From the table, we can see that some classes like `.hide-for-large` and `.show-for-small` have same result. It is up to your preference on which word makes more sense.

EXAMPLE
--------------
    
Sidebar hidden on mini screen

    <aside hide-for-mini"></aside>

Slider visible only on large screen
    
    <div role="banner" class="show-for-large"></div>
    // or
    <div role="banner" class="hide-for-small"></div>

BOILERPLATE GENERATOR
========================

Generate basic template for your project. Run this command inside your project directory:

1. Static HTML

    `edge create html`

2. Wordpress 3.8+ (Min PHP 5.3)

    `edge create wordpress`

3. Rails (run inside Rails project)

    `rails g edge:install`

4. Coming soon: Sinatra and Flask


WORDPRESS
====================

![Edge Wordpress](http://cdn.setyono.net/edge/wp-edge.jpg)

Features:

- Auto add header and footer.
- Independent from any plugin.
- Cleaner WP Query call.
- Easily create custom post type and taxonomy.

Custom WP Query
---------------------

    Post::find()
        get all posts.

    Post::find($args_array)
        get post(s) based on the arguments array.

    Post::find_by($key, $value)
        faster way of writing Post::find(array( $key => $value ))

All of the functions above returns `WP_Query()` object. [Refer here](https://gist.github.com/luetkemj/2023628) for available argument.

Example:
    
    $posts = Post::find_by("category_name", "featured");
    
    if( $posts->have_posts() ):
      while( $posts->have_posts() ): $posts->the_post();
        ...
      endwhile;
    endif;


Custom Post Type
--------------------

![Wordpress Custom Type](http://cdn.setyono.net/edge/wp-post-type.jpg)

    add_post_type( $name, <$icon>, <$taxonomy> )

Inside `functions.php`, add these codes:

    add_post_type("Product", "cart", "Brand");
    add_post_type("Event", "calendar");

The icon name is taken from [melchoyce.github.io/dashicons/](http://melchoyce.github.io/dashicons/).

To enable custom WP Query, create a class with the Post Type's name that extends `Post`.

    // still inside functions.php

    class Product extends Post {}
    class Event extends Post {}

Now, you can use the custom WP Query:

    $products = Product::find_by("brand", "Microsoft")
    $events = Event::find()

**Alert**: If you want pagination to work, the Name cannot be the same as any page's slug.

Template File
---------------

The template file for custom post is `single-{slug}.php` while custom taxonomy is `taxonomy-{slug}.php`.

Based on the example above, create `single-product.php` for single **Product** template. If we need to list all products within a brand, create `taxonomy-brand.php` which works the same way as `category.php`.

Naming Convention
-----------------

All names must be **singular**.

No special character except space. If contain space, the class' name should be its combined word and no camel casing.

    add_post_type("Photo Gallery", "format-gallery");

    class Photogallery extends Post {}

COMPASS
=================

![Edge Compass](http://cdn.setyono.net/edge/compass-edge.jpg)

The generated template includes **config.rb** for Compass. So, we can compile it using the command:

    compass watch

Inside the template, go to `assets/sass/` and you will see `_settings.scss`. This file overrides the default styling like primary color or column's gutter.

Just uncomment the variable and change the value. For example:

    // $column-gutter : 20px;

Become:

    $column-gutter : 30px;

EM Converter
===============
    
    .post p {
      font-size: em(14px);  
    }

    // Result
    .post p {
      font-size: 0.875em;
    }

The default em size is 16px. It is defined in variable `$body-font-size`.

If the base size is not default, pass it as second parameter:
    
    <h1 class="title">
      Hello <em>World</em>
    </h1>

    .title {
      font-size: em(40px);

      em {
        font-size: em(45px, 40px);
      }
    }

GRID - mixin
======================
  
    row()
      $gutter   : px    - Gutter for columns inside this row
      $width    : px    - The row's max width.
      $collapse : bool

    column()
      $size    : int    - The large sizing
      $small   : int    - The small sizing
      $mini    : int    - The mini sizing (below 480px)
      $offset  : int
      $push    : int
      $pull    : int
      $collapse : bool
      $centered : bool
      $gutter   : px
      $total    : int   - Total number of columns
      

Custom grid makes the markup cleaner and easier to change.

    // HTML
    <div class="row">
      <aside class="column"></aside>
      <main class="my-col column"></main>
    </div>


    // SCSS
    aside.column {
      @include column(2, 4, 12);
      // or
      @include column($size: 2, $small: 4, $mini: 12);
    }

    .my-col {
      @include column(10, 8, 12);
      // or
      @include column($size: 10, $small: 8, $mini: 12);
    }

**Convention**:

- Custom column must be applied to the element that has `column` class. The same goes to custom row.

### GUTTER

Custom gutter must be applied to both row and column.

    // HTML
    <div class="my-row row">
      <aside class="column"></aside>
      <main class="my-col column"></main>
    </div>


    // SCSS
    .my-row {
      @include row($gutter: 50px);
    }

    aside.column {
      @include column($size: 2, $gutter: 50px);
    }

    .my-col {
      @include column($size: 10, $gutter: 50px);
    }

### COLLAPSE

Collapse must be applied to both row and column.
    
    .my-row {
      @include row($collapse: true);
    }

    .my-col {
      @include column($size: 10, $collapse: true);
    }

### TOTAL COLUMNS

You can either use `$total` parameter or fraction:

    .my-col {
      @include column($size: 7, $offset: 3, $total: 15);
    }

    // or

    .my-col {
      @include column($size: 7 / 15, $offset: 3 / 15);
    }

GRID PIXEL *beta
===============

    column-px()
      $size     : px
      $width    : px
      $gutter   : px
      $centered : boolean

Let's say a designers gives you a design that doesn't follow grid system. Here's an example:

![Pre-given Design](http://cdn.setyono.net/edge/custom-total-column.jpg)

With `column-px()` mixin, we can create that layout easily:

    // HTML
    <div class="my-row row">
      <main class="my-col column"> ... </main>
      <aside class="side-col column"> ... </aside>
    </div>

    // SCSS
    .my-row {
      @include row($gutter: 35px);
    }

    .my-col {
      @include column-px($size: 500px, $width: 735px, $gutter: 35px);
    }

    .side-col {
      @include column-px($size: 200px, $width: 735px, $gutter: 35px);
    }

TILE - mixin
======================

    tile()
      $size     : int
      $small    : int
      $mini     : int
      $gutter   : px,
      $collapse : bool

Mini sizing is available for tile's mixin too.

    <ul class="products"></ul>

    .products {
      @include tile($size: 7, $small: 4, $mini: 2);
      
      // or
      
      @include tile(7, 4, 2);
    }

MEDIA QUERY - mixin
=========================

    below($size)
    above($size)
    between($smaller-size, $larger-size)
    
    $size = large / small / mini

**Below** means less than or equal to (`<=`).

**Above** means more than (`>`).

**Between** is inclusive to both (`>= smaller-size` and `<= larger-size`).

    p {
      color: black;

      @include above(small) {
        color: blue;
      }

      @include below(small) {
        color: yellow;
      }
    }

You can use pixel too:

    p {
      color: black;
      
      @include above(850px) {
        color: pink;
      }

      @include between(300px, 400px) {
        color: green;
      }
    }

VISIBILITY - mixin
========================

We don't offer mixin for visibility. Use media query instead:

    .sidebar {
      @include below(small) {
        display: none;
      }
    }

RAILS
=================

![Edge Rails](http://cdn.setyono.net/edge/rails-edge.jpg)

Gemfile:

    gem 'sass'
    gem 'sass-rails', '~> 4.0.0'
    gem 'compass-rails'
    gem 'edge_framework', '~> 1.2'

Template generator:

    rails g edge:install

The command will give you Edge's SCSS files and append the pipeline.

FAQ
===============

1. Why should I use Edge over leading frameworks like Boostrap or Foundation?

  Edge leans toward those who create website based on designer's wireframe/mockup.

  Bootstrap and Foundation offer pre-styled elements which are great for quick prototyping. But when you are working with a designer, you won't use any of those styling.

2. Is Edge a mobile-first framework?

  No it is not.