Routing Module

The task of the Routing Module is to process HTTP requests and to perform an appropriate HTTP response depending on the requested Sophora document. Corresponding entries of redirect documents will also be processed.

Setup

Make sure that the RoutingSpringConfig is imported (e.g. via Spring auto configuration) to load all spring classes of this module.

Maven Dependency

<dependency>
     <groupId>com.subshell.sophora.webapp</groupId>
     <artifactId>sophora-webapp-routing</artifactId>
     <version>x.y.z</version>
</dependency>

Routing Configuration

The routing configuration is done in the application.yml of the Sophora Web Application Framework. Here is a sample extract:

sophora:
  web: 
    routing:
      node-types:
        - name: all # special type for all node types 
          types:
            - name: print
              template: "/common/print.html"
        - name: "sophora-example-nt:image"
          types: 
            - name: default
              servlet:
                name: "/system/com.subshell.sophora.webapp.components.servlet.image.ImageServlet"
                properties: {}

Possible keys for list elements in sophora.web.routing.node-types

Templates

Template routing is configured in the application.yml. The following sample would route /site/path/example-story100.html to the story.html template and /site/path/example-story100~print.html to the story-print.html template, assuming that example-story100 is of type sophora-example-nt:story and the given structure path (including the site) exists.

node-types:
  - name: "sophora-example-nt:story"
    types:
      - name: default
        template: "/document/story.html"
      - name: print
        template: "/document/story-print.html"

Dynamic Content in Templates

Per default, the requested document and its properties are available in a template via the sophoraDocument attribute. The provided object is of type com.subshell.sophora.client.ISophoraDocument.

Additional attributes can be made available by implementing the IRoutingModelMapProvider interface. You will also have to provide a bean of the implementing class. All attributes returned by IRoutingModelMapProvider#getModelMap are then available in the document. If the map contains existing attributes, such as the sophoraDocument attribute, they are overwritten.

Redirects

Redirects are configured in redirect documents. No further configuration is needed in the WebApp.

Custom Response Header

Custom headers in your response can be set by implementing the com.subshell.sophora.webapp.routing.configuration.IResponseHeaderProvider interface. You will also have to provide a bean of the implementing class. All key-value pairs returned by IResponseHeaderProvider#getHeaders are added to the response header. Per default, this is done after verifying that the requested document exists and before forwarding. Therefore, Servlets that also set custom headers may simply overwrite any header from the IResponseHeaderProvider.

For headers of custom redirects, all headers set on the AbstractRequestTarget returned by ICustomRedirectBuilder#getTargetForRequest will be added to the redirect response.

Static Resources

The static resources of a WebApp must be located within the classpath in one of the folders META-INF/resources/, resources/, static/ or public/. These locations are derived from the standard locations for static resources used by the Spring Boot framework. If you need a custom folder setup, you can configure the folders with the default property used by Spring Boot. Usually you create a folder like public in the folder src/main/resources of your Web App project and save your static resources in this folder.

If a static resource is requested, the configured locations are scanned in the specified order. If more than one folder within the classpath contains the requested resource, the first match will be chosen and delivered. If you want to overwrite a resource from a dependency within your own Web App, make sure that it is placed in a suitable folder within your project so that the static resource in the dependency will not be found first.

The static resources of a Web App must be located within the resources folder. You will also have to provide the site name:

sophora:
  web: 
    routing:
      site: mySite

StaticAssetUrlBuilder

If you want to generate URLs for your static resources, you may use the com.subshell.sophora.webapp.routing.asset.StaticAssetUrlBuilder. The StaticAssetUrlBuilder will generate URLs with the following format:

[domain]/[site]/<assetPath>

Links in templates

Links in templates must contain a relative path and must start with a Slash. Those links will be replaced with their full relative form before the HTML is send.

Example:

<link rel="stylesheet" th:href="@{'/resources/assets/css/main.css'}" />

The above example to the main.css file will be prefixed with the site (if configured). So the resulting URL in the final HTML may look like this:

/mySite/resource/assets/css/main.css