URL Library | Version 4

Sophora URL Library Guide

Configuration and code examples to create and parse URLs for Sophora documents.

The Sophora URL Library supports creation and parsing of URLs for Sophora documents like <scheme>://<domain>/<structure path>/<Sophora-ID>.html (e.g.: https://www.subshell.com/hamburg/hallo-welt-100.html)

Maven Dependency

First you need to add the URL Library to your pom.xml. If you use Spring Boot in your application we recommend to import sophora-url-spring-boot-starter library that includes an implementation of all necessary interfaces:


Otherwise you need to add sophora-url-client library,


Implement the ISophoraUrlConfigProvider interface to provide the configuration for the URL library and add com.subshell.sophora.url.client.UrlClientSpringConfig to your components scan to load all spring classes from the module.

URL configuration

The configuration of the Sophora URL Library is distributed between local (for current application) and global (for whole Sophora environment) configurations:

Local configuration

The configuration of the Sophora URL Library for the current application is described in your application.yml under the sophora.url prefix:

    createUrlWithoutSitePrefix: false 
    defaultDomain: "http://localhost:8080"
      "[/demosite]": "https://demosite.subshell"
      "[/demosite/trendcities]": "https://demosite.trendcities.subshell"

Configuration parameters:

Local configuration parameters
createUrlWithoutSitePrefixFlag if paths in generated URLs should be created without Sophora-Site prefix (e.q. /site/structurepath/sophora-id-123.html or /structurepath/sophora-id-123.html)
defaultDomainSpecifies the domain for absolute URLs (scheme://host:port").
This domain will be used if neither the document's Sophora-Site URL nor a matching structurePathToDomain is present.
Note that static asset URLs will be relative if left blank.
imageServiceActiveFlag if URLs for images should be handled by the Sophora Image Service.
structurePathToDomainMaps a structure path to a domain for absolute URLs (<scheme>://<host>:<port>). A document's absolute URL will have the domain corresponding to the longest prefix match for the configured structure paths. If this mapping provides a domain, the Sophora-Site URL property and the configured defaultDomain have no effect. Structure paths need to be encapsulated in brackets (see this spring-boot issue)

Global configuration

The global configuration is related to all applications using the Sophora URL Library. It is defined in a Sophora configuration document with the external ID sophora-url-configuration and describes following properties:

Global configuration parameters
Property nameDescription
sophora:slugPropertyNameDefines a property name in Sophora documents whose content will be used as slug in generated URLs

Creation of URLs

To create URLs for Sophora documents or structure nodes use the com.subshell.sophora.url.builder.UrlBuilderProvider bean:

    .sophoraUrlParameter("param", "value")
    .queryParameter("key", "query")

It will produce a URL like: https://localhost:8080/site/structurepath/sophora-id-123~type_param-value.suffix?key=query

Special Sophora URL parameters

If the Sophora-Image-Service is configured to handle URLs for images the following Sophora URL parameters can be used to provide additional information to the Image Service:

Parameters for Sophora-Image-Service
Sophora URL parameterPurpose in Image Service
vThe name of an image variant
overlayDocumentExternalIdThe external ID of an image document which will be used as overlay

Define custom URL codec

Creation and parsing of URLs is based on a URL Codec. The URL Library provides a default Sophora URL codec. But the application can as well define a custom codec to encode and decode URLs by providing a central Spring component implementing the interface ISophoraUrlCodec.

The following example shows how a custom URL codec can use the default codec internally to modify standard URLs:

public class CustomCodec implements ISophoraUrlCodec {

    private final DefaultSophoraUrlCodec defaultCodec; 

    public String encode(SophoraUrl sophoraUrl) { 
        String defaultUrl = defaultCodec.encode(sophoraUrl); 
        // modify default url

	public Optional<SophoraUrl> decode(String url) {
		Optional<SophoraUrl> defaultSophoraUrlOpt = defaultCodec.decode(url);
		if (defaultSophoraUrlOpt.isEmpty()) {
			return Optional.empty();
		// modify default SophoraUrl

Last modified on 2/21/23

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