diff --git a/docs/src/orchid/resources/config.yml b/docs/src/orchid/resources/config.yml index fd5739ad6..0b829a135 100644 --- a/docs/src/orchid/resources/config.yml +++ b/docs/src/orchid/resources/config.yml @@ -11,6 +11,11 @@ theme: - type: 'page' title: 'Home' itemId: 'Home' + - type: 'page' + itemId: 'Spring Boot Integration' + - type: 'link' + title: 'Spring petclinic example' + url: 'https://github.com/PebbleTemplates/spring-petclinic' - type: 'page' itemId: 'Twig Compatibility' - type: 'page' diff --git a/docs/src/orchid/resources/homepage.md b/docs/src/orchid/resources/homepage.md index ad6e16e4c..5db135f2b 100644 --- a/docs/src/orchid/resources/homepage.md +++ b/docs/src/orchid/resources/homepage.md @@ -88,4 +88,5 @@ The output should result in the following: ``` For more information on installation and configuration, see {{ anchor('the installation guide', 'Installation and Configuration') }}.
-For more information on basic usage, see {{ anchor('the basic usage guide', 'Basic Usage') }}. \ No newline at end of file +For more information on basic usage, see {{ anchor('the basic usage guide', 'Basic Usage') }}.
+For Spring Boot integration, see {{ anchor('the Spring Boot integration guide', 'Spring Boot Integration') }}. \ No newline at end of file diff --git a/docs/src/orchid/resources/wiki/guide/spring-boot-integration.md b/docs/src/orchid/resources/wiki/guide/spring-boot-integration.md index 123d5af5c..5cc1095f8 100644 --- a/docs/src/orchid/resources/wiki/guide/spring-boot-integration.md +++ b/docs/src/orchid/resources/wiki/guide/spring-boot-integration.md @@ -2,7 +2,7 @@ --- # Pebble Spring Boot Starter -Spring Boot starter for autoconfiguring Pebble as an MVC ViewResolver. +Spring Boot starter for autoconfiguring Pebble. ## Basic Usage Add the starter dependency to your pom.xml: @@ -37,17 +37,10 @@ This is enough for autoconfiguration to kick in. This includes: * a Loader that will pick template files ending in ``.pebble`` from ``/templates/`` dir on the classpath * a PebbleEngine with default settings, configured with the previous loader +* a Spring extension which offers some functionality described below * a ViewResolver that will output ``text/html`` in ``UTF-8`` -PLEASE NOTE: the starter depends on ``spring-boot-starter-web`` but is marked as optional, you'll need to add the dependency yourself or configure Spring MVC appropiately. - -## Compatibility matrix -Pebble vs tested Boot versions (may work on older Boot releases). - -| Pebble Boot Starter | Spring Boot | -| --- | --- | -| 2.2.0+ | 1.2.1+ | -| 2.6.0+ | 2.0.1+ | +PLEASE NOTE: the starter depends on ``spring-boot-starter-web`` but is marked as optional, you'll need to add the dependency yourself or configure Spring MVC appropriately. ## Boot externalized configuration A number of properties can be defined in Spring Boot externalized configuration, eg. ``application.properties``, starting with the prefix ``pebble``. See the corresponding [PebbleProperties.java](https://github.com/PebbleTemplates/pebble/blob/master/pebble-spring/pebble-spring-boot-starter/src/main/java/com/mitchellbosecke/pebble/boot/autoconfigure/PebbleProperties.java) for your starter version. Notable properties are: @@ -62,6 +55,13 @@ A number of properties can be defined in Spring Boot externalized configuration, * ``pebble.defaultLocale``: defines the default locale that will be used to configure the PebbleEngine. Defaults to ``null`` * ``pebble.strictVariables``: enable or disable the strict variable checking in the PebbleEngine. Defaults to ``false`` +## Examples +There is the spring petclinic example which has been migrated to [pebble](https://github.com/PebbleTemplates/spring-petclinic) + +There is also a fully working example project located on [github](https://github.com/PebbleTemplates/pebble-example-spring) +which can be used as a reference. It is a very simple and bare-bones project designed to only portray the basics. +To build the project, simply run `mvn install` and then deploy the resulting war file to a an application container. + ## Customizing Pebble ### Pebble extensions Extensions defined as beans will be picked up and added to the PebbleEngine automatically: @@ -116,5 +116,83 @@ public PebbleReactiveViewResolver pebbleReactiveViewResolver() { PLEASE NOTE: you need to change the Loader's prefix and suffix to match the custom ViewResolver's values. +## Features +### Access to Spring beans +Spring beans are available to the template. +```twig +{% verbatim %}{{ beans.beanName }}{% endverbatim %} +``` + +### Access to http request +HttpServletRequest object is available to the template. +```twig +{% verbatim %}{{ request.contextPath }}{% endverbatim %} +``` + +### Access to http response +HttpServletResponse is available to the template. +```twig +{% verbatim %}{{ response.contentType }}{% endverbatim %} +``` + +### Access to http session +HttpSession is available to the template. +```twig +{% verbatim %}{{ session.maxInactiveInterval }}{% endverbatim %} +``` + +## Spring extension + +This extension has many functions for spring validation and the use of message bundle. + +### Href function +Function to automatically add the context path to a given url + +```twig +{% verbatim %}Example{% endverbatim %} +``` + +### Message function +It achieves the same thing as the i18n function, but instead, it uses the configured spring messageSource, typically the ResourceBundleMessageSource. + +```twig +{% verbatim %} +Label = {{ message('label.test') }} +Label with params = {{ message('label.test.params', 'params1', 'params2') }} +{%- endverbatim %} +``` + +### Spring validations and error messages +6 validations methods and error messages are exposed using spring BindingResult. It needs as a parameter the form name and for a particular field, the field name. + +To check if there's any error: +```twig +{% verbatim %} +{{ hasErrors('formName' }} + +{{ hasGlobalErrors('formName' }} + +{{ hasFieldErrors('formName', 'fieldName' }} +{%- endverbatim %} +``` + +To output any error: +```twig +{% verbatim %} +{% for err in getAllErrors('formName') %} +

{{ err }}

+{% endfor %} + +{% for err in getGlobalErrors('formName') %} +

{{ err }}

+{% endfor %} + +{% for err in getFieldErrors('formName', 'fieldName') %} +

{{ err }}

+{% endfor %} +{%- endverbatim %} +``` + ### Using Pebble for other tasks The main role of this starter is to configure Pebble for generating MVC View results (the typical HTML). You may define more PebbleEngine/Loader beans for other usage patterns (like generating email bodies). Bear in mind that you should not reuse the default Loader for other Engine instances. + diff --git a/docs/src/orchid/resources/wiki/guide/spring-integration.md b/docs/src/orchid/resources/wiki/guide/spring-integration.md deleted file mode 100644 index c47bc24a7..000000000 --- a/docs/src/orchid/resources/wiki/guide/spring-integration.md +++ /dev/null @@ -1,174 +0,0 @@ ---- ---- - -# Integration with Spring - -## Example -There is the spring petclinic example which has been migrated to [pebble](https://github.com/PebbleTemplates/spring-petclinic) - -There is also a fully working example project located on [github](https://github.com/PebbleTemplates/pebble-example-spring) -which can be used as a reference. It is a very simple and bare-bones project designed to only portray the basics. -To build the project, simply run `mvn install` and then deploy the resulting war file to a an application container. - -## Setup -Pebble has integration for both versions 3.x, 4.x and 5.x of the Spring Framework, provided by three separate libraries called pebble-spring3, pebble-spring4 and pebble-spring5. - -First of all, make sure your project includes the `pebble-spring3`, `pebble-spring4` or `pebble-spring5` dependency. -This will provide the necessary `ViewResolver` and `View` classes. -```xml - - io.pebbletemplates - pebble-spring{version} - {{ site.version }} - -``` -Secondly, make sure your templates are on the classpath (ex. `/WEB-INF/templates/`). Now you want to define a -`PebbleEngine` bean and a `PebbleViewResolver` in your configuration. -```java -@Configuration -@ComponentScan(basePackages = { "com.example.controller", "com.example.service" }) -@EnableWebMvc -public class MvcConfig extends WebMvcConfigurerAdapter { - - @Autowired - private ServletContext servletContext; - - @Bean - public Loader templateLoader(){ - return new ServletLoader(this.servletContext); - } - - @Bean - public SpringExtension springExtension() { - return new SpringExtension(); - } - - @Bean - public PebbleEngine pebbleEngine() { - return new PebbleEngine.Builder() - .loader(this.templateLoader()) - .extension(this.springExtension()) - .build(); - } - - @Bean - public ViewResolver viewResolver() { - PebbleViewResolver viewResolver = new PebbleViewResolver(); - viewResolver.setPrefix("/WEB-INF/templates/"); - viewResolver.setSuffix(".html"); - viewResolver.setPebbleEngine(this.pebbleEngine()); - return viewResolver; - } - -} -``` -Now the methods in your `@Controller` annotated classes can simply return the name of the template as you -normally would if using JSPs: -```java -@Controller -@RequestMapping(value = "/profile") -public class ProfileController { - - @Autowired - private UserService userService; - - @RequestMapping - public ModelAndView getUserProfile(@RequestParam("id") long id) { - ModelAndView mav = new ModelAndView(); - mav.addObject("user", this.userService.getUser(id)); - mav.setViewName("profile"); - return mav; - } - -} -``` -The above example will render `\WEB-INF\templates\profile.html` and the "user" object will be available -in the evaluation context. - -## Features - -### Access to Spring beans -Spring beans are now available to the template. -```twig -{% verbatim %}{{ beans.beanName }}{% endverbatim %} -``` - -### Access to http request -HttpServletRequest object is available to the template. -```twig -{% verbatim %}{{ request.contextPath }}{% endverbatim %} -``` - -### Access to http response -HttpServletResponse is available to the template. -```twig -{% verbatim %}{{ response.contentType }}{% endverbatim %} -``` - -### Access to http session -HttpSession is available to the template. -```twig -{% verbatim %}{{ session.maxInactiveInterval }}{% endverbatim %} -``` - -## Spring extension - -This extension has many functions for spring validation and the use of message bundle. - -#### Href function -Function to automatically add the context path to a given url - -```twig -{% verbatim %}Example{% endverbatim %} -``` - -#### Message function -It achieves the same thing as the i18n function, but instead, it uses the configured spring messageSource, typically the ResourceBundleMessageSource. - -```twig -{% verbatim %} -Label = {{ message('label.test') }} -Label with params = {{ message('label.test.params', 'params1', 'params2') }} -{%- endverbatim %} -``` - -#### Spring validations and error messages -6 validations methods and error messages are exposed using spring BindingResult. It needs as a parameter the form name and for a particular field, the field name. - -To check if there's any error: -```twig -{% verbatim %} -{{ hasErrors('formName' }} - -{{ hasGlobalErrors('formName' }} - -{{ hasFieldErrors('formName', 'fieldName' }} -{%- endverbatim %} -``` - -To output any error: -```twig -{% verbatim %} -{% for err in getAllErrors('formName') %} -

{{ err }}

-{% endfor %} - -{% for err in getGlobalErrors('formName') %} -

{{ err }}

-{% endfor %} - -{% for err in getFieldErrors('formName', 'fieldName') %} -

{{ err }}

-{% endfor %} -{%- endverbatim %} -``` - -## Timer - -A timer in PebbleView is available to output the time taken to process a template. Just add the following config to your log4j.xml - -```xml - - - -``` diff --git a/docs/src/orchid/resources/wiki/summary.md b/docs/src/orchid/resources/wiki/summary.md index ef3a96233..5209ffed2 100644 --- a/docs/src/orchid/resources/wiki/summary.md +++ b/docs/src/orchid/resources/wiki/summary.md @@ -1,9 +1,8 @@ ## Guides - [Installation and Configuration](guide/installation.md) -- [Spring Integration](guide/spring-integration.md) - [Spring Boot Integration](guide/spring-boot-integration.md) -- [Pebble Spring Example](https://github.com/PebbleTemplates/pebble-example-spring) - [Spring petclinic](https://github.com/PebbleTemplates/spring-petclinic) +- [Pebble Spring Example](https://github.com/PebbleTemplates/pebble-example-spring) - [Basic Usage](guide/basic-usage.md) - [Escaping](guide/escaping.md) - [Extending Pebble](guide/extending-pebble.md)