Migrating from Version 2 to Version 3

---

So what's involved in migrating from version 2 to version 3 then? In truth, not a great deal actually.

Despite the many changes, there's still not a huge amount to actually change, and the changes you do need to make are generally just class renames where applicable.

One of the things you might want to do, especially if you've been using BS only for general web app development and not mobile or any kind of responsive design, is to disable the responsive features in BS3.

This is easy enough to do, but not at all recommended.

You can achieve this as follows:

1. Do not add the meta tag containing the device width and other initial sizing info to the head of your document.
2. Do override the 'width' on your elements that are marked up with a class of 'container' and make sure you use 'style='width: xxx !important' when you do so.
3. Do make sure that any width overrides are processed AFTER the main bootstrap CSS rules have been loaded.
4. Do remove ALL collapsing and expanding behaviors and rules from ALL nav bar constructs within your document.
5. Do change all grid layout classes to use ONLY 'col-xs-*' classes and none of the other 4 levels.

If your targeting IE8 and IE9 you will still need to make sure you use respond.js even if you do disable responsiveness like this.

Class changes

As I mentioned earlier there's been a lot of class name changes between the 2 versions, there's also been a lot of classes deprecated and withdrawn.

One thing that will (and has if you look at Stack Overflow) come as a surprise to many is the withdrawal of the fluid width classes.

In version 2 if you wanted to do a full width elastic container, then you had to do something like the following:

<div class="container-fluid" id="myParentContainer">

  <div class="row-fluid" id="mycontentrow">

    <h1>A headline</h1>

    <p>Some paragraph text</p>

  </div>

</div>

Code Snippet 1: Version 2 flexible container

In version 3 the container and row fluid classes no longer exist.

So how do you get a fluid container? Simple, you don't.

Rather than wrap your contents in a container then a row, you simply don’t wrap them in anything.

You can still use the grid system to provide enclosing containers for your content, so that things line up nicely with Bootstrap’s grid, but you no longer need to put a container around those collections of divs before you use them.

In fact, if you use container and row (the non-fluid versions still exist) then you'll end up with all your content being in the nice 1024 pixel central column automatically, and be able to use the entire page width if you do not.

Migrating the grid system

Then next biggest class change then is the grid system itself.

In version 2 you typically created grids in the following manner:

<div class="container">

  <div class="span2">Content here</div>

  <div class="span10">Content here</div>

</div>

Code snippet 2: version 2 grid classes

The above code would give you 2 containers, that neatly filled the 12 grid squares horizontally that all layouts had, typically a side bar.

In version 3, the 'medium level' grid is now the equivalent of the v2 span classes, so to re-write the above code for V3 you simply do the following:

<div class="container">

  <div class="col-md-2">Content here</div>

  <div class="col-md-10">Content here</div>

</div>

Code snippet 3: version 3 grid classes equivelent to 'span'

However, whereas version 2 had only one level of grid size, version 3 now has 4. Each level is tailored for the expected main target device that you anticipate your end product will be running on.

These grid units are now named as follows:

• Extra small devices = col-xs-*
• Small devices = col-sm-*
• Medium devices = col-md-*
• Large devices = col-lg-*

Media queries are used internally for BS3 to decide just which of the aforementioned grid classes to use, and the different sizes are defined as follows:

For a device to be 'Extra small' its display width must be less than 768 pixels.

For a device to be 'Small' its display width must be greater than or equal to 768 pixels or less than 992 pixels.

For a device to be 'Medium' its display width must be greater than or equal to 992 pixels or less than 1200 pixels.

For a device to be 'Large' its display width must be greater than or equal to 1200 pixels.

You can code up multiple versions of your grid, for BS3 to decide which type to use when targeting multiple displays, so for example if you did the following:

<div class="container">

  <div class="col-xs-2">Content here</div>

  <div class="col-xs-10">Content here</div>

  <div class="col-sm-2">Content here</div>

  <div class="col-sm-10">Content here</div>

  <div class="col-md-2">Content here</div>

  <div class="col-md-10">Content here</div>

  <div class="col-lg-2">Content here</div>

  <div class="col-lg-10">Content here</div>

</div>

Code snippet 4: Multiple grid size declerations

Then BS3 will hide, unhide the containers as required depending on the width of the device display and the operation of the media queries.

As with previous versions of the grid system, there are 12 columns horizontally and this is true across all the different sizes, meaning that whichever grid size is displayed, you will always still get 12 grids on every device.

The column width itself however does change, so you may need to plan the content in those grids to take advantage of the differing sizes. The sizes for each of them are as follows:

• col-xs-* = Auto sizing, with no fixed dimensions
• col-sm-* = 60 pixels
• col-md-* = 78 pixels
• col-lg-* = 95 pixels

The gutter margin in all cases will remain at 15 pixels on each side of the grid container, giving an overall gutter of 30 pixels, this size will be consistent no matter which gird size level your using.

Also nesting and offsets work as they did previously, but again as with the grid themselves, by way of a slight renaming in the actual classes used.

To apply an offset simply use 'col-md-offset-*' remembering to replace the 'md' with 'xs', 'sm' or 'lg' as required depending on your grid size.

Nesting is done simply by nesting containers under control of the 'col-xx-*' classes inside each other, where they will resize and behave as they did in previous BS versions.

The following examples show the correct way to achieve both of these techniques:

<div class="col-md-9">

  Level 1: .col-md-9

  <div class="col-md-6">

    Level 2: .col-md-6

  </div>

  <div class="col-md-6">

    Level 2: .col-md-6

  </div>

</div>

Code Snippet 5: Nested grids in version 3

