Official documentation of tartempion

1. Installation

Installing tartempion is easy. Just run the following:

npm install -g tartempion

Don't forget the -g parameter to install it globally. It may require you to run this as root though. If you only install it locally, using the command-line utility will be more painful. (You'll have to use it this way: ./node_modules/.bin/tartempion, which is a pain.)

If you want to get the last version from the git repository, here are the instructions:

git clone https://github.com/Ralt/tartempion
cd tartempion
# x.y.z is the current last version
git checkout x.y.z

tartempion's release management only uses git tags. The master branch is the one being used for development.

2. Command-line interface

tartempion provides a command-line utility to generate projects, pies, and also to run the tests or the application. (You will find out later what a pie is, please be patient. For now, just think it's an entity.)

2.1. Getting help

I believe that every project shouldn't need documentation. This is why the CLI utility provides help. Just type:

tartempion help

# or
tartempion

# or
tartempion --help

These three commands will show you the following screen:

~$ tartempion

Usage: tartempion [options] [command]

Commands:

    create-project <project>
    Create a project named <project>

    create-pie <pie>
    Create a pie named <pie>

    run
    Run tartempion

    test <pie>
    Run the tests in the pie <pie>

    test-all
    Run the tests in all the pies

    help
    Show help

Options:

    -h, --help     output usage information
    -V, --version  output the version number

As you can see, there are five useful commands.

2.2. Creating a project

tartempion provides an easy way to start a project. Just type:

tartempion create-project someProject

Replace someProject with your project's name. It will create a folder named someProject and add the boilerplate files to it. Here are the files and folders it creates:

someProject/
    locals/
        locals.js
    middlewares/
        middlewares.js
    pies/
    templates/
    config.json
    package.json
    pies.json
    tartempion.js

2.3. Creating a pie

You don't know yet what a pie is, but you will soon find out it is an essential notion to tartempion. Hopefully for you, the CLI utility also provides an easy way to create a pie. Just type:

tartempion create-pie pieName

Replace pieName with your pie's name. This command does two things:

Here are the files and folder created in the new pie:

pies/
    pieName/
        test/
        controller.js
        model.js
        routes.json

2.4. Running tartempion

Once you will have added the pies and coded your application, running the final application is easy. Just type:

tartempion run

2.5. Testing the pies

tartempion provides an easy way to run the tests you will add to the pies. Just type:

tartempion test pieName

If you want to run the tests in all the pies, just type:

tartempion test-all

3. Configuration

tartempion doesn't want you to hard-code values in your code.

So it has a config.json file where you can store your configuration.

The configuration is divided in 5 parts:

You can see an example of a basic config.json here.

3.1. server

The server part has the following properties:

3.2. templates

The templates part has the following properties:

3.3. session

The session part has the following properties:

3.4. database

The databases part has basically one field: the name of the database used. Depending on the database used, the properties differ.

3.4.1. mongodb

For mongodb, you can read the official documentation to see what are the options.

3.5. test engine

The test engine part has only this property for now:

4. Pies

4.1. Introduction

A pie is an entity. It is similar to an app in django. Or a mojito in mojito.

A pie has one controller and one model.

tartempion uses the concept of a pie so that you can have decoupled business code. This way, you can code your "user" pie for a project, and reuse this pie in another project, by simply copy pasting it. Rumors say that someone is thinking of building a pie package manager.

Don't forget that tartempion relies on express to do its work. So you will see some similarities.

4.2. Definition

You can define the pies used in the pies.json file. By default, the CLI utility does this for you, so you may not need it. But here is how a pie is defined:

{
    "pieName": {
        "path": "path/to/pieName"
    }
}

path/to/pieName starts at the pies/ folder.

If you want to use a pie in another pie, this is where you define the dependencies. Here is an example:

{
    "pieName" {
        "path": "pieName"
    },
    "otherPie": {
        "path": "otherPie",
        "dependencies": [
            "pieName"
        ]
    }
}

You will see in 4.4. how to use these dependencies.

4.3. The routes

To define the routes that a pie handles, the routes.json file is there.

tartempion believes that writing JSON files is less prone to errors than writing code, so it tries to use them as much as possible.

Here is a sample of a routes.json file:

{
    "get": [
        { "/": "index" },
        { "/user/login": {
            "method": "getLogin",
            "middlewares": [
                "requireGuest"
            ]}
        }
    ],
    "post": [
        { "/user/login": {
            "method": "postLogin",
            "middlewares": [
                "requireGuest"
            ]}
        },
        { "/user/logout": {
            "method": "logout",
            "middlewares": [
                "requireLogged"
            ]}
        }
    ]
}

You can see how such a file is structured:

4.4. The controllers

As you could see, we defined the controller's methods in the routes.json file. These controller's methods are to be found in the controller.js file of the pie.

To follow the example of 4.2., here is a controller's example:

module.exports = {
    getLogin: function( req, res ) {
    },

    postLogin: function( req, res ) {
    },

    logout: function( req, res ) {
    }
};

Each controller's method has two parameters:

Now, there is something very important to know:

Each controller has its model's methods available through this.model.

This means that after defining a get( username, callback ) method in the model, you can use it this way in the controller:

module.exports = {
    getLogin: function( req, res ) {

        // See the very important thing here:
        this.model.get( req.params.username, function() {} );
    });
};

And it works.

If you have defined dependencies in the pies.json file, you can access the other pie's controller methods through this.pieName.

4.5. The models

The model's methods are defined in the model.js file of a pie.

To follow up on the previous example, here is the model.js file:

module.exports = {
    get: function( username, callback ) {
        // Use "this.db" to access the database
        // specified in the configuration.
        callback();
    }
};

You saw that comment right. You can access the methods of your database through this.db. Just like this.

5. Express