VuFind Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Bootstrap 2.x to 3.x Migration ======
When the experimental "bootstrap" theme was replaced with the stable "bootstrap3" theme, we moved to a newer version of the Bootstrap CSS framework, which introduced substantial changes. This page is designed to help users who built local customizations on top of "bootstrap" to migrate over to "bootstrap3."

===== Column System Update =====
The most sweeping update was the change in the column system. There was a move from "spanx" columns to a "col-size-x", allowing different layouts at different widths. VuFind uses 'col-sm-x" because it maintains the layout down to and including the tablet size, before resizing for mobile.

First step towards BS3 is a regex to switch all the columns from "spanx" to "col-sm-x". There are a few places where the span value was set programmatically, such as TopFacets and Combined search, that will need to be fixed by hand. (The below worked for me (Anna); your mileage may vary)

  $ cd themes/<mytheme>/templates
  $ find . -type f -print0 | xargs -0 sed -i -r 's/span([0-9]+)/col-sm-\1/g'

There are a few "offsetx" classes in Bootstrap, but these were/will get replaced with the form overhaul.

In addition, the "visible-" and "hidden-" helper classes were changed to their xs/sm/md/lg equivalents.

  <span class="visible-xs">This message is only visible on phones</span>
  <span class="visible-sm visible-xs">You're carrying your computer right now, aren't you?</span>
  <div class="hidden-lg">We don't need this on very large monitors.</div>  
  
Each size takes effect at a certain screen width, and we strongly encourage leveraging these classes, and using these sizes in your templates.

^ Class   ^ Bounds         ^ CSS                                               ^ Media          ^
| **-xs** | ≤ 767px        | @media (max-width: 767px)                         | Phones         |
| **-sm** | 768px - 991px  | @media (max-width: 991px) and (min-width: 768px)  | Tablets        |
| **-md** | 992px - 1199px | @media (max-width: 1199px) and (min-width: 992px) | Desktops       |
| **-lg** | ≥ 1200px       | @media (min-width: 1200px)                        | Large Desktops |

And for all you LESS users: 
^ Bootstrap Variable ^ Value  ^
| @screen-xs         | 480px  |
| @screen-sm         | 768px  |
| @screen-md         | 992px  |
| @screen-lg         | 1200px |

Bootstrap's @screen- variables also have a -min variant, which is usually equal, and a -max variant, which is usually one less. For example:
^ Bootstrap Variable ^ Value ^
| @screen-sm         | 768px |
| @screen-sm-min     | 768px |
| @screen-sm-max     | 767px |

===== Customizing Bootstrap =====
Bootstrap 3 offers a tool to customize your build of Bootstrap, available here: [[http://getbootstrap.com/customize/]]

Customizing Bootstrap itself will prevent some visual anomalies that plagued the Bootprint 2 theme, namely extremely tall inputs and wide padding. Bootstrap's classes can be hard to override because of how powerfully specific they are. A custom BS3 CSS can be created using variables provided in LESS and SCSS. You can also change the responsive trip points, as seen in the tables above.

LESS users: I was successful in creating a custom Bootstrap by tweaking variables.less and @importing it. See this in action in the bootprint3 theme.

For those not using LESS, I had equal success [[http://getbootstrap.com/customize/|creating a custom CSS download]], although the work-flow is significantly slower.

The new Bootprint 3 theme uses a unique, custom version of Bootstrap 3 but all the templates are from the Bootstrap 3 theme. Icons are replaced via icons.[css/less].

===== Obsolete CSS classes =====
In what I consider a misleading move, Bootstrap's "label-important" and "alert-error" have become "label-danger" and "alert-danger". I don't like it either. Here's a list of a few more changes to watch out for.

  * .unstyled to .list-unstyled
  * .noprint to .hidden-print

Full list here: [[http://getbootstrap.com/migration/#classes]]

The biggest one of these is the change from "hide" to "hidden". This is a major problem because this doesn't jive with jQuery, which still uses .hide as its Class Of Invisibility.

First, convert all "hide" classes in templates to "hidden".
Second, convert all ".show()" and ".hide()" jQuery calls in the JS to ".removeClass('hidden')" and ".addClass('hidden')", respectively.

This is different from the "hidden-" changes listed above.

===== Sidebars =====
With the removal of .nav-list, I redid the sidebars, converting them from the obsolete .nav-list to collapsible .list-groups.

After a few iterations, I found the simplest syntax for this:

  <ul class="list-group" id="side-panel-[title] ?>">
    <li class="list-group-item title" data-toggle="collapse" href="#side-collapse-[title]">
      [label]
    </li>
    <div id="side-collapse-[title]" class="collapse<? if(collapsedFacet): ?> in<? endif ?>">
      [ list content ] as
        <li class="list-group-item"> or
        <a class="list-group-item" href=""> or
        <label class="list-group-item"><input/> Label</label>
    </div>
  </ul>

===== New Forms =====
The largest amount of work for the update (before new features) is the port to the new forms layout. Horizontal forms, as BS calls them (http://getbootstrap.com/css/#forms-horizontal), are forms where the labels are to the left of the input, a bunch of these pairs in a list.

The old system used custom CSS, while the new system relies of the column system directly. The proper format for horizontal forms (forms where the labels are next to and inline with their inputs) is thus:

  <form class="form-horizontal">
    <input type="hidden"/>
    <input type="hidden"/>
    ...
    <div class="form-group">
      <label class="col-sm-2 control-label">Your Label Here</label>
      <div class="col-sm-10">
        <input/> or <select> or <p class="form-control-static">static value</p>
      </div>
    </div>
    <div class="form-group">
    ...
    </div>
    <div class="form-group">
      <div class="col-sm-offset-2 col-sm-10">
        <input class="btn btn-primary" type="submit"/>
      </div>
    </div>
  </form>

Some forms use col-sm-3 and col-sm-9 to give longer labels (to my English eye) a little more room.

===== Font Awesome Update =====
This update was a bit annoying, but a regex solved it. Font Awesome (which provides Bootstraps icons) switched from classes of "icon-thing" to "fa fa-thing". Regex for class="icon- to class="fa fa- does 95% of the work. If your custom JS or CSS uses classes, make sure you update your icons there too. I did something like:

  grep -rl 'class="icon-' themes/yourtheme/templates | xargs sed -i 's/class="icon-/class="fa fa-/g'
  
Run just the grep part first to make sure you don't catch anything you don't mean to.

There are also a few icons that were renamed and I'll add them here as I find them.

  * -remove to -times (though it appears -remove was kept as an alias)
  * -trash to -trash-o
  * -signin to -sign-in
  * -signout to -sign-out
  * -ok to -check

A full list of icon changes can be found here: [[https://github.com/FortAwesome/Font-Awesome/wiki/Upgrading-from-3.2.1-to-4]]

===== New Header =====
The header at the top of every page has been updated to be a modern, one-line navigation bar. For smaller displays, there is a second, hidden searchbox which can be toggled as on all the time via CSS (maybe a configuration in the future). See Bootprint 3 for an example of this.

===== HTML5 Elements and Roles =====
New over arching layout:
  <body>
    <div class="container">
      <header role="banner" class="navbar hidden-print">
        <?=$this->render('header.phtml')?>
      </header>
      <nav class="nav searchbox hidden-lg hidden-print">
        <?=$this->layout()->searchbox ?>
      </nav>
      <ul class="breadcrumb hidden-print"></ul>
      <div role="main"></div>
      <footer role="contentinfo" class="hidden-print"></footer>
    </div>
    <div id="modal"></div>
  </body>

Additional roles:
  * Search forms (basic and advanced) - role="search"
  * Sidebars - role="complementary"
  * Logo - role="logo"
  * Dropdowns - role="menu"
  * Scattered non-button/input elements (needs research) - role="button"

====== Using LESS ======

See [[development:architecture:less|Using LESS]] for background information.
===== Setup =====
Write permission needs to be given to a new folder for LESS to work: [theme]/css/less/

Configure in theme.config.php:
  "less" => array(
    "active" => true/false,
    "compiled.less"
  ),

For now, every LESS theme needs a compiled.less which "@import"s a custom theme.less or a parent.less.