Modules

phun-ky edited this page Jan 29, 2013 · 15 revisions

Here you will find the full documentation of the modules in patsy. Currently, this is a work in progress, YMMV.

Table of Contents

Currently, patsy comes with these modules:

  1. Patsy modules
  2. GruntJS
  3. JavaScript linting
  4. JavaScript minification
  5. CSS linting
  6. CSS minification
  7. LESS baking
  8. Automagic documentation generation
  9. Automated tests
  10. Concatination of *.mustache template files
  11. Proxy
  12. Static File Server
  13. API-mocking
  14. Live reload
  15. Configuration

Patsy modules

We've divided patsy in "modules", but perhaps not in the way you usually interpret the word "module". A patsy "module" is something that provides certain features, and it could be:

  • a single dependency/ several dependencies
  • a file/set of files
  • a set of config/rules/logic/algorithm
  • a node module
  • all of the above

For example, GruntJS is a "module", but the set of files and rules regarding the proxy option is also a "module".

⬆ Go to the TOC

GruntJS

grunt-cli is installed locally to prevent security warnings when trying to install patsy on linux platforms.

This is where the true power of patsy lies, the fantastic build tool grunt.

For further reading about GruntJS, see their site.

You must never ever edit the Gruntfile.js in the patsy folder. The grunt config file is used for all your projects, including patsy.

If you want to run grunt on patsy, just go into the patsy folder and type grunt.

Grunt is currently run with the --force flag by default to produce helpful feedback to the end user on grunt warnings that usually forces a process.exit(). To change this, set build.options.force to false.

⬆ Go to the TOC

GruntJS plugins currently in use

⬆ Go to the TOC

Regarding grunt-recess errors

Grunt-reccess is built upon Twitters RECESS and RECESS currently does not cast some vars attached with the node plugin colors to String. It's a chance that the error is due to parser error, FWIW from the RECESS issue list

Solution

Unfortunately, we can't use our fork of RECESS (https://github.com/phun-ky/recess), since RECESS is a dependency for grunt-recess.

⬆ Go to the TOC

Regarding grunt-dox errors

Grunt-dox is built upon P'unk Avenues dox-foundation and dox-foundation currently does not have the desired support for Windows and it does not run well with a local install of dox-foundation.

Solution

⬆ Go to the TOC

Regarding grunt-contrib-nodeunit, grunt aborts when no files found

grunt-contrib-nodeunit exits grunt when no test files are found.

Solution

⬆ Go to the TOC

GruntJS configuration

See the Configuration page under "build" for all options available for the build module grunt.

⬆ Go to the TOC

JavaScript linting

Linting with JSHint.

⬆ Go to the TOC

JavaScript minification

Minification with UglifyJS 2.

⬆ Go to the TOC

CSS linting

RECESS

⬆ Go to the TOC

CSS minification

RECESS

⬆ Go to the TOC

LESS baking

RECESS

⬆ Go to the TOC

Automagic documentation generation

We currently use grunt-dox for this.

This module is more of a "show what we can do" module, rather than a module that's production ready. We await some updated and decisions from grunt-dox and dox-foundation before we make it production ready.

⬆ Go to the TOC

Automated tests

Automated tests with qunit, jasmine and node-unit.

⬆ Go to the TOC

Concatination of *.mustache template files

grunt-mustache

⬆ Go to the TOC

Proxy

Patsy comes with a full featured proxy module to solve all your developer needs when developing REST API-based applications with a JavaScript frontend.

Currently, only http to http forwarding is supported. Until further support is added, we recommend the usage of NGINX.

Proxy configuration

See the Configuration page under "proxy" for all options available for the proxy module.

⬆ Go to the TOC

Static file server

Patsy comes with a simple static file server module. The configuration for this is based on the configuration settings in project.environment.

The server is set up on project.environment.host:project.environment.port.

⬆ Go to the TOC

Live reload

