Configuration of user-specific Advanced URLs

FirstSpirit 5 saw the introduction of interfaces and a reference implementation (“Advanced URL Creator”) which support the integration of different path strategies for generating URLs into FirstSpirit. The generation of the URLs is delegated to a UrlFactory. Alongside the reference implementation to improve URL generation (“Advanced URLs” setting in the project properties), these interfaces can be used to implement new customer-specific path strategies and integrate them into FirstSpirit as modules.

All classes which implement the UrlFactory interface support the passing of parameters and values for configuring URL generation. To ensure that this data, which is made available to the UrlFactory.init(…) method, can persist, class-internal fields for saving the configuration setting are defined:

public class UrlCreatorExample implements UrlFactory {

    // Fields for persistence during the object's life cycle.
    private PathLookup _pathLookup;
    private boolean _useWelcomeFilenames;

    public void init(final Map<String, String> settings, final PathLookup pathLookup) {   
        _pathLookup = pathLookup;
        _useWelcomeFilenames = settings.get("usewelcomefilenames");
        ....
   }
   ...
}

The init(…) method is called every time a UrlFactory object is instantiated so that the object can be initialized with data that cannot change during a generation process. When the method is called, a map object containing the configuration parameters is made available along with a PathLookup object which can be used to query user-defined URLs on Store directories.

For an example application, see reference implementation “Advanced URL Creator”.

Passing of configuration parameters

All configuration parameters must be defined either using a job script that is executed BEFORE the actual generation schedule or with the configuration settings in the module.xml file.

Passing with script:

Passing with predefined script in job management (in the project properties), e.g.,

context.setProperty("#urlCreatorSettings", Collections.singletonMap("usewelcomefilenames", "true")); 

More standard configuration parameters and other user-defined parameters can be passed in the same way. These parameters must subsequently be passed to the corresponding URL Creator implementation (see above).

Passing with module.xml:

Instead of being passed in a predefined script, the configuration parameters can be defined in the module.xml file in the <configuration> tags, e.g.,

<module>
	<name>UrlFactory Example</name>
...
<components>
        <public>
            <name>Advanced URLs Example Module</name>
            <class>firstspirit.generate.UrlCreatorSpecificationImpl</class>
            <configuration>
                <UrlFactory>examples.urlfactory.UrlFactoryExample</UrlFactory>
                <useWelcomeFileNames>yes</useWelcomeFileNames>
            </configuration>
        </public>
	</components>
 ...
</module>

Standard configuration parameters

The FirstSpirit framework evaluates some standard parameters:

• useWelcomeFileNames
• stripWelcomeFileNames
• useIRIs
• useRegistry
• removeDeleted
• useLowercase

(Use of upper or lower cases for the parameters is not relevant, i.e. useIRIs, UseIris or UseIRIs are the same parameter.)

useWelcomeFileNames

The “useWelcomeFileNames” parameter can be used to configure start page references.

context.setProperty("#urlCreatorSettings", Collections.singletonMap("usewelcomefilenames", "true"));

If the parameter is passed with the value “true” (default value), the file name “index.*” is always provided for page references which are marked as the start page of a folder in the Site Store when an Advanced URL is generated (regardless of the display name or the file name from the properties dialog).

In standard URL generation mode,

../de/startpage/mithras_home.html
../en/startpage/mithras_home.html

become the following in advanced mode with “useWelcomeFileNames”:

../Startseite/index.html
../Startpage/index.html

For page references which are not marked as start pages, on the other hand, the display name continues to be used when the Advanced URL is generated.

If the parameter is passed with the value “false”, regardless of whether a page reference is a start page or not, the URLs are generated based on the display name of the page reference (with the blank space being replaced by a “-” character):

../Startseite/Mithras-Homepage.html
../Startpage/Mithras-Homepage.html

This parameter is used in the Advanced URL Creator reference implementation (see above).

In the case of self-referencing (i.e., when the page currently being generated contains itself, e.g., within the navigation), an empty string "" is returned instead of the Advanced URL.

stripWelcomeFileNames

The “stripWelcomeFileNames” parameter is only relevant if the URL path strategy used also uses the “useWelcomeFileNames” configuration parameter. The “stripWelcomeFileNames” parameter can be used to remove the “/index.*” extension added by “useWelcomeFileNames” from the Advanced URL (but not from the file name under which the file is stored in the file system).

creatorSettings = new HashMap(); 
creatorSettings.put("usewelcomefilenames", "true");  
creatorSettings.put("stripwelcomefilenames", "true");  
context.setProperty("#urlCreatorSettings", creatorSettings);  

If the “useWelcomeFileNames” and “stripWelcomeFileNames” are passed with the value “true” (default value), the display name of the start page is removed from the Advanced URL for page references which are marked as the start page of a folder in the Site Store.

For instance, in standard URL mode,

../de/startpage/mithras_home.html
../en/startpage/mithras_home.html

become the following (in the file system) in advanced mode with “useWelcomeFileNames” and “stripWelcomeFileNames”:

../Startseite/index.html
../Startpage/index.html

and the Advanced URL:

../Startseite
../Startpage

As a result, although the start page of the “Startpage” folder is created in the file system with the extension “/index.*”, it can (if the web server has been configured accordingly) be called via the “/Startpage/” URL.

If the project contains more than one presentation channel, “stripWelcomeFileNames” only removes “index.{master extension}”. “Master extension” is the file extension from the first presentation channel (usually “html”).

