<!--toc--> |
|
## Introduction |
|
CppCMS is [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93View%E2%80%93Controller) web framework. One of its important parts is view - the HTML rendering system. |
|
CppCMS's web pages are written in a special template language, that is translated to C++ code that can be compiled to a shared object (or DLL on windows) or be statically linked into your applications. |
|
Generally the CppCMS template system uses a push model, where the user application prepares the content and pushes it to the web template system for rendering. |
|
For proper rendering of templates it is required to have 2 stages: |
For proper rendering of templates two stages are required: |
|
1. Your application - controller prepares the "content" for the HTML template system. |
2. The content is rendered using template system to HTML that is returned to users. |
1. Your application (controller) prepares the "content" for the HTML template system. |
2. The content returned to the users is rendered to HTML using the template system. |
|
## Code |
|
In order to work with templates we need to separate our |
source into three parts: |
|
- Content - the objects that are filled with data that should be rendered. |
- Application itself that creates the content. |
- HTML template that renders the content. |
|
### The content |
|
The content declarations would appear in "content.h" file: |
|
#include <cppcms/view.h> |
#include <string> |
|
We need to include a header `<cppcms/view.h>` that would |
bring us all definitions for proper definition of our content class. |
|
namespace content { |
struct message : public cppcms::base_content { |
std::string text; |
}; |
} |
|
Each content object should be derived from the class `cppcms::base_content` and should store all relevant data. |
|
So we create a small structure `message` that holds a single |
string `text` that would be rendered in HTML template. |
|
As a rule of thumb we put all our content objects to |
separate namespace. |
|
### The template |
|
All web templates are separated to skins - the specific implementation of the view that can vary for same content. Each skin is placed in the namespace with same name. |
|
Each skin consists of a set of views - the representation of a single page. All views can be organized to an hierarchy of views so each view can extend the base view with more features and redefine its templates. The views are represented with classes each one of them responsible for rendering specific content object. |
|
As rule of thumb we name them using same ways as content classes. |
|
Each view consists of a set of templates when the one base template that is always rendered is called `render` template and it should be always implemented. |
|
So lets see out first template: |
|
<% c++ #include "content.h" %> |
<% skin my_skin %> |
<% view message uses content::message %> |
<% template render() %> |
<html> |
<body> |
<h1><%= text %> World!</h1> |
</body> |
</html> |
<% end template %> |
<% end view %> |
<% end skin %> |
|
In the first line we use C++ inline code to include the appropriate header. |
|
Then we define our skin called simply "my_skin" and then in line 3 we define our view. We call it `message` same as out content's class, and we describe that is would render an object of type `content::message` |
|
Then in line 4 we define the function that actually renders all the HTML for as - `render`. |
|
In the line 7 we display a member `text` of of the `content::message` in the HTML. Note: the displayed text |
would be automatically escaped with HTML entities, for example `<` would be converted into `<`. |
|
### The controller |
|
Similarly to our "hello world" example we define a `main` function of an application, but before this we include our `content.h` header. |
|
Our main function: |
|
virtual void main(std::string /*url*/) |
{ |
content::message c; |
c.text=">>>Hello<<<"; |
render("message",c); |
} |
|
|
We create an object `c` of type `content::message` |
and set the value for its `text` member with |
arbitrary HTML unsafe string. |
|
And then we call `render` member function of `cppcms::application` with following parameters: |
|
1. The name of view for default skin. It generally matches the name of the content class, in our case "message". |
2. The content object itself that holds all the data HTML template needs. |
|
After calling it the HTML would be automatically written |
to the output. |
|
## Building Templates |
|
The template that was shown in [above](#The+template) should be compiled into C++ code in order to be useful. We do it with special compiler as following: |
|
cppcms_tmpl_cc my_skin.tmpl -o my_skin.cpp |
|
The created `my_skin.cpp` contains all the code needed for rendering and registering this skin in CppCMS's rendering system. |
|
### Linking Statically |
|
Now, `my_skin.cpp` should be compiled and linked together with your application: |
|
g++ hello.cpp my_skin.cpp -o hello -lcppcms -lbooster |
|
And we can run our application as usual: |
|
./hello -c config.js |
|
### Dynamic loading |
|
The dynamic linking a little bit more tricky but as well much more powerful as allows to load skins without relinking application and even update them without restarting the application. |
|
First we create a shared object from our `my_skin.cpp` and name it with same name as our skin: |
|
g++ -shared -fPIC my_skin.cpp -o libmy_skin.so -lcppcms -lbooster |
|
(Or for GCC 4.7 on OSX, we create it like this:) |
|
g++ -shared -fPIC my_skin.cpp -o libmy_skin.dylib -lcppcms -lbooster |
|
Now we compile our hello application without `my_skin.cpp` but we pass an additional parameter `-rdynamic` in order to allow shared library to see symbols in the application: |
|
g++ -rdynamic hello.cpp -o hello -lcppcms -lbooster |
|
(Or for GCC 4.7 on OSX, we compile it like this:) |
|
g++ -dynamic hello.cpp -o hello -lcppcms -lbooster |
|
Now our system is almost ready to run, we just need to add |
in our configuration description of what skins should be loaded dynamically. We add following section to `config.js`: |
|
"views" : { |
"paths" : [ "." ], |
"skins" : [ "my_skin" ] |
} |
|
- `paths` - describe the location of dynamic libraries that should be loaded. |
- `skins` - describes the list of skins that should be loaded. |
|
Now run the application as usual and it would load the |
skins and use them. |