Patsy comes with a grunt-module, grunt-reload, to support live reloading of changed files. Currently, only complete pages are reloaded. The configuration for this is based on the configuration settings in project.environment.

The live reload server will listen to port 8001, and proxy page requests to proxy.host:proxy.port. These page requests will automatically be appended with the live reload client script reloadClient.js.

Logic in Gruntfile.js

reload: {
  port: 8001,
  proxy: {
    host: config.project.environment.host || "localhost",
    port: config.project.environment.port || 8090
  }
}

Using Live Reload with the static file server and the proxy module

When using the static file-server, proxy and LiveReload you should add this snippet in your index.html, as of now having the LR-proxy forward requests to the patsy-proxy is not supported.

  <script>__reloadServerUrl="ws://localhost:8001";</script>
  <script src="http://localhost:8001/__reload/client.js"></script>

If you're using multiple machines and browsers (or devices), remember to replace localhost with the IP or domainname of your static file server. Consider using a index_dev.html or something similar, avoiding accidentally adding LiveReload in production.

  <script>__reloadServerUrl="ws://10.160.150.163:8001";</script>
  <script src="http://10.160.150.163:8001/__reload/client.js"></script>

⬆ Go to the TOC

API-mocking

⬆ Go to the TOC

Configuration

Patsy will generate a configuration file for you if you have not specified one in your project root folder. Patsy will ask you some questions to build a configuration file, or if you trust him, he will generate a default configuration file for you. See Configuration page for more details.

⬆ Go to the TOC

Example of a patsy configuration file:

Can be found here aswell: Example configuration file.

{
  "project": {
    "details": {
      "name": "ProjectFoo",
      "homepage": "http://projectfoo.com",
      "author": "Foo Bar"
    },
    "environment": {
      "root" : "ProjectFoo",
      "abs_path": "C:\\Users\\JohnDoe\\Workspace\\ProjectFoo\\",
      "web_root": "\\src\\main\\webapp\\",
      "port": 8094,
      "host": "localhost",
      "home_file": "/ProjectFoo/start.html"
    },
    "options" : {
      "watch_config": true
    }
  },
  "build": {
    "js": "js/src/",
    "min": {
      "dest": "js/min/projectfoo.core.js",
      "options" : {
        "sourceMap" : "js/dist/maps/sourcemap.js",
        "mangle" : false
      }
    },
    "dist": "js/dist/",
    "tmpl": {
      "src": "js/mustache/",
      "options" : {
        "prefix" : "$B.extend({ templates: ",
        "postfix" : "});",
        "verbose": false
      }
    },
    "lint": {
      "options": {},
      "src": ["js/src/**/*.js","!js/src/lib/*.js"]
    },
    "docs": {
      "dest": "js/docs/",
      "options": {}
    },
    "css" : {
      "src" : "css/src/less/main.less",
      "dest" : "css/dist/main.css",
      "options" : {
        "compile" : true,
        "compress" : true
      }
    },
    "test": {
      "suites": {
        "jasmine" : {
          "src": "js/test/jasmine/**/*.js"
        },"qunit" : {
          "src": "js/test/qunit/**/*.js",
          "options": {
            "timeout": 10000,
            "--cookies-file": "misc/cookies.txt"
          }
        },"nodeunit" : {
          "src": "js/test/nodeunit/**/*.js"
        }
      }
    },
    "options": {
      "verbose": true,
      "linting": false
    }
  },
  "proxy": {
    "resources": [{
      "path" : "/api/oauth/token",
      "pass"      : "http://beezwax:1500/rest-api/oauth/servicetoken"
    },{
      "path" : "/model/person/",
      "pass"      : "http://alt-stb-002:12000/database/sources/model/person/",
      "headers"       : {
        "foo": "bar"
      }
    }],
    "options": {
      "verbose": true,
      "port" : 80
    }
  },
  "options": {
    "verbose": true,
    "logToFile": false,
    "scripture": true
  }
}

See the Configuration page for full option list with examples.

⬆ Go to the TOC