Author: cthomas
Publication Date: 9/30/2014 15:48

In the first article about FirstSpirit <RULES> we described what rules or dynamic forms in FirstSpirit are and provided several useful examples on how they can help you solve common requirements and increase the usability for the editors.

This second article will focus on ValueServices, a concept providing means to store the actual validation logic not on the rules tab of templates but in a FirstSpirit module implemented in Java. This offers new possibilities and more powerful functionality, making FirstSpirit rules even more versatile and useful.

Using a ValueService makes it possible to cover specific requirements that cannot be solved just by using the rules notation. To do this you implement your logic in a FirstSpirit module written in Java by simply implementing the ValueService interface and extending it with your custom code.

The Objective

Let us consider a case where links to external sites can be set by editors. To not have any dead links in the front end, these links should be checked for validity and availability during the editing process, allowing the editor to be notified of potential problems right away.

The Rule

Before implementing the ValueService itself we are going to take a look at how the ValueService is used in a rule on the FirstSpirit rules tab:

<ON_RELEASE>
    <SCHEDULE service="CheckURLValueService" id="checkURL" delay="100">
        <CONDITION>
            <MATCHES regex="^https?://[a-zA-Z0-9\-\.]+\.[a-zA-Z]{2,3}(/\S*)?$">
                <PROPERTY source="lt_url" name="VALUE" />
            </MATCHES>
        </CONDITION>
        <PARAM name="url">
            <PROPERTY source="lt_url" name="VALUE" />
        </PARAM>
    </SCHEDULE>
    
    <DO>
        <VALIDATION>
            <PROPERTY source="lt_url" name="VALID" />
            <MESSAGE lang="*" text="URL not available!" />
        </VALIDATION>
    </DO>
</ON_RELEASE>

As you can see we are using a <SCHEDULE>-part instead of the <WITH>-part mentioned in the first article of the series. The service-attribute must be the “name” of the public component (the ValueService class) as defined in the module.xml as described later on. The id-attribute has to be unique and is used by FirstSpirit to identify and distinguish ValueServices in cases where multiple <SCHEDULE>-rules are running and the delay-attribute can optionally set the time taken before the ValueServervice is triggered after user input.

The <CONDITION>-tag equals the <IF> part explained in the previous article and the <PARAM>-tags are used to transfer information from the current context to the ValueService.

The <CONDITION> in this example checks if the URL is well-formed and generally a valid URL using a simply regular expression, only valid URLs are passed on to the ValueService.

Everything else should look familiar to you from the previous article about rules. If it does not you should take your time and read that article first to refresh your memory.

The ValueService

As mentioned above you need to implement the ValueService interface providing and overriding a single method: getValue. Below we highlight some interesting parts of the ValueService. For the full source code as well as a compiled and ready-to-run FirstSpirit module (.fsm) please refer to the files attached to this post.

public class CheckURLValueService implements ValueService {

    private static final String PARAM_URL = "url";

    @Override
    public object getValue (final SpecialistsBroker specialistsBroker, final Map<String, ?> paramMap) {
        // ...
    }

}

First of all the class CheckURLValueService implements the ValueService interface and the interface method getValue is overridden by our own implementation. The static variable PARAM_URL holds the name of the input component passed by the rule. Having the basic setup in place we can now continue to implement our logic for getValue.

final String urlParam = (String) paramMap.get(PARAM_URL);

After getting the parameter named url passed to the ValueService by the rule described above (and making sure it actually was passed) the implementation check it for validity and availability using basic Java functionality. What the code basically does is:

• Make sure the URL is valid.
• Connect to the given URL using a HttpURLConnection.
• Check if the connection returns the status 200 OK.

If the URL is valid and reachable the ValueService returns true, indicating that everything is fine, otherwise it returns false so the error message defined is shown to the editor.

For the sake of the length of this article only the bare essentials are described here. Please refer to the attached source code for a more sophisticated example with the actual code, error checking, logging for debugging purposes  and more.

The module.xml

Having the implementation of the ValueService ready it needs to be installed as a module on the FirstSpirit server. To make it available you need a module description file (module.xml) similar to the one below and wrap everything up in a FirstSpirit module (.fsm) as described in the Manual for Module Developers (only available in German at the time of writing).

<module>
    <name>CheckURLValueService</name>
    <version>@VERSION@</version>
    <description>CheckURLValueService - Inside FirstSpirit Example</description>
    <vendor>e-Spirit AG</vendor>

    <resources>
        <resource scope="module">lib/CheckURLValueService-@VERSION@.jar</resource>
    </resources>

    <components>

        <public>
            <name>CheckURLValueService</name>
            <class>de.espirit.firstspirit.ps.blog.CheckURLValueService</class>
        </public>

        <web-app>
            <name>CheckURLValueService WebApp</name>
            <web-xml>web.xml</web-xml>
            <web-resources>
                <resource>lib/CheckURLValueService-@VERSION@.jar</resource>
            </web-resources>
        </web-app>

    </components>

</module>

In the module.xml the ValueService is added as a public component to make it available in all FirstSpirit contexts. You can access the ValueService in the rule using the defined <name> from the module.xml in the service parameter of the <SCHEDULE>-tag as shown above in the “The Rule” section.

The rule and the ValueService also work in the ContentCreator. You simply have to define the <web-app> section in the module.xml as shown above. The WebApp additionally has to be added as a web component to the ContentCreator environment for each project it is used in as described in the Manual for Administrators in chapter 7.4.18 “Web components”.

The End

In this article you have learned about ValueServices to leverage the full potential of FirstSpirit rules and dynamic forms. If you have any comments, questions or examples of clever ValueServices implemented in your projects we are more than happy if you share them with us in the comments to this article.

Tags: , fs5, module.xml, rules, valueservice, webapp