The above example will give you a grid that looks like the following:

<div class="col-md-4">

  .col-md-4

</div>

<div class="col-md-4 col-md-offset-4">

  .col-md-4 .col-md-offset-4

</div>

<div class="col-md-3 col-md-offset-3">

  .col-md-3 .col-md-offset-3

</div>

<div class="col-md-3 col-md-offset-3">

  .col-md-3 .col-md-offset-3

</div>

<div class="col-md-6 col-md-offset-3">

  .col-md-6 .col-md-offset-3

</div>

Code snippet 6: Offset grids in version 3

The above example will give you a layout as follows:

BS3 also brings something new to the table when it comes to offsetting and nesting, and that's something called column ordering.

If you want your columns to be presented in a different order to how you define them in your HTML document, then you can use the new 'col-xx-pull-*' and 'col-xx-push-*' classes to push or pull your grid layouts into the order you want them in, take the following example:

<div class="col-md-8">8 columns of content</div>

<div class="col-md-4">4 columns of content</div>

If you render those in your document, as expected, you'll get the following:

If, however, you modify the above code to add a push and pull modifier as follows:

<div class="col-md-8 col-md-push-4">8 columns of content</div>

<div class="col-md-4 col-md-pull-8">4 columns of content</div>

Then render your document, you should see your layout change as follows:

Finally before we leave the grid system behind, and if you're using the less css source versions of bootstrap, you have complete control over the grid sizes by changing the following variables

• @grid-columns - controls the number of grids horizontally (default 12)
• @grid-gutter-width - the total margin around each grid (default 30 pixels)
• @grid-float-breakpoint - The minimum size below which we have 'Extra small' devices (default 768 pixels)

So now that we have the new grid system under control is there anything else to be aware of?

The more astute of you may be sitting there right now thinking 'But that's crazy, all those multiple sets of divs and offsets with col-xx-xx classes in, all for different size displays, I might as well just create 4 different sites, with 4 different resolutions in mind', and to be honest I wouldn't blame you if you were, except for one thing: Each of these new layout size levels are designed to work on the same markup at the same time and occupy the same space.

Let's take the code in 'code snippet 4' above, and re-write it to do this the recommended way:

<div class="container">

  <div class="col-xs-2 col-sm-2 col-md-2 col-lg-2">Content here</div>

  <div class="col-xs-10 col-sm-10 col-md-10 col-lg-10">Content here</div>

</div>

Code snippet 7: The recommended way of providing multi-resolution layouts

Ok so you might end up with the class list from hell on your elements, but one set of markup will adapt to all display sizes, and resize itself where needed.

This also works with the various offset, order, and nesting classes too.

Other migrations to be aware of

As well as what we've already discussed, the following class names also need to be changed if you’re migrating from a V2 layout to a V3 layout (Note: the following table has been taken directly from the bootstrap 3 docs and was correct at the time of writing, as bootstrap matures however this may not remain so:

As you can see most of the changes as previously mentioned have been to bring conformity to the naming scheme used by the various classes, but many of them have also been renamed because their overall purpose has changed.

Many of them we'll go into in more detail in further chapters in this book, but for now if you're doing a conversion, then the table above will tell you everything you need in order to retarget a V2 layout to V3.

One thing you might want to consider doing is to use a custom job in something like a Grunt.JS task, so that when you run your build system, these changes are performed automatically, this will allow your developers to remain productive using version 2, while gradually making the move to version 3.

So the final question then has to be, what exactly has been added that's new, and well mores the point what exactly has been removed?

We'll start with what's been removed, and we'll cover what's been added in more detail in the chapter on 'Changed CSS features', it's more important that you know what's been removed in this chapter, since this is the chapter you’re likely to be referring to when migrating your layouts.

First we'll start with what's been removed where Forms are concerned, and unfortunately that's quite a lot, first off we no longer have a specific type for a search form 'form-search' also the shaded bar typically found at the foot of a form 'form-actions' has also been deprecated in V3.

Also disappeared is the class typically used to display validation errors 'control-group-info' and its help counterpart 'help-inline' None of these 4 classes has any recommended replacement in the V3 code base, meaning that to construct equivalents of them, you will need to use other elements and classes where applicable.

Continuing with forms, the main 'controls' class used to wrap entire control sets, along with 'controls-row' instead you are advised to use 'row' or the new 'form-group' class. Forms have also lost most of the sizing classes, the fixed size classes such as 'input-mini', 'input-small', 'input-medium', 'input-large', 'input-xlarge' and 'input-xxlarge' have now all gone away along with the block level control class 'input-block-level', instead you are now advised to control your form element sizes using 'form-control' in combination with the new sizes and layouts available in the grid system.

From an individual control point of view, the 'inverse' classes have been removed from buttons and other similar controls, and we've also lost the 'dropdown-submenu' class in favor of just using split drop down buttons to create the same functionality.

For tabs the 'tabs-left', 'tabs-right' and 'tabs-below' classes no longer exist which means we now only have the ability to put tabs at the top of the content and to be left aligned.

Staying with tabs, the class to do content in a pill based tab set up has now also been removed, this means that 'pill-pane' & 'pill-content' should now use the general 'tab-content' & 'tab-pane' classes.

Finally, the various navbar classes are not without casualties, 'navbar-inner', 'navbar divider-vertical' 'nav-list' and 'nav-header' are no longer part of the framework.

In most cases, there are no direct equivalents in V3 for these classes, although there are some similarities in other classes that may prove useful. For example, 'nav-list' & 'nav-header' can be re-created using List groups.

There's a quick reference chart to all of these on the Bootstrap 3 site in the migration guide.