Improve Templates section (#65)

Author: decebals

_posts/2015-03-17-templates.md

@@ -6,12 +6,14 @@ date: 2015-03-17 17:37:21
 order: 40
 ---
 
-Not all applications are REST based and you might need to generate some HTML. 
-It is not productive to inline the HTML in strings in your code and concatenate them at request time.  
+Not all applications are `REST` based and you might need to generate some HTML.  
+It is not productive to inline the `HTML` in strings in your code and concatenate them at request time.  
 Pippo ships with Freemarker template engine as default and other engines as a builtin alternatives.  
-These engines are optional and Pippo detects automatically the template engine using __ServiceLocator__.  
-You can set programmatically the desired template engine using `setTemplateEngine(TemplateEngine templateEngine)` from
-__Appplication__.
+
+To use a template engine is optional and Pippo detects automatically the template engine using __ServiceLocator__.
+If you want to use a template engine in your application, you must add `pippo-<engine name>` as dependency for your project. 
+Other option is to set programmatically the desired template engine using `Application#setTemplateEngine(TemplateEngine templateEngine)`, 
+that in case that you want to create by hand the template engine.
 
 Pippo comes (out of the box) with some template engines:
 
@@ -32,24 +34,46 @@ To use one of these template engines just add a dependency in your project:
 </dependency>
 ```
 
-If you want to add support for other template engine in your application, please create a new module/project, add file 
-`ro.pippo.core.TemplateEngine` in _src/main/resources/META-INF/services_ folder with your class name that implements 
-TemplateEngine as content (for Jade the content file is _ro.pippo.jade.JadeTemplateEngine_).  
+All templates by default are localized in `/templates` folder (`src/main/resources/templates` for Maven projects).
+So, by default the templates are loaded from classpath.
+See below all templates from [pippo-demo-basic]({{ site.demourl }}/pippo-demo-basic) project:
+
+```bash
+$ tree src/main/resources/templates
+src/main/resources/templates
+├── files.ftl
+└── hello.ftl
+```
+
+You can change the location of templates by adding the following line in `conf/application.properties`:
 
-Bellow is a code snippet about how you can use a template as response to a request:
+```properties
+template.pathPrefix = /
+ ```
+
+Using above snippet we changed the templates location from `/templates` to `/`.
+Don't remember that the template will be loaded from classpath as resource.
+
+Below is a code snippet about how you can use a template as response to a request:
 
 ```java
 GET("/contact/{id}", routeContext -> {
+    // retrieve some request's parameters values
     int id = routeContext.getParameter("id").toInt(0);
     String action = routeContext.getParameter("action").toString("new");
 
+    // create the template model
     Map<String, Object> model = new HashMap<>();
     model.put("id", id);
     model.put("action", action)
+    
+    // render the template using data from model
     routeContext.render("contact", model);
 });
 ```
 
+In above route, Pippo will find a template with name "contact" and will respond with the result of rendering template by the template engine (a String).  
+
 Don't forget that `locals` variables from a response will be available automatically to all templates for the current request/response cycle.
 So, maybe the shortest version is:
 
@@ -61,9 +85,21 @@ GET("/contact/{id}", routeContext -> {
 });
 ```
 
- 
+From the above code snippets you can see that we call the `render` method with the template name as parameter but without extension.
+That means that you can change anytime the template file extension without to change the route handler code.
+Also, you can change the template engine without to change teh route handler code (for Freemarker template engine you supply a template `contact.ftl` file, 
+for Pebble template engine you supply a `contact.peb` file, and so on).
+
+Each template engine has a default file extension but you can change it if you want.
+For example, `PebbleTemplateEngine` has `peb` as default file extension but you can change it in `html`.
+The customization can be applied by adding the following line in `conf/application.properties`:
+
+```properties
+template.extension = html
+```
+
 For each template engine we expose its configuration. For example __Freemarker__ works with `freemarker.template.Configuration` and __Jade__ works with `de.neuland.jade4j.JadeConfiguration`.  
-In _Application.onInit_ you can create a new instance for a discovered template engine or you can modify its configuration.
+In _Application#onInit_ you can create a new instance for a discovered template engine or you can modify its configuration.
 
 ```java
 public class CrudApplication extends Application {
@@ -104,4 +140,21 @@ public class CrudApplication extends Application {
 }
 ```
 
+By default, all template engines disable the cache in `dev` and `test` mode (to speed the development - change template and refresh the page in browser) 
+and enable the cache in `prod` mode (to improve the performance). 
+
+Majority of builtin template engine supplied by Pippo, come with useful functions (extensions) that increase the readability of template:
+- webjarsAt
+- publicAt
+- i18n
+Read the documentation page allocated to each template engine for more information. The links to individual pages are presented in the start of this page.  
+ 
+If you want to add support for other template engine in your application you must follow below steps:
+- create a new module/project
+- create a class (ex. MyTemplateEngine) that extends `AbstractTemplateEngine` (or implements `TemplateEngine`)
+- mark your template engine class as service using one of the methods below  
+   - automatically via `@MetaInfServices` annotation (mark your template engine class with this annotation)
+   - manually, add file `ro.pippo.core.TemplateEngine` in _src/main/resources/META-INF/services_ folder with your class name that implements 
+TemplateEngine as content (for Jade the content file is _ro.pippo.jade.JadeTemplateEngine_).  
+
 For more information about how to implement a template engine please see _pippo-freemarker_ and _pippo-jade_ modules.