We use plugin setting to explain how to use the bean editor to generate plugin UI. As introduced in [QBTEAM:Write a Simple Plugin], user can provide a plugin setting class by overriding getPluginSettingClass() method in the plugin class. If provided, this class will be used by QuickBuild to generate plugin setting user interface. The setting will be saved as an instance of this class and can be retrieved later through getPluginSetting() method when this plugin runs. Let's start with a very simple plugin setting class:
By specifying the @Editable annotation for getter method, that property will be editable with user interface. The generated interface to edit this plugin setting looks as following:
- The bean for which the editor is generated must have a default constructor.
- order attribute need to be specified for @Editable annotation to make sure that properties are displayed in the correct order.
- The name and description attribute of the @Editable annotation is optional. Name attribute is used to specify the display name of the property and description is used to specify the description of this property which will be displayed when a user hovers the mouse over the question mark icon next to the the property name in the user interface.
- Validation annotations can be applied to the properties in order to put constraint on the values of the certain properties. Refer to [Bean Validator] for details.
- Some helper annotation can be added to specify how the property should be edited. For example:
By specifying @Multiline annotation for the name property, the editor for the name property will be displayed as textarea with specified number of rows.
By specifying @ChoiceProvider for the name property, the editor for the name property will have a dropdown icon next to the input box, to help user to choose from the set of predefined values of this property. The predefined values are provided by calling a method specified as value attribute of the @ChoiceProvider annotation.
Some other helper annotations are:
- @Password: by specifying this annotation, the property will be displayed as a password field.
- @Color: by specifying this annotation, a color picker will be displayed next to the input box, and the input value will be validated against color formats, in the form of rrggbb.
QuickBuild editor is able to generate user interface to edit list if the list element is of the same type. For example in the above plugin, we add a new property of type List to this class as follows:
And the Dog bean is defined as:
The resulting edit page will look like:
Please note that:
- Element type of the list needs to be specified. There are two ways to specify the element type: by using Java generics or by specifying elementType attribute of the @Editable annotation. For Dogs bean above, we use the Java generics declaration, that is, the return type of getDogs() method is List<Dog>. This tells QuickBuild that the element type of the list is Dog. In cases you cannot specify Java generics return type (for example if you are overriding a method whose return type is List), you will need to specify the element type as follows:
- All elements in the list should be of the same concrete type.
- You may also attach Hibernate validator annotations to the list, for example you may attach @Size annotation to the getDogs() method to limit the list size.
QuickBuild editor is able to generate user interface to edit polymorphic properties. For example, for the plugin setting class above:
Vehicle class is defined as:
and Vehicle class has two implementations subclasses in the same package as the Vehicle class: SUV and Car:
Then the user interface for the plugin will be:
Please note that:
- In order to get the polymorphic editor to work, the return type of the getter method needs to be an abstract class or an interface.
- The implementation types can be specified by elementTypes attribute of the Editable annotation. If this attribute does not exist, QuickBuild will load all implementation classes from the package where the abstract class (or interface) resides in.
- The @Editable annotation applied to the implementation class provides display name of the implementation.
- When you specify @Edtiable annotation for the properties defined in Car and SUV classes, the order attribute is starts from 1000. This is to make sure that the properties defined in these implementation classes come after the properties defined in the abstract class.
Variables are widely used in QuickBuild to add flexibility. To define variables:
The editor recognizes a variable definition automatically and provides following interface to define variables (the last property attributes):
Sometimes the bean defines property that expects expressions. Proving some predefined expressions will be convenient for the user. The annotation PresetExpressions serves this purpose. For example:
The generated user interface will be:
As you can see, the preset values provided by @PresetExpressions appears as a menu next to the input box. Menu items are presented with meaningful text, and selecting these menu items will set corresponding expression in the input box.
Sometimes the expressions cannot be hard-coded inside the annotation, if we want to provide expressions generated dynamically at runtime, for example an input box for users to enter a valid node address in the build grid. In this case, the @ExpressionProvider annotation can be used as follows:
As the code demonstrates, the @ExpressionProvider annotation specifies a method in the bean, which QuickBuild can call to get the expressions associated with the menu and the generated user interface looks as follows:
- Validate single property
You may specify validation annotation(s) to the properties to put restraint on values of these properties. For example:
The validation annotations are the annotation validations defined in Hibernate validation framework.
Besides Hibernatebased validation, QuickBuild also has a facility to validate properties mutually through the Validatable interface.
- Validate multiple properties all together