Upgrading From Foundation 4

Need to upgrade from Foundation 4? No problem. This handy migration guide makes it super easy!

Upgrade your Rails project

Change the following line in your Gemfile:

gem 'zurb-foundation'

to:

gem 'foundation-rails'

Then run bundle install.

Upgrade using our CLI and Compass

Before continuing you'll need to install the following on your system:

• NodeJS
• bower (sudo npm install -g bower)

Our CLI can help you upgrade your Foundation 4 project to Foundation 5. It can be installed using the following commands in terminal:

gem install foundation
foundation version #=> should say v1.0.3 or higher

So let's assume you have a project in ~/Sites/PROJECT_NAME. To upgrade it to Foundation 5 you would run the following in terminal:

cd ~/Sites/PROJECT_NAME
foundation upgrade

Upgrade manually with Compass

Before continuing you'll need to install the following on your system:

• NodeJS
• bower (sudo npm install -g bower)

Starting in Foundation 5 there's no longer a Compass extension. Instead we use bower to keep Foundation assets up to date within your project. Here's how you can update your project:

Step 1: Create a bower.json file

In the root of your Compass project create a file called bower.json with this content:

{
  "name": "PROJECT_NAME",
  "dependencies": {
    "foundation": "~5.1.0"
  }
}

Step 2: Install Foundation 5

Now run bower install. This will create a directory called bower_components/ in your project. Foundation's Sass and JavaScript files will be placed in the bower_components/foundation folder.

Step 3: Tell Compass where Foundation resides

You'll want to update your config.rb folder to change this line from:

require "zurb-foundation"

to:

add_import_path "bower_components/foundation/scss"

Step 4: Update JavaScript links

Any references to the JavaScript files in your project will have changed. Links to Foundation JavaScript files should be changed from:

<script src="javascripts/foundation.min.js"></script>

to:

<script src="bower_components/foundation/js/foundation.min.js"></script>

This will ensure that when you run bower update to fetch the latest version of Foundation that the JavaScript is also updated.

Step 5: Recompile your project

Now run compass watch to recompile your project. If you see any errors please jump down to the upgrading your Sass section.

Upgrading the Sass

In Foundation 5 we removed the following components:

@import "foundation/components/sections";
@import "foundation/components/custom-forms";

Upgrading the JavaScript

We have built a migration plugin, foundation-migrate, that will guide you through moving your old Foundation JavaScript over to the new syntax.

Foundation 5 removes support for Zepto. Here's how you can switch Zepto for jQuery:

HTML

<!-- old Foundation 4 embed code -->
<script>
  document.write('<script src=/js/vendor/'
    + ('__proto__' in {} ? 'zepto' : 'jquery')
    + '.js><\/script>');
</script>

All you need to do is add jQuery to the end of your body:

HTML

<script src="/js/vendor/jquery.js"></script>

After you have included jQuery, you can drop in the Foundation library and initialize Foundation:

HTML

<script src="/js/vendor/jquery.js"></script>
<script src="/js/foundation/foundation.min.js"></script>
<script>
  $(document).foundation();
</script>

In Foundation 4, you could pass a string of the plugins you want to initialize like $(document).foundation('topbar reveal');. You can no longer do this in Foundation 5. Everything is initialized by default.

Configuration changes

Configuration options are passed a little differently to the Foundation libraries:

$(document).foundation('dropdown', {is_hover: false});

$(document).foundation({dropdown: {is_hover: false}});

In Foundation 5 you can reconfigure variables on the fly after the page has loaded and Foundation has been initialized:

JS

$('#myTarget').foundation({dropdown: {is_hover: true}});

Javascript Variable Changes

All Javascript configuration variables are now under_score instead of camelCase: