Tutorial: Foundation for Apps Setup With AngularJS Best Practices

February 17, 2015January 1, 2018 Fedil 1 Comment

Lately I have been diving deep into responsive web development and AngularJS. For the responsive part I have been using Zurb’s Foundation. I really like Foundation and found it really easy to work with. Unfortunately there are issues with their JavaScriptÂ interactivity when you try to use it with AngularJS.Â Â That is why I was excited whenÂ Zurb announced theirÂ Foundation for Apps.

Foundation for Apps

Foundation for Apps uses a lot of cutting edge front end technologies. They use flex box for their grid system which givesÂ greater flexibility.Â AngularJS is also built-in. In my eyes this makes it perfect for my future front end development projects. So I decided to download it and try to make some prototypes. Unfortunately I didn’t see anything in their documentation on how to set up a project manually. Of course you can always use their ruby CLI utilities. I didn’t want to go that route because I like to know how things work and I am also not a big ruby fan.

So I tried to find anything on how to set up a new project and hoped it would also incorporate the best practices for AngularJS. I was not successful in finding anything. That is what led me to create this tutorial. One thing that was important to me was to try my best to follow the Best Practice Recommendations for Angular App Structure.

Tutorial

The goal of this tutorial will be to walk through the steps of setting up a project that will use Foundation for Apps and follow the AngularJS best practices. All commands demonstrated throughout this tutorial can be run from aÂ terminal on a unix, linux, or Mac OS X computer. The final outcome can be used as a seed for new projects. If you want to skip directly to the ending product feel free to getÂ the foundation for apps seed repoÂ on my github.

Clone the Repository

Clone the angular-seed repository using git:

# git clone https://github.com/ukneeq/foundation-apps-seed.git
# cd foundation-apps-seed

If you just want to start a new project without the foundation-apps-seed commit history then you can do:

# git clone --depth=1 https://github.com/ukneeq/foundation-apps-seed.git <your-project-name>

The depth=1 tells git to only pull down one commit worth of historical data.

Prerequisites

You’ll need the following software installed to get started.

Node.js: Use the installer provided on the NodeJS website
Gulp and Bower: Run [sudo] npm install -g gulp bower

We will also need to create a directory for our web app. For this tutorial I will use the name “foundation-apps-seed”. After we create the directory we need to change into it so that we can start creating the files for our project.

# mkdir foundation-apps-seed
# cd foundation-apps-seed

Setup Dependencies

We have two kinds of dependencies: tools and the foundation for apps framework. We use the tools for the various build tasks and testing of the application.

To get the tools we will be using npm, the node package manager.
To get the foundation for apps framework we will be using bower, aÂ client-side code package manager.

In order for npm to know what packages we need, we have to create the package.json file. We will also need to set up a few scripts so we can use npm to set up everything we need for our application to make development faster and easier. The file will have the following entries:

package.json:

{
  "name": "foundation-apps-seed",
  "private": true,
  "version": "0.0.1",
  "description": "A starter project for AngularJS apps using Foundation for Apps",
  "repository": "https://github.com/ukneeq/foundation-apps-seed.git",
  "license": "Private",
  "devDependencies": {
    "karma": "~0.12",
    "protractor": "^1.6.1",
    "http-server": "^0.6.1",
    "bower": "^1.3.1",
    "shelljs": "^0.2.6",
    "karma-junit-reporter": "^0.2.2",
    "connect-modrewrite": "^0.7.9",
    "front-matter": "^0.2.0",
    "del": "^1.1.1",
    "glob": "^4.3.5",
    "gulp": "^3.8.10",
    "gulp-changed": "^1.1.1",
    "gulp-concat": "^2.4.3",
    "gulp-autoprefixer": "^1.0.1",
    "gulp-file-include": "^0.8.0",
    "gulp-gzip": "^0.0.8",
    "gulp-livereload": "^2.1.1",
    "gulp-load-plugins": "^0.8.0",
    "gulp-minify-css": "^0.3.11",
    "gulp-notify": "^2.2.0",
    "gulp-rename": "^1.2.0",
    "gulp-sass": "^1.2.4",
    "gulp-sourcemaps": "^1.3.0",
    "gulp-uglify": "^1.1.0",
    "gulp-util": "^3.0.2",
    "gulp-watch": "^3.0.0",
    "require-dir": "^0.1.0",
    "rimraf": "^2.2.8",
    "run-sequence": "^1.0.1",
    "gulp-connect": "^2.0.6",
    "streamqueue": "^0.1.1",
    "through2": "^0.6.2"
  },
  "scripts": {
    "postinstall": "bower install",

    "prestart": "npm install",
    "start": "http-server -a localhost -p 8000 -c-1",

    "pretest": "npm install",
    "test": "karma start karma.conf.js",
    "test-single-run": "karma start karma.conf.js  --single-run",

    "preupdate-webdriver": "npm install",
    "update-webdriver": "webdriver-manager update",

    "preprotractor": "npm run update-webdriver",
    "protractor": "protractor e2e-tests/protractor.conf.js",

  }
}

