Adjust spring boot doc

PebbleTemplates · May 3, 2020 · b64df06 · b64df06
1 parent dce0a26
commit b64df06
Show file tree

Hide file tree

Showing 5 changed files with 96 additions and 187 deletions.
diff --git 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
@@ -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') }}.<br/>
-For more information on basic usage, see {{ anchor('the basic usage guide', 'Basic Usage') }}.
+For more information on basic usage, see {{ anchor('the basic usage guide', 'Basic Usage') }}.<br/>
+For Spring Boot integration, see {{ anchor('the Spring Boot integration guide', 'Spring Boot Integration') }}.
diff --git 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 %}<a href="{{ href('/foobar') }}">Example</a>{% 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') %}
+    <p>{{ err }}</p>
+{% endfor %}
+
+{% for err in getGlobalErrors('formName') %}
+    <p>{{ err }}</p>
+{% endfor %}
+
+{% for err in getFieldErrors('formName', 'fieldName') %}
+    <p>{{ err }}</p>
+{% 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
diff --git 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)