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:

<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:
    createUrlWithoutSitePrefix: false 
    domainName: "http://localhost:8080"

Configuration parameters:

Local configuration parameters
KeyDescription
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)
domainNameSpecifies the domain for absolute URLs (scheme://host:port").
This configuration overrides the Sophora-Site URL property for document-URL retrieval. Note that static asset URLs will be relative if left blank.

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:

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

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
	}
 
 }

Last modified on 9/3/21

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

Icon