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.
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.)
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.
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
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:
pieName in the pies/ folder.pies.json file to add information about the new pie.Here are the files and folder created in the new pie:
pies/
pieName/
test/
controller.js
model.js
routes.json
Once you will have added the pies and coded your application, running the final application is easy. Just type:
tartempion run
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
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:
server: about the server being run.templates: about the templates used.session: about the session used.database: about the database used.test engine: about the test engine used.You can see an example of a basic config.json here.
The server part has the following properties:
address: the address the server listens on.port: the port the server listens on.The templates part has the following properties:
folder: the folder in which the templates reside.template engine: the template engine used.The session part has the following properties:
secret: the secret key used to crypt your cookies.maxAge: the expire time of your sessions.The databases part has basically one field: the name of the database
used. Depending on the database used, the properties differ.
For mongodb, you can read the official documentation
to see what are the options.
The test engine part has only this property for now:
name: name of the test engine used.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.
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.
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:
get and post.method property defines the controller's method.middlewares property is an array of the middlewares used.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:
req: the request parameter.res: the response parameter.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.
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.