Como usar Foundation com Laravel Elixir

Actualização: está disponível uma nova versão deste tutorial.

Quando se fala em frameworks front-end, o Bootstrap (anteriormente conhecido como Twitter Bootstrap) é o mais popular. Mas mais popular não significa melhor, e eu sempre preferi o Foundation. Até agora, para usar o Foundation num projecto com o Laravel, simplesmente fazia uma instalação normal dentro da directoria dos assets. Agora com o lançamento do Elixir podemos simplificar um pouco as coisas e usar apenas um task runner para todas as tarefas que queremos automatizar (compilar SCSS, concatenar ficheiros, correr testes…).

Vamos então ver como usar o Foundation num projecto Laravel.

0. Configurar o Elixir

Antes de começar, devemos garantir que o Elixir está devidamente instalado e configurado. Para isso é necessário ter instalado o Node.js (com  o npm) e o gulp. Depois basta correr o seguinte comando, na raiz do projecto (onde está o ficheiro “package.json”). Mais informação na documentação do Laravel.

npm install

O ‘package.json’, por defeito, inclui como dependência o Twitter Bootstrap. Como vamos utilizar o Foundation, podemos apagar a respectiva linha antes de correr o comando anterior. Para remover o Twitter Bootstrap depois de já estar instalado basta correr:

npm rm bootstrap-sass --save

Por esta altura, deve ser possível correr, sem erros, o comando gulp .

1. Instalar o Bower

O Bower é o package manager com que vamos instalar o Foundation. De notar que deve ser instalado globalmente (por isso a flag -g) .

npm install -g bower

Depois temos que inicializar o Bower. Para isso, ou criamos um ficheiro chamado bower.json (em que o único valor obrigatório é “name”), ou corremos a ferramenta de inicialização:

bower init

Não esquecer de adicionar a pasta “bower_components” ao .gitignore

Segundo a página do Foundation no GitHub existe também um package para o npm, o que tornava desnecessário instalar o Bower. Mas, pelo que vi, se instalarmos via npm, nenhuma das dependências (jquery, modernizr, etc…) são instaladas. Por isso a preferência pelo Bower.

2. Instalar o Foundation

Estamos finalmente prontos para instalar o Foundation, com o seguinte comando:

bower install foundation --save

Depois da instalação, na pasta “resources/assets/sass” vamos precisar de dois ficheiros. Este sãos os ficheiros que nós vamos editar.

2.1. Copiar o ficheiro “_settings.scss” da directoria  “bower_components/foundation/scss/foundation” para a directoria “resources/assets/sass”. Este ficheiro contêm todos os parâmetros dos vários elementos do Foundation que podemos personalizar.

2.2. Na directoria ‘resources/assets/sass’ criar um ficheiro chamado app.scss com o seguinte conteúdo.

@import "settings";
@import "foundation";

// Or selectively include components
// @import
//   "foundation/components/accordion",
//   "foundation/components/alert-boxes",
//   "foundation/components/block-grid",
//   "foundation/components/breadcrumbs",
//   "foundation/components/button-groups",
//   "foundation/components/buttons",
//   "foundation/components/clearing",
//   "foundation/components/dropdown",
//   "foundation/components/dropdown-buttons",
//   "foundation/components/flex-video",
//   "foundation/components/forms",
//   "foundation/components/grid",
//   "foundation/components/inline-lists",
//   "foundation/components/joyride",
//   "foundation/components/keystrokes",
//   "foundation/components/labels",
//   "foundation/components/magellan",
//   "foundation/components/orbit",
//   "foundation/components/pagination",
//   "foundation/components/panels",
//   "foundation/components/pricing-tables",
//   "foundation/components/progress-bars",
//   "foundation/components/reveal",
//   "foundation/components/side-nav",
//   "foundation/components/split-buttons",
//   "foundation/components/sub-nav",
//   "foundation/components/switches",
//   "foundation/components/tables",
//   "foundation/components/tabs",
//   "foundation/components/thumbs",
//   "foundation/components/tooltips",
//   "foundation/components/top-bar",
//   "foundation/components/type",
//   "foundation/components/offcanvas",
//   "foundation/components/visibility";

Este é o ficheiro principal, que faz todos os imports necessários e onde podemos escrever o nosso SCSS. De notar que é preferível importar apenas os componentes que realmente vamos usar, de modo a limitar o tamanho do ficheiro CSS que vai ser gerado. Para isso devemos comentar ou apagar a linha @import “foundation”;  e descomentar as linhas necessárias no bloco seguinte.

3. Escrever as tarefas do Elixir

Para terminar, temos apenas que escrever as tarefas do Elixir que vão compilar o SCSS para CSS e copiar alguns ficheiros JavaScript necessários.

elixir(function(mix) {
    // Sass
    var options = {
        includePaths: ['bower_components/foundation/scss']
    };

    mix.sass('app.scss', null, options);

    // Javascript

    // base directories
    var bower = '../../../bower_components/';
    var foundationScripts = bower + 'foundation/js/foundation/';

    mix.scripts([
        bower + 'jquery/dist/jquery.js',
        foundationScripts + 'foundation.js',
        foundationScripts + 'foundation.topbar.js',
        foundationScripts + 'foundation.alert.js',
        foundationScripts + 'foundation.reveal.js',
        foundationScripts + 'foundation.tooltip.js',
        foundationScripts + 'foundation.accordion.js',
        'start_foundation.js'
    ])
       .scripts([
        bower + 'modernizr/modernizr.js'
    ], 'public/js/modernizr.js');
});

Na tarefa do Sass, definimos a opção ‘includePaths’ de forma a podermos simplificar todos os imports nos ficheiros .scss. Esta tarefa vai criar um ficheiro “app.css” na pasta “public/css” que depois podemos usar no nosso site.

Nas tarefas de JavaScript, copiamos e concatenamos os ficheiros necessários para o Foundation funcionar correctamente. No mínimo, são necessários o “jquery.js” e o “foundation.js”. Depois devemos adicionar os ficheiros relativos aos componentes que estamos a utilizar (os ficheiros listados são só um exemplo). O ficheiro “start_foundation.js” inclui apenas o código para inicializar o Foundation.

$(document).foundation();

Isto vai criar um ficheiro “all.js” na directoria “public/js” que depois podemos usar no nosso site.

O ficheiro “modernizr.js” é criado à parte porque, normalmente, este ficheiro deve ser incluído na head do documento HTML, enquanto que o restante pode ser incluído no final.

4. Conclusão

E é isto. Agora, para executar, basta escrever na linha de comandos gulp para executar as tarefas uma vez ou gulp watch para executar as tarefas sempre que há uma alteração num dos ficheiros.

Se quisermos que os ficheiros criados sejam também minificados temos que adicionar a flag ‘–production’ (gulp –production ou gulp watch –production ).