Joget Workflow v6 Beta 3 Released
Check out the latest Joget Workflow v6 Beta for many new features and improvements in user experience (UX), app maintainability and performance.
In this tutorial, we will be following the guideline for developing a plugin to develop our Bean Shell Hash Variable plugin.
Hash variable is convenient to use, but sometime we want to do some condition check before displaying a value. But, Hash variable does not provide the ability for condition checking.
By looking at the Plugin Types that are currently supported by Joget Workflow, we can develop a Hash Variable Plugin to allow us to write our scripting for condition checking. There are quite a number of Bean Shell plugins provided as default plugin for several plugin types. We can do one for Hash Variable plugin as well.
Hash Variable plugin does not provide interface for user to configure, but to develop a Bean Shell Hash Variable plugin, we need somewhere to put our Bean Shell script. We can reuse the Environment Variable to store our script. So the Hash Variable syntax will be a prefix with environment variable key.
But, this may not be enough, we may need some other way to pass in some variable also. We can consider using a URL query parameters syntax to pass in our variables because it is easier to parse later on.
What do we expected from this Bean Shell Hash variable plugin? The Bean Shell Hash Variable plugin is for admin/developer user to use when building/developing an app. Once used, the Hash Variable will be replaced by the output return from the Bean Shell interpreter. So that the admin user can do condition check before display something to normal user.
E.g. Display a welcome message for logged in user but display nothing when the user is an anonymous.
To develop Bean Shell Hash Variable plugin, we can refer to the source code of all the Hash Variable plugin and Bean Shell plugin. Especially, we can refer to the Environment Variable Hash Variable plugin on how to retrieve environment variable using a variable key. We can also refer to the Bean Shell Tool or Bean Shell Form Binder plugin on what to execute the script with Bean Shell interpreter.
We can use getUrlParams method from StringUtil to help us parse parameters passed in with URL query parameters syntax.
We need to always have our Joget Workflow Source Code ready and builded by following this guideline.
The following tutorial is prepared with a Macbook Pro and Joget Source Code version 5.0.0. Please refer to the Guideline for developing a plugin article for other platform commands.
Let say our folder directory is as following.
The "plugins" directory is the folder we will create and store all our plugins and the "jw-community" directory is where the Joget Workflow Source code stored.
Run the following command to create a maven project in "plugins" directory.
Then, the shell script will ask us to key in a version number for the plugin and ask us for a confirmation before it generates the maven project.
We should get "BUILD SUCCESS" message shown in our terminal and a "beanshell_hash_variable" folder created in "plugins" folder.
Open the maven project with your favour IDE. I will be using NetBeans.
Create a "BeanShellHashVariable" class under "org.joget.tutorial" package.
Then, based on Hash Variable Plugin document, we will have to extends org.joget.apps.app.model.DefaultHashVariablePlugin abstract class.
Let us implement all the abstract methods. We will be using AppPluginUtil.getMessage method to support i18n and using constant variable MESSAGE_PATH for message resource bundle directory.
Now, let's focus on the main method of our Hash Variable plugin which is processHashVariable. We will refer to the source code of Environment Variable Hash Variable plugin on how to retrieve the Environment variable. Then, refer to the source code of Bean Shell Form Binder on how to execute a bean shell script.
Our plugin class cannot resolve "bsh.Interpreter". So, we will have to add bean shell library to our POM file.
We are using AppPluginUtil.getMessage method to display i18n value for our getLabel and getDescription method. We will have to create a message resource bundle properties file for it. Create directory "resources/messages" under "beanshell_hash_variable/src/main" directory. Then, create a "BeanShellHashVariable.properties" file in the folder.
In our properties file, we will need to add the key we have used.
We will have to register our plugin class in Activator class to tell the Felix Framework that this is a plugin.
Let build our plugin. Once the building process is done, we will find that a "beanshell_hash_variable-5.0.0.jar" file is created under "beanshell_hash_variable/target" directory.
Then, let's upload the plugin jar to Manage Plugins. After uploading the jar file, double check that the plugin is uploaded and activated correctly.
Now, let's test our plugin.
Let assume that we have a HTML menu page in a userview that wants to display the following line to logged in user. Normally, we will use "Welcome #currentUser,username#," to display a welcome message.
But, in this use case there is a problem, which shows "Welcome ," without an username when the user is an anonymous.
Now, change the whole message to our Bean Shell Hash Variable and create an environment variable to put our script.
to the following. We will need to pass the current user's username as one of our parameters and do not forget to escape it as url.
Then, we can create an environment variable with ID "welcome" and use the following script. As we are using getUrlParams method from StringUtil to parse the parameters, all value from parameters are String array.
Let go back to our HTML menu page to see the result.
When user is logged in, it shows the message correctly.
When no user is logged in, the welcome message is not shown.
You can download the source code from beanshell_hash_variable.zip.
To download the ready-to-use plugin jar, please find it in http://marketplace.joget.org/.