Example 4: Configuration

If you can't play the video, make sure that you are logged in at Wex Solutions.

• What will we do? - Learn how to add a configuration and the supported types of configuration

• What do you need? - Site access to a non-production Windchill

• How long will it take - 8 minutes

The purpose of this example is to demonstrate how to add a configuration UI to a Windchill Extension. If you want to learn more about WEX configuration, be sure to check out the Configuration section of the Developer Guide.

You can find the code for this example in our GitHub repository.

Implementation

A WEX's configuration is implemented with a single Java file. In this example, you'll find it under com/wincomplm/wex/example/config/impl/config/ExampleConfiguration.java. This file implements the following fields:

    @ConfigOption(category = "Basic", description = "Simple string", required = false)
    String exampleString = "bad";

    @ConfigOption(category = "Basic", description = "Boolean",
            longdesc = "A true/false boolean", required = false)
    boolean exampleBoolean = false;

    @ConfigOption(category = "Collections", description = "String list",
            longdesc = "A string list", required = false)
    List<String> exampleList = new ArrayList();

    @ConfigOption(category = "Collections", description = "String map",
            longdesc = "A string map", required = false)
    Map<String,String> exampleMap = new HashMap();

    @ConfigOption(category = "Collections", description = "String list with handler",
            longdesc = "String list with handler", required = false, handler = LifeCycleStateHandler.class)
    List<String> exampleStateList = new ArrayList();

The @ConfigOption tab is used to define each of the fields that will appear in the configuration's UI. It takes in several paremeters:

• category: This defines under which headline the field will appear. It is used to separate the UI into several blocks: it is good practice that conceptually related fields fall into the same block for a better and easier user experience.
• description: A short description.
• longdesc: A string that will appear when the mouse hovers over the field. It is useful when the developer needs to provide extra information that the user might need when filling the field.
• required: A boolean that determines if the field can be left blank or not.
• handler: An optional field that offers the possibility of attaching a handler class to the field, which provides a closed set of options that can be used to populate it.

It is good practice to implement validation checks for the fields that need it. An example of a validation would look like this.

@Override
public void validate() throws WexValidationException {
    // We ccheck the consistency of the data here
    if (exampleString.equals("bad")) {
        throw new WexValidationException("exampleString","Please change to not bad!");
    }
}

The developer might also choose to set up a test JSP to verify the data held by the config:

@WexComponent(uid = "methods", description = "Wex Diagnostic Methods")
public class ExampleMethods {

    public static ExampleConfiguration config = (ExampleConfiguration) WexConfigRegistryHelper.instance.getConfig();

    @WexMethod(name = "test", description = "Display configuration")
    public String test() throws Exception {
        // This is test code but generally rendering HTML server side is not a good practice ;-)
        final String EOL = "<br>";
        String result = "";
        result += "Example String: " + config.getExampleString() + EOL;
        result += "Example Boolean: " + config.isExampleBoolean()+ EOL;
        result += "Example List: " + config.getExampleList()+ EOL;
        result += "Example Map: " + config.getExampleMap()+ EOL;
        result += "Example State List: " + config.getExampleStateList()+ EOL;
        return result;
    }//string

}

Execution

The configuration UI can be accessed through the Extension Manager:

Once the icon is clicked, the following UI will appear which offers the possibility of updating the data:

Note that if you enter "bad" in the Simple string, a warning will appear. This is triggered by the validation previously implemented in the configuration's Java file.

You can use the test page from the WEX's User Guide in order to test if the changes you made to the fields actually made it to the system.

Clicking on the link will show the current configuration values:

Passwords

The configuration can be used to store passwords using the hidden flag

@ConfigOption(category = "Security", description = "Password", required = false, hidden=true)
String examplePassword = "";

For security the password is only show whilst being edited, from wex-config 1.36