Skip to main content

Migration Guide

Guidance on how to upgrade from Fuel UX v2.x to v3.x with emphasis on setup differences, updated project structure, and new vs removed features.

Migrating from 2.x to 3.0

Fuel UX 3 is not backwards compatible with v2.x. Use this section as a general guide to upgrading from v2.x to v3.x.

Bundled no more

In Fuel UX 2.x, Bootstrap was bundled along with the Fuel UX project code, but this is no longer the case. We wanted to enable developers to upgrade either library at their own leisure, so we've decoupled the code. Fuel UX still has a dependency on Bootstrap, so the developer must be certain to include Bootstrap within their project before Fuel UX themselves. For information on how to do this using external script tags or AMD, please see our Basic Templates.

Upgraded foundation

Fuel UX 3 is built upon Bootstrap 3 rather than Bootstrap 2, which has an improved mobile-first architecture. There are many differences between the two versions. Converting your project to use the latest version of Bootstrap is one of the larger efforts when migrating to Fuel UX 3. For assistance with this task, please visit Bootstrap's Migration Guide.

Directory structure

The directory structure has changed significantly in this version of Fuel UX:

├── dev/
├── dist/
│   ├── css/
│   ├── fonts/
│   └── js/
├── fonts/
│   └── src/
├── js/
├── less/
├── markup/
└── test/
    └── markup/

Since UMD (Universal Module Definition) is used for our controls, the 'loader.js' file is no longer needed for non-AMD users. This means any file within the js directory can be included on the page via external script tag or AMD, which is useful for bringing in individual controls.

Markup changes

Due to the updated Bootstrap foundation, our controls have had significant changes made to the markup required to be functional. It is recommended that all Fuel UX controls within your project are investigated and updated as needed. Visit our controls page for more information.

What's new

This table shows the new controls added to Fuel UX 3.

Control Description
Infinite Scroll Turn any element into an infinite scrolling region with content that loads on demand.
Loader Animation for visual indication of waiting time that can be customized to have many appearances. Replaces the preloader.
Placard Adds a pop-up element to inputs/textareas on focus with additional options for explicit accept/cancel actions.
Repeater Data viewer with paging, sorting, and searching. Can be easily extended for various renderings. Replaces the datagrid.

What's removed

The following controls have been removed from Fuel UX 3.

Control Reason
Datagrid This control has been refactored as the Repeater to enable greater data-rendering flexibility.
Preloader This control has been refactored as the Loader to be more flexible and consistent across browsers while providing a javascript API. CSS-only variations may be re-introduced at a later date.

Get Started Today With Fuel UX

Here's all the assets you will need to get started with Fuel UX:

Additional notes

Other changes in v3.0 are not immediately apparent. Here's a partial list:

  • Be sure to first convert your project to Bootstrap 3
  • Events have been namespaced to follow the [eventname].fu.[controlname] format, which is different than the previous structure that contained only the [eventname]. This has been done to avoid collision with events outside the Fuel UX library. Example event: actionclicked.fu.wizard
  • While most javascript methods remain the same, there have been some changes, so be cautious of that.
  • Images are no longer a part of Fuel UX. The loader control uses font-icons, but everything else is all CSS.
  • Fuel UX controls are based on jQuery and JavaScript controls, so try to use JavaScript when interacting with them.
  • Fuel UX 3 has all the benefits and trappings of Bootstrap 3

Upgrading to Bootstrap 3

Migrate your html: Guides and "best effort" convertors

Start from scratch

Get help with Fuel UX

Create an issue on Github if you think it is a bug, or ask a 'fuelux' tagged question on StackOverflow.