If you have worked with npm before this will all look familiar. If you haven’t a lot of it should seem very self-explanatory. The values “devDependencies” are a list of packages that this project will need. Most of the packages are for tools that will be used during the build tasks and testing setup. We also include minimum versions that were used for this tutorial so that we know it will work correctly.

The “scripts” part is where we define commands that need to be run for certain parts of the setup:

“postinstall”: This tells npm to run “bower install” after it has down it has performed its install. This will install all the bower components for us.
“start”: Tells npm to startup a localhost instance of http-server.
“prestart”: This is kicked off automatically before it performs the action listed in “start”. So before the action is performed we want to make sure that we have performed a npm install.
“test”: This will run our unit tests that we will write during the tutorial.
“pretest”: This is kicked off automatically before it performs the action listed in “test”. Again it just makes sure that npm install was run first.

You get the pattern here. So the rest should be pretty obvious.

Now we need to tell bower what it needs to install when the command “bower install” is performed. For thisÂ we will create the bower.json file. It will look like the following:

bower.json:

{
  "name": "foundation-apps-seed",
  "description": "A starter project for AngularJS apps using Foundation for Apps",
  "version": "0.0.1",
  "homepage": "https://github.com/ukneeq/foundation-apps-seed",
  "license": "Private",
  "private": true,
  "dependencies": {
    "foundation-apps": "~1.0.3"
  }
}

Again most of this should be easy to read and understand. The important part of this is the “dependencies”. This is where we list what we need bower to install. For this tutorial we really only need bower to install the foundation-apps code. As of this tutorial version 1.0.3 is the latest.

Create App Structure

Since I modeled this tutorial off the angular-seed project it has the same basic structure. I modified it slightly because I like to have a src directory to hold all my files that could be used in development.

src/
  app/                    --> all of the source files for the application
    app.css               --> default stylesheet
    components/           --> all app specific modules
      version/            --> version related components
        version.js               --> version module declaration and basic "version" value service
        version_test.js          --> "version" value service tests
        version-directive.js     --> custom directive that returns the current app version
        version-directive_test.js  --> version directive tests
        interpolate-filter.js      --> custom interpolation filter
        interpolate-filter_test.js --> interpolate filter tests
    view1/                --> the view1 view template and logic
      view1.html          --> the partial template
      view1.js            --> the controller logic
      view1_test.js       --> tests of the controller
    view2/                --> the view2 view template and logic
      view2.html          --> the partial template
      view2.js            --> the controller logic
      view2_test.js       --> tests of the controller
    app.js                --> main application module
    index.html            --> app layout file (the main html template file of the app)
karma.conf.js         --> config file for running unit tests with Karma
e2e-tests/            --> end-to-end tests
protractor-conf.js    --> Protractor config file
scenarios.js          --> end-to-end scenarios to be run by Protractor

We haven’t created a lot of the files yet, but I wanted to just give an overview of how the whole structure will look. So for now we are just going to create the directories that we will need.

# mkdir -p src/app/components/version
# mkdir -p src/app/view1
# mkdir -p src/app/view2
# mkdir e2e-tests

Install Dependencies

Now all that is left is to tell npm to install everything for us. Since we preconfigured npm to automatically run bower we can run:

# npm install

This will download and install everything we need for our web app. It will also make sure we have the correct versions so that we don’t have to worry about those details. Everything will also be in the correct location since we already setup the directory structure.

Since this is a long tutorial I figured I would break it up into several parts. Continue to Part 2 ofÂ Foundation for Apps Setup With AngularJS Best Practices Tutorial. Part 2 will take you through creating the build script.