Logical architecture

This page describes the logical architecture of cppcms-skeleton framework.

Main application

Your website is served by the main application, which is built directly in the src directory. Application's entry point is defined in main.cpp. This application handles all HTTP requests. In the constructor we will attach to it some "sub-application" (named controllers). The main application is not used directly to display pages, it will always delegate this to a controllers.

Pre-routing phase

The goal of the main application is to do all the "before" routing actions: like for example checking that the URL is correctly formatted (for example if a website is multilingual and you have the following url schema:

http://language.domain.tld/controller/action/parameters1/parameters2 

you may want to allow users to do

http://domain.tld/controller/action/parameters1/parameters2

and to have code that redirect to the version of the website in the same language as the user's one.

Or if you change the overall url schema during the lifetime of your application, it's the main application that will be used to do the rewriting.

An other example: if your application is only to be accessed by some IPs (and if your webserver does not permit you to do so directly in the webserver configuration), you can do the check here.

Routing phase

Once this post-routing code done, the application will transfer part of URL, the cookies, sessions etc. to a controller (see the section below to more in-depth description of what is a controller). As an application has several controllers attached, the url will be used to determine which one to call.

for example considering this application with 3 controllers

• Tatowiki main application
  • Articles controller
  • Module1 controller
  • Pages controller

and the following code use to attach them:

add(articles,"^/articles(.*)",1);
add(module1,"^/module1(.*)",1);
//%%%NEXT_CONTROLLER_DISPATCHER_MARKER%%%, do not delete
add(pages, "/(.*)", 1);

then the following url

http://en.example.com/articles/show/1

will call the controller Articles and will send it the url '/show/1'

Controllers

The work flow of a controller is basically this:

1. The Controller is called trough the main application
2. It analyzes the URL it receives to decide which action to trigger
3. The action receives some parameters, extracted from the URL
4. Some basic checks are made to know if the user is allowed to do it
5. If so, the controller's action will initialize an instance of its dedicated Content
6. The Content will be filled using one or several of the following ways: * Using directly the parameters the action received and/or session and/or cookies * By calling a Model's action and treating the Result it returned
7. Some data may be stored/modified/deleted by calling a Model's action
8. The Content is then sent to the View that will take care of rendering it: * alternatively a redirection may be done instead
9. Optionally some post-rendering code may be executed after

What you may put in a Controller

The code dealing with analyzing the URL received from the main application

In a controller you will do all the code dealing with the HTTP headers:

• settings cookies
• retrieving data from the cookies/sessions
• Setting the information for a redirection (HTTP error code/ url on which to redirect to)
• Choosing the mime/type of the HTTP answer (in case you generate an image, excel file etc.)
• etc.

You will put the code dealing with calling Models to retrieve a Result

The code that will use the Results and other informations to fill the Content

The call to the View that will give it the Content and only this

What you should not put in a controller

Code aware of how and/or where the data are stored:

• No SQL requests
• No direct file writing/opening
• No API request to other services
• No raw JSON/XML (Xpath etc.) reading
• No complex manipulation of the data retrieved (i.e math formula etc.) These things are to be made in Model Classes

Code dealing with the output:

• No HTML/JSON/XML writing

for this => View

The goal of a controller is more to decide what to call rather than really doing actual actions, it should be something really "abstract"

Models

Models are used to store,retrieve,modify information

They are called by Controller, do data manipulation and return a Result