Menu

Integration of Foundation 6 to Laravel 5

Feb 20, 2016 at 11:06 am, by Pierre Liard

Laravel is prepared out of the box to work with Bootstrap 3.0. It is not however a prerequisite, and Boostrap can be easily replaced by Foundation. It is this process I would like to explain in this blog.

 

Prerequisites

Laravel is probably already installed on your machine, but if it is not the case, you need at first to install Composer and then type the following command:

 composer global require "laravel/installer"

Make sure that the directory ~/.composer/vendor/bin can be found by your system in order for Laravel to work. This means that the PATH to this directory should be accessible from any location in your OS. If you are working with a Mac, you can check if it is the case by running the following command:

echo $PATH

If the path doesn't exist, it may be necessary to insert the following line:

export PATH="~/.composer/vendor/bin:$PATH"

 in three different files, all located in the home directory:

  1. ~/.profile
  2. ~/.bashrc
  3. ~/.zshrc (optional: only if oh-my-zsh is in use. For more information, oh-my-zsh )

 A fresh install of Laravel with all the dependencies can be then executed by simply typing:

laravel new yourfilename

It is also possible to install Laravel via Composer by issuing the command create-project as so:

composer create-project laravel/laravel yourfilename --prefer-dist

The second possibility gives an identical result, but is slower, per my experience, than the first. 

 

Preparation for Zurb-Foundation 6 framework

Foundation 6 was released a few days before 2015 Thanksgivings. It comes in three flavors: Foundation for Sites, Foundation for Apps, and Foundation for Email. I am here interested in showing how to install Foundation for Sites. The integration of Foundation with Laravel is almost seamless. Before starting the installation, a Bootstrap dependency in the package.json file needs to be removed and two new dependencies added:

{
  "private": true,
  "devDependencies": {
    "gulp": "^3.8.8"
  },
  "dependencies": {
    "laravel-elixir": "^4.0.0",
    "foundation-sites": "*",
    "motion-ui": "*"
  }
}

I personally prefer to insert a star instead of the version number; it presents the advantage of downloading the most recent version of Foundation 6. It is also possible of course to write 6.* for foundation-sites. This system is also convenient when you don't know the most recent version's number of a dependency. Motion-ui is a standalone library and is not required for Foundation to work properly, but it adds nice transition effects to several Foundation components.

Once done,make sure that node.js is installed on your computer. If it is not your case, go to nodejs.org and download the latest stable version. The package Node.js contains a node package manager called npm installed automatically with the node environment. npm runs through the command line and manages dependencies for an application.

Type npm install in your terminal window to install the dependencies written in the json file. It takes a few minutes to install the node dependencies, so be patient!  I have run a separate installation to give an idea of the files installed by Foundation and motion-ui,  but a single npm command is necessary to install all the dependencies needed by Laravel and Foundation.

☁  template_laravel_foundation  npm install
/Users/Pierre/Desktop/template_laravel_foundation
├─┬ foundation-sites@6.1.2
│ ├── jquery@2.1.4
│ └── what-input@1.1.4
└── motion-ui@1.2.0

What-input is a new functionality brought by Foundation 6, but is not yet well explained in Foundation-sites documentation. According to a recent post in GitHub by a Zurb designer, 

All of our components add outlines to focus/active states to make them accessible to keyboard users. However, designers find those outlines ugly, but they're necessary for accessibility.What-input watches for what input device the user is using, mouse or keyboard. If it's a mouse, the outlines are removed in the CSS. If it's a keyboard, the outlines are kept as a navigational aid. It's technically an optional dependency—you can remove it if you want. However, we highly recommend keeping it. (Functionality of What-Input)

Once done with this step, it is now time to copy several files from the node_modules directory just created in Laravel to the folder resources/assets/sass. The assets folder is for raw assets that need to be compiled or minified first. So for example, you can have several scss files in resources/assets that will be then compiled and minified into a single CSS file located into the public directory. It is worth mentioning that each file inside the public directory is...well public, whereas the files in resources are not. The public folder should only contain the files the browser needs to access, such as CSS, Javascript, images, video or audio files.

 

Laravel Elixir

Elixir, for those who are unfamiliar with Laravel, is an API (application program interface) that integrates with Gulp. It is like a wrapper around Gulp that simplifies its use. It allows the compiling of Sass, Less or CoffeeScript files, the minification of js files, and also automatic concatenation, automatic versioning of files among other tasks. We have seen already this association between Gulp and Elixir in the package.json file.

The first task is to copy all the scss files in the Foundation-Sites and Motion-ui folders, from the node_modules directory to the resources/assets/scss folder. This process is done with the help of gulpfile.js:

var elixir = require('laravel-elixir');

/*
 |--------------------------------------------------------------------------
 | Elixir Asset Management
 |--------------------------------------------------------------------------
 |
 | Elixir provides a clean, fluent API for defining some basic Gulp tasks
 | for your Laravel application. By default, we are compiling the Sass
 | file for our application, as well as publishing vendor resources.
 |
 */

elixir(function (mix) {
    mix.copy('node_modules/foundation-sites/scss', 'resources/assets/sass');
    mix.copy('node_modules/motion-ui/src', 'resources/assets/sass/motion-ui');
});

 You may want, at this point, to run Gulp into your terminal to check the results. If everything worked, you should see in your text editor something similar to this:
phpstorm resultThe second step is to copy the foundation.min.js, motion-ui.min.js, jquery.min.js and what-input.min.js files. There are two possibilities: they can be either copied to a resources/assets/js folder if you prefer to compile these files together, or stored separately to a public/js folder, if you don't want to have one single js file. I have personally retained the last alternative. Whatever the option, the code is exactly similar to the copy of the scss files:

   elixir(function (mix) {
    mix.copy('node_modules/foundation-sites/scss', 'resources/assets/sass');
    mix.copy('node_modules/motion-ui/src', 'resources/assets/sass/motion-ui');
    mix.copy('node_modules/foundation-sites/dist/foundation.min.js', 'public/js');
    mix.copy('node_modules/motion-ui/dist/motion-ui.min.js', 'public/js');
    mix.copy('node_modules/jquery/dist/jquery.min.js', 'public/js');
    mix.copy('node_modules/what-input/what-input.min.js', 'public/js');
});

 

Importing Foundation

Foundation is incredibly supple: it allows to tailor your project to your exact needs. Each component of this framework can be imported separately, or all together. For simplicity sake, I have chosen to import everything. To understand how Sass works in Foundation 6, please have a look at Sass implementation and Adjusting CSS output in the Foundation-sites docs. The import is done through app.scss in the resources/assets/sass folder. This file is the core of all CSS outputs and can be used to add your own CSS style (you can also create a partial file, especially if your personal styles are important). When this file is opened for the first time, there is a commented line for importing Bootstrap. Get rid of it, and replace it by the following code:

@import "settings/settings";
@import "foundation";
@import "motion-ui/motion-ui";

@include foundation-everything;
@include motion-ui-transitions;
@include motion-ui-animations;

 It is very important to import the settings before foundation, otherwise it won't work correctly.

Another core file, this time for all the javascript components related, is app.js. This file is located in the public directory, in the js folder. After creating this file, a single line needs to be added:

$(document).foundation();

This file can also be used for any personal javascript. The public and resources directory should now look something like that:

Your output may look slightly different, but the general structure should be similar to mine. As mentioned before, I prefer to keep my js files separate, but it may be even a better practice to compile them into a single file, like we are about to do for the scss files.

 

Compiling CSS

The last step of this process is to compile the components imported and added into the app.scss file. It is also done in gulpfile.js, similarly to what we did when copying the scss files.

elixir(function(mix) {
    mix.sass(
        'app.scss',
        'public/css/app.css',
        { includePaths:
            ['resources/assets/sass/']
        });

    mix.version(['public/css/app.css']);
});

The last line of code refers to what is called versioning or hashing. When a CSS or Javascript file is modified and the changes pushed to the server, some users don't see the modifications immediately because their browser has cached the previous version of the script. One way to fix this problem is to change the name of the file by using a random string to name the file. This process is known as versioning. Elixir saves its hashed files in the public directory in a folder called build. A random hash is placed between the file's name and its extension. So for example if your file is named main.css, it will be renamed main-592df76b95.css.

Our work is almost finished: we just need to run a last time Gulp to compile all the scss files into the public/css/css.app file. If everything works fine, you should now have an app.css file of about 3,860 lines. You have also a new folder build in the public directory with a hashed CSS file. It is identical to the app.css, but represents the current version of it. Try for example to add some personal style to resources/assets/app.scss, compile it by running Gulp, and you will notice that the hash in the build folder is different from the prior one. It is the versioning in action!

 

It's working!

There is at this point no way to verify that Foundation is now the framework that Laravel will use for all its CSS outputs. The integration of these two frameworks can be checked easily by using Laravel Blade templates engine. Two of the benefits of using Blade is template inheritance and sections. Because most of the web applications use the same layout across multiple pages, it is very good practice to create a Master page layout. This new blade file can be stored inside resources/views or, as I have done it, inside a layouts folder (resources/views/layouts/master.blade.php). Any file related to the site's layout such as navigation bar, header, footer, etc... can then be stored in this folder. My Master file looks like that:

Note the way the css.file is referenced: 

href="{{ elixir('css/app.css') }}"

When generating a versioned file, Laravel's global elixir PHP helper function allows to load the appropriate hashed asset. This function determines also automatically the name of the hashed file. If I had also compiled my js files with elixir, I would have used the same syntax.

I also created in the views folder a foundation.blade.php test file containing different components of Foundation 6. Near the end of this file, I have tested some javascript components of Foundation: Accordion, Motion-ui and Reveal, that is a component for modal dialogs, or pop-ups windows. Because of its length, it is not reproduced here, but it can be downloaded from GitHub - template laravel-foundation - with all the other files I mentioned before. 

To make this template eventually working, a route pointing to this foundation.blade.php needs to be added in the app/Http/routes.php file:

Route::get('/foundation', function () {
    return view('foundation');
});

You should now see the title Welcome to Foundation and some of the most used components of this framework. You should also be able to play with the accordion and to see motion-ui at work. You have now the best of two worlds in one application!

This process can still be improved, especially in the compiling of the javascript files, but it is sufficient to start working with both Laravel and Foundation frameworks. Once you get the hang of it, the setting time should take no more than 10-15 minutes, the longest part being to run npm install.


Leave a comment

Login to comment a post