[VUFIND-987] Bootstrap 3 Created: 06/Jun/14  Updated: 25/Aug/14  Due: 01/Aug/14  Resolved: 05/Aug/14

Status: Resolved
Project: VuFind®
Components: User Interface
Affects versions: None
Fix versions: 2.3

Type: Improvement Priority: Major
Reporter: Chris Hallberg Assignee: Chris Hallberg
Resolution: Fixed Votes: 2
Labels: bootstrap
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified


 Description   
Re-construct the Bootstrap theme using Bootstrap 3.

Fork here: https://github.com/crhallberg/vufind/tree/bootstrap3
Feedback ticket: VUFIND-994.

ROAD MAP:
- jQuery update (DONE)
- Full functionality (TESTING)
- Documentation for updating (ONGOING)
    - Move to DokuWiki before 2.3 release
- Bootprint full theming (DONE)

- LESS and SCSS support (DONE)
    - LESS programs in direct paths, not relative ones, making a releasable, pre-compiled CSS a small issue...
    - LESS uses direct paths because of the nature of it being compiled. We'll just have to be careful about what we include in release.
- LESS and SCSS theming (DONE)
- LESS and SCSS bootprint theming (DONE)
- LESS and SCSS command line tools (DONE)
    - Integrate with install (CANCELLED)

- TESTING (Ongoing)

- New functionality (31 July)
  - jsTree updates (Trying for types) (DONE)
    - Thanks for Ere Maijala for his work on this
- LESS/SCSS compile script (DONE)

- MORE TESTING

Progress:
- See comments

Current Release Plan (TBF):
- 2.3 - themes "bootstrap" and "bootstrap3"
- 2.4 - remove "bootstrap"

 Comments   
Comment by Chris Hallberg [ 10/Jun/14 ]
First step was a regex to switch all the columns from 'spanx' to 'col-sm-x'. -sm- because this works down to tablet width before switching (http://getbootstrap.com/css/#grid-options), complying with VUFIND-967.

There are a few places where the span value was set programmatically, such as TopFacets and Combined search, that may need to be fixed by hand.

There are a few "offsetx" classes in Bootstrap, but these were/will get replaced with the form overhaul.
Comment by Chris Hallberg [ 10/Jun/14 ]
Next 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>

I need to make sure this is consistent everywhere.
Comment by Chris Hallberg [ 10/Jun/14 ]
NEW HEADER.

All one line on extra large displays, with a hidden second searchbox for smaller displays and responding. Respond or switch to Bootprint 3 for the difference. Bootprint 3 enables the lower box all the time using pure CSS.
Comment by Chris Hallberg [ 10/Jun/14 ]
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"
Comment by Chris Hallberg [ 16/Jun/14 ]
CUSTOM BOOTSTRAP AND BOOTPRINT

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 BS CSS can be created using variables provided in LESS and SCSS.

LESS/SCSS users: I was successful in creating a custom Bootstrap by tweaking variables.less/scss and @importing it in my bootprint less.

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

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

If you think I should use the custom Bootstrap css in the regular Bootstrap theme (minus colors), please let me know. This could be to cut down on large unused features (carousel, et al) or tweak styling that affect a universal standard of visual appeal. Do so at VUFIND-994.
Comment by Chris Hallberg [ 16/Jun/14 ]
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 in our theme is thus:

<form class="form-horizontal">
    <input type="hidden"/>
    <input type="hidden"/>
    ...
    <div class="form-group">
        <label class="col-sm-2 control-label"></label>
        <div class="col-sm-10">
            <input/> or <select> or <p class="form-control-static">Set 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.
Comment by Chris Hallberg [ 16/Jun/14 ]
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. There are also a few icons that were renamed and I'll add them here as I find them.

> -remove to -delete
> -trash to -trash-o
> -signin to -sign-in
> -signout to -sign-out
Comment by Chris Hallberg [ 23/Jun/14 ]
LESS and SCSS

SETUP
Write permission needs to be given to these folders for LESS/SCSS to work:
- [theme] / [less/scss] / cache
- [theme] / css / [less/scss]

MAGIC
Configure in theme.config.php
Comment by Chris Hallberg [ 24/Jun/14 ]
ACCESSIBILITY

PayPal has a wonderful Bootstrap extension that I've added to Bootstrap. They also have a great a11y theme that I used, but it was fully supported in LESS alone, so the contrast and some padding is different in LESS than it is in CSS and SCSS.
Comment by Chris Hallberg [ 30/Jun/14 ]
HIDDEN AND HIDE

Oh, boy. Bootstrap switched from .hide to .hidden for its Class of Invisibility, COI for short. The biggest problem is that this puts it out of jive with jQuery, which still uses .hide as its COI.

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.

That should fee-- fix the COI.
Comment by Chris Hallberg [ 01/Jul/14 ]
LESS/SCSS THEME INHERITANCE

This is a bit tricky, so the following is my current understanding of it, to be corrected as I learn. We are researching how to handle mixed inheritance.

CSS inheritance is pretty straight forward in VuFind: name your CSS file the same if you want to override the parents', different if you want to extend. In LESS/SCSS, you can import other files into your stylings, which is INSANELY useful for things like Bootstrap because of all the variables. Being able to use those variables to color and size things correctly is crucial.

In order to utilize the power of imports and the power of inheritance, here's what's going on in the Bootstrap 3 and Bootprint 3 themes.

Bootstrap3
- bootstrap.less (pulls in the bootstrap library, contains all customizations, ala bootstrap-custom in Bootstrap2)
- compiled.less (only imports bootstrap.less, included in theme.config.php)
- font-awesome (pulls in FA library, could be imported, included in theme.config.php)
- a11y.less (Accessibility theme, included into bootstrap.less)

Bootprint3
- bootprint.less (contains all stylings for Bootprint, ala bootprint-custom in Bootprint2)
- compiled.less (imports bootstrap.less and bootprint.less, included in theme.config.php)
- icons.less (FA icon overwrites, included in theme.config.php)
- variables.less (tweaking of Bootstrap variables, imported into bootprint.less)

Core will essentially contain a list of parents' LESSes. Doing this will prevent n Bootstrap instances from occuring, where n is the depth of your theme from root on Bootstrap 3's direction. Wow, I'm a nerd.
Comment by Chris Hallberg [ 03/Jul/14 ]
LESS COMMAND LINE COMPILER
php util/cssBuilder.php

This will use the Less Parser to compile your LESS into css files in the regular css folder. These can then be used as regular css files, but more importantly, these will be used as fall-back in case of a LESS parser error. So compile regularly!

Also, it only compiles active LESS sheets in your theme, so check your theme.config.php before compiling!
Comment by Chris Hallberg [ 07/Jul/14 ]
CSS TIP

Bootstrap can be hard to theme sometimes because of how specific the classes are. One easy way around this is using the !important modifier for css rules. Just an FYI.
Comment by Demian Katz [ 11/Jul/14 ]
Chris, should we add a comment here about "danger" classes?
Comment by Chris Hallberg [ 11/Jul/14 ]
In what I consider a misleading move, Bootstrap label-important and alert-error have become -danger. I don't like it either. Here's a list of a few to watch out for.

> unstyled to list-unstyled
> label-important to label-danger
> alert-error to alert-danger
> noprint to hidden-print

Full list here: http://getbootstrap.com/migration/#classes
Comment by Chris Hallberg [ 25/Aug/14 ]
I moved and reorganized all of this documentation on the wiki: https://vufind.org/wiki/bootstrap_migration
Generated at Fri Mar 29 09:43:03 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100248-rev:6a03a54452e975225e04dfda06fdac6fd9e95b00.