Web App Framework | Version 4

Routing Module

Configuration and code examples for processing requests and generating HTML for Sophora documents and static resources.

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.


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

Maven Dependency


Routing Configuration

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

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

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

Possible keys for list elements in sophora.web.routing.node-types
nameThe name of the node type to match. The special type all matches all node types if there is no specific mapping for a node type.
types.nameThe name of the mapping type in the request URL. If "default", the type has not to be specified in the URL. E.G. the mapping type in the following URL would be print: https://subshell.com/test/example-story100~print.html
types.templateThe path to the template file that should be used.
types.servlet.nameThe registered path of the servlet to use. Check out our predefined servlets in the Additional Components module.
types.servlet.propertiesGeneric map of individual properties for the specified servlet
types.forwardAny URL the request will be forwarded to.


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.

  - name: "sophora-example-nt:story"
      - 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 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:

      site: mySite


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:

Explanation of the static resource URL parts
domainThe configured domain of the URL module configuration. Will only be present when an absolute URL will be generated and if the domain-name is configured.
siteThe configured site name. Will only be present, when URL module configuration does not prohibit the site prefix.
assetPathThe relative path to the concrete asset the URL has been generated for. This should usually start with "/resources/"

Last modified on 3/20/23

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.