Sophora URL Library Guide

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:

<dependency>
    <groupId>com.subshell.sophora.webapp</groupId>
    <artifactId>sophora-url-spring-boot-starter</artifactId>
    <version>x.y.z</version> 
</dependency>

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

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

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:

sophora:
  url:
    create-url-without-site-prefix: false 
    default-domain: "http://localhost:8080"
    structure-path-to-domain: 
      "[/demosite]": "https://demosite.subshell"
      "[/demosite/trendcities]": "https://demosite.trendcities.subshell"

Optionally you can use the Sophora Image Service to handle URLs for image documents, this can be configured as follows:

sophora:
   url: 
     image-service-active: true
   image-service:
     url:
       default-domain: "https://images.subshell.com"
       structure-path-to-domain:
         "[/demosite]": "https://images.demosite.subshell.com"
         "[/demosite/trendcities]": "https://images.trendcities.subshell.com"

Configuration parameters:

If URLs for images are handled by the Sophora Image Service (enabled by setting sophora.url.image-service-active: true), there are two additional properties to configure the URLs for images.
These properties complement the property imageUrl in the site of the image document.

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:

Creation of URLs

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

urlBuilderProvider.forDocumentUuid(documentUuid)
    .absolute(true)
    .suffix("suffix")
    .templateType("type")
    .sophoraUrlParameter("param", "value")
    .queryParameter("key", "query")
    .build();

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:

If you want to use additional image URL features (e.g. image width or height), you should use the ImageUrlBuilder from the Sophora Image Service. Please read the documentation for the Image Service URL builder.

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:

@Component
@Primary
@RequiredArgsConstructor
public class CustomCodec implements ISophoraUrlCodec {

    private final DefaultSophoraUrlCodec defaultCodec; 

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

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