Project Example - lagoasoft-lucasschmidt/project_cartero GitHub Wiki

Example of how a project can look like

This example can be found in /example/example1 in this repository.

1. Views

• /views/layout.jade

You can have a base layout, to be used by all your views, and here, you could load basic libraries that will be used by all your views. By using ##cartero_requires, you are saying which libraries will be loaded for this view, and for all views that extend this layout.

// ##cartero_requires "jquery", "bootstrap" ,"utils"
doctype html
head
| !{cartero_css}
| !{cartero_js}
body
	block content

A important thing to notice is the local variables cartero_css and cartero_js. They are generated by express-hook. If you use express, based on a cartero.json, you can inject the correct dependencies automatically for your views.

• /views/clock/clock.jade, /views/clock/clock.js, /views/clock/clock.css

Here you have a view that extends layout.jade, by using ##cartero_extends or by simply by using Jade extends command (built in support). You can see that this view requires the library app/timekeeper.

Another detail is that this view contains two files in their folders: this means that these files will be loaded as view files as well. Plus, this view includes another view. If the included view has libraries required, or assets files inside their folder, they will be loaded as well.

// ##cartero_extends "layout.jade"
// ##cartero_requires "app/timekeeper"

extends ../layout
block content
  .row
    .col-lg-12
      p Hello Clock World
      include table/redtable

You can implement your own LibraryCreator by extending the default one, and overriding the function to detect extends/includes of a view, so that, based on your own templating language, you can detect when a view extends another view (to load their assets), or includes another view.

2. Libraries

• /library/bootstrap (contains bootstrap.min.js, bootstrap.css)
• /library/jquery (contains bundle.JSON, file that describes this library)

You can define a library based on remote files, so that you dont need to built in jquery inside your view files, and enjoy of CDN benefits.

{
	"remoteFiles": [
		"https://ajax.googleapis.com/ajax/libs/jquery/1.10.1/jquery.min.js"
	]
}

• /library/app/timekeeper (can contain any kind of asset that you define as a possible asset in your options, meaning, javascript, css, images ..., and can contain a bundle.json, if you want to describe your library and add options to it)

3. Gruntfile

In your Gruntfile, you will have a project_cartero task. You can define multiple configurations per environment, eg:

        project_cartero:
            dev:
                options:
                    templatesPath: path.resolve(__dirname, ".app/server/views")
                    librariesPath:  path.resolve(__dirname, ".app/client/library")
                    libraryFilesExtensions: /.*\.(coffee|js|css|less|jpg|jpeg|tiff|gif|png|bmp|swf|eot|svg|ttf|woff|jade)$/
                    publicFilesPath: path.resolve(__dirname, ".app/public")
                    librariesPublicRelativePath: ""
                    assetsProcessors: [
                        require('project-cartero/lib/component/processor/moveAssetsProcessor')
                        ,{task: "coffee", fileExt:"coffee", destExt:"js", clean:true}
                        ,require('project-cartero/lib/component/processor/calculateAssetsProcessor')
                    ]
                    carteroFileDescriptorPath: __dirname
                    logLevel: "info"
            prod:
                options:
                    templatesPath: path.resolve(__dirname, ".app/server/views")
                    librariesPath:  path.resolve(__dirname, ".app/client/library")
                    libraryFilesExtensions: /.*\.(coffee|js|css|less|jpg|jpeg|tiff|gif|png|bmp|swf|eot|svg|ttf|woff|jade)$/
                    publicFilesPath: path.resolve(__dirname, ".app/public")
                    librariesPublicRelativePath: ""
                    assetsProcessors: [
                        require('project-cartero/lib/component/processor/moveAssetsProcessor')
                        ,{task: "cssmin", fileExt:"css", destExt:"css"}
                        ,{task: "coffee", fileExt:"coffee", destExt:"js", clean:true}
                        ,{task: "uglify", fileExt:"js", destExt:"js"}
                        ,require('project-cartero/lib/component/processor/concatAssetsProcessor')
                        ,require('project-cartero/lib/component/processor/calculateAssetsProcessor')
                    ]
                    carteroFileDescriptorPath: __dirname
                    logLevel: "info"

If you notice, you must define where your templates are located, where your libraries are located, which files extensions should we consider, whats the folder where you want your output (publicFilesPath).

You can list multiple assets processors to process your files after they are detected. The description of your view/libraries are saved in a file named cartero.json*, thats why you must specify the directory you want to save this file. (This file will be necessary for the express-hook)

Notice that we have a MoveAssetsProcessor always there. For now, you must always explicitly include as the first one, if you want your code moved (it doesnt make sense for it to not be moved, since you dont want to transform your source files anyways).

4. Serve files using Express.js hook

express = require 'express'
projectCarteroMiddleware = require 'project-cartero/lib/express-hook'
path = require 'path'

app = express()
app.use '/', express.static(path.resolve(__dirname, '../public'))

app.set 'view engine', 'jade'
app.set('views', __dirname+'/views')

carteroJSONPath = path.resolve __dirname, "../..", "cartero.json"
app.use projectCarteroMiddleware(carteroJSONPath)

app.get "/", (req, res, next)->
  res.render "clock/clock"

app.listen 3000, ()-> console.log "Started app!!"