<!--toc--> |
|
## Introduction |
|
CppCMS is an [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 two stages are required: |
|
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: |
The content declarations will appear in the "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. |
We need to include the header `<cppcms/view.h>` that will provide us with all the definitions required as a base 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've created a small structure `message` that holds a single |
string `text` that would be rendered with an HTML temp |
|
So welate. |
|
As a rule of thumb we put all our content objects in a |
separate namespace. |
|
### The template |
|
All web templates are separated to skins - the specific implementation of the view that can vary for the same content. Each skin is placed in the namespace with the same name. |
|
Each skin consists of a set of views - the representation of a single page. All views can be organized to a 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 a specific content object. |
|
As a rule of thumb we name them the same way as content classes. |
|
Each view consists of a set of templates where the base template that is always rendered is called `render`, and it should always be 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 us - `render`. |
|
In the line 7 we display a member `text` 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 the `render` member function of `cppcms::application` with the following parameters: |
|
1. The name of the view for the default skin. It generally matches the name of the content class, in our case "message". |
2. The content object itself that holds all of the data the HTML template needs. |
|
After calling it the HTML would be automatically written |
to the output. |
|
## Building Templates |
|
The template that was shown above should be compiled into C++ code in order to be useful. We do this with a 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 |
|
Dynamic linking is a little bit more tricky, but it is much more powerful as it allows you to load skins without relinking the application. You can even update your application without the need of restarting it. |
|
First we create a shared object from our `my_skin.cpp` file, and name it with the 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. |