If the “stripWelcomeFileNames” parameter is passed with the value “false”, the extension “/index.*” is retained for all start page references both in the file system and in the Advanced URL.

useIRIs

Where object names are concerned, FirstSpirit draws a strict distinction between display names (not unique, can be edited in multiple languages, support Unicode) and reference names (unique within the namespace, restricted to letters and numbers, i.e., do not support Unicode). While display names are relevant for editorial work and can be changed at any time by the editor, reference names are usually only needed by the template developer or for the purpose of internal intervention in the system and cannot be changed (or can only be changed with great difficulty). This two-layer naming convention has proven its worth in practice, but does lead to reference names having to be used in some places. For example, according to the specification, URLs can only contain US ASCII characters, whereas non-ASCII characters can only be encoded with UTF-8.

Thus, when Advanced URLs are generated, they are based on the display name of the FirstSpirit objects, which may contain illegal characters (umlauts, blank spaces, or similar). Some illegal characters are replaced one-to-one when Advanced URLs are generated (regardless of configuration with “useIRIs”). Accordingly, as a general rule, leading and trailing white spaces are removed from URLs and following characters as well as other spaces are replaced by (-):

 \ / , : ; * ? " < > |  # @ = & + % $

(% since FirstSpirit version )

The “useIRIs” parameter (default value “true”) is used to generate all URLs in UTF-8, inclusive of spaces and special characters.

context.setProperty("#urlCreatorSettings", Collections.singletonMap("useiris", "true"));

For instance, in standard URL mode,

../de/marketing/aboutus.html
../en/marketing/aboutus.html

become the following in advanced mode with “useIRIs”:

../Marketing/Über-uns.html
../Marketing/About-us.html

and the following in advanced mode without “useIRIs”:

../Marketing/%C3%9Cber-uns.html
../Marketing/About-us.html

The “useIRIs” parameter does not affect file names, only the Advanced URL generated (in the same way as the “stripWelcomeFileNames”) parameter.

useRegistry

The URL generation for a project can be manipulated via the “global settings” in FirstSpirit SiteArchitect. For example, “short URLs” for certain project content (e.g., for “landing pages”) can be configured here. This makes it possible to generate short, “meaningful” URLs that are easily remembered for certain content, in addition to the normal URLs. These concepts (short URLs, SEO URLs) are only effective if the Advanced URLs are saved in a persistence structure in which each object is assigned a URL that is unique across the entire project.

If the “useRegistry” parameter is passed with the value “true” (default value), all new Advanced URLs generated are saved in the project registry. In this case, the underlying URL Creator implementation can read the URLs from the persistence structure and/or save new URLs in the persistence structure.

context.setProperty("#urlCreatorSettings", Collections.singletonMap("useregistry", "true"));

The registry can grow significantly during the lifetime of a project, since URLs are retained once they have been saved. If, for example, an object is deleted from within a project, the URL saved for this object is retained so that the URL can be restored automatically if the object is restored (see also Saving and resetting URLs for more information). The deletion of saved Advanced URLs can be configured with the “removeDeleted” parameter.

removeDeleted

The “removeDeleted” parameter is only relevant if the URL path strategy used also uses the “useRegistry” configuration parameter.

creatorSettings = new HashMap();
creatorSettings.put("useregistry", "true"); 
creatorSettings.put("removedeleted", "true"); 
context.setProperty("#urlCreatorSettings", creatorSettings);

If the “removeDeleted” parameter is passed with the value “true” (default value “false”), URLs on objects which have already been deleted can also be removed from the registry. The standard procedure is that the Advanced URLs are retained in the project registry so that if a deleted object is restored in the project, the URL generated for this object can also be restored automatically.

In worst-case scenarios,the registry can grow significantly during the lifetime of a project. If, for example, a page reference in a project is deleted which contains a PageGroup relating to a content projection, many thousands of saved URLs can quickly be associated with this page reference (even via deleted datasets).

Another application is the resolving of URL conflicts in a project. The use of the “useWelcomeFileNames” parameter can lead to problems, for example. Since URLs are assigned once and are unique within a project, once an “index” entry has been generated for a start page, it is retained, even if the associated page reference has already been removed from the project. New start pages are then automatically assigned a consecutive number instead of

../Startseite/index.html

and therefore become:

../Startseite/index.1.html

To resolve this conflict, the old index entry must first be removed from the registry.

Removing an Advanced URL from the persistence structure can potentially create invalid links in a project (when deleted objects are restored).

useLowercase

In Windows, it does not matter whether upper or lower case is used for files and folders, i.e., the folders “abc”, “Abc” and “ABC” are the same folder.

By contrast, for Unix file systems, upper and lower case are distinguishing features for files and folders. Therefore, this may lead to conflicts if the files are generated in Linux and then transferred to a Windows system, for example.

You can influence whether upper or lower case is used when files and folders are generated using the “useLowercase” parameter:

If the parameter is transferred with the value “false”, the upper/lower case of display names in the project is taken into account when Advanced URLs are generated. This is the default behavior.

If the parameter is transferred with the value “true”, lower case is used for file and folder name generation.

Example:
A project contains two structure folders (menu levels) with the display names “Folder” and “folder”.
If generated with the value “false” for “useLowercase”, the following Advanced URLs are formed:

/folder/index.html
/Folder/index.html

If generated with the value “true” for “useLowercase” , the following Advanced URLs are formed:

/folder/index.html
/folder/index-2.html