Custom Builder Plugin

Usages

• Custom Builder Plugin is used for extends the builder feature in addition to the default form, list, userview & process builder.
• Custom Builder Plugin let app designer build extra definition which auto handles the load/store/merge/export/import by the platform.
• A useable Custom Builder Plugin must extend org.joget.apps.app.model.CustomBuilderAbstract abstract class.

Abstract Class

org.joget.apps.app.model.CustomBuilderAbstract

• Under wflow-core module
• Extended org.joget.plugin.base.ExtDefaultPlugin. Please refer to Plugin Base Abstract Class and Interface.
• Implemented org.joget.plugin.property.model.PropertyEditable. Please refer to Plugin Base Abstract Class and Interface.
• A base abstract class to develop a Custom Builder Plugin. 

Method Detail

Abstract Methods

getIcon

public String getIcon();

The unique font awesome icon of the builder. Eg. "fas fa-key".

getColor

public String getColor();

The unique color code of the builder. Eg. "#85ea2d".

getObjectName

public String getObjectName();

The unique shortname of the output definition of the builder. Eg. "api", "report", etc.

getObjectLabel

public String getObjectLabel();

The unique label of the output definition of the builder. Eg. "API", "Report", etc.

getIdPrefix

public String getIdPrefix();

The prefix for created output definition ID.  Eg. "API-", "rp-", etc.

getResourceBundlePath

public String getResourceBundlePath();

The resource bundle file path. The resource bundle message key can be retrieved in the builder javascript using 'get_cbuilder_msg(String key)'.  

getBuilderConfig

public String getBuilderConfig();

The builder configuration in JSON format. Used to configure the builder callback event and the advanced tools available for the builder. Full available configuration as below. Please refer to Sample Plugins on how to use this config.

{
    builder : {
        callbacks : { //methods name to call
            initBuilder : "", //call after initialized the builder. 
            load : "", //Call to load the definition JSON
            saveEditProperties : "", //Call after save edit properties event is trigger 
            cancelEditProperties : "" //Call after cancel edit properties event is trigger
        }
    },
    advanced_tools : { //configure the advanced tools available 
        tree_viewer : { //tree viewer to view the tree structure of the definition
            disabled : false, //to disable this tool
            childs_properties : ["elements"], //the property name which hold editable plugins
            matchers : { //matchers to customize the tree viewer
                'sample' : { //sample matcher
                    match : function (viewer, deferreds, node, jsonObj, refObj) {
                        //do something

                        return false;
                    }
                }
            }
        },
        usage : { //to check usage of the definition of this builder
            disabled : false  //to disable this tool
        },
        i18n : { //to provide i18n editor for this builder
            disabled : false, //to disable this tool
            keywords : [ //The property names which allowed for i18n 
                "label"
            ]
        },
        permission : { //to provide permission editor for this builder
            disabled : false, //to disable this tool
            permission_plugin : "org.joget.apps.form.model.FormPermission", //the permission plugin class used for this builder
            authorized : { //configure the authorized section
                property : "", //the property name to store the authorized section value
                default_value : "", //the default value for authorized property
                options : [ //the sample option for authorized section
                    {
                        key : "vissible",
                        value : "",
                        label : get_cbuilder_msg("ubuilder.visible")
                    },
                    {
                        key : "hidden",
                        value : "true",
                        label : get_cbuilder_msg("ubuilder.hidden")
                    }
                ]
            },
            unauthorized : { //configure the unauthorized section
                property : "", //the property name to store the unauthorized section value
                default_value : "", //the default value for unauthorized property
                options : [ //the sample option for unauthorized section
                    {
                        key : "vissible",
                        value : "",
                        label : get_cbuilder_msg("ubuilder.visible")
                    },
                    {
                        key : "hidden",
                        value : "true",
                        label : get_cbuilder_msg("ubuilder.hidden")
                    }
                ]
            },
            element_label_callback : "", //Method name to call for customize the element label
            element_support_plugin : [], //Plugin class name which support permission plugin configuration
            display_element_id : false, //to enable/disable to display the element id beside the element label
            childs_properties : ["elements"], //The property name to loop the child elements(plugins)
            ignore_classes : [], //The plugin class name to skip in the loop of child elements(plugins)
            render_elements_callback : "" //The method name to call to customize the rendering of child elements(plugins)
        },
        customTabsCallback : "" //Method name to call to render additional tabs in Advanced Tools. 
    }
}

getBuilderJS

public String getBuilderJS(String contextPath, String buildNumber);

The JS files used in the builder. Please refer to Sample Plugins on how to implement this method.

Parameters:

contextPath - the http request context path.

buildNumber - Joget platform build number

getBuilderCSS

public String getBuilderCSS(String contextPath, String buildNumber);

The CSS files used in the builder. Please refer to Sample Plugins on how to implement this method.

getBuilderHTML

public String getBuilderHTML(BuilderDefinition def, String json, HttpServletRequest request, HttpServletResponse response);

The HTML of builder. Please refer to Sample Plugins on how to implement this method.

Parameters:

def - the definition object to edit/load

json - the JSON definition to edit/load

getBuilderResult

public Object getBuilderResult(String json, Map<String, Object> config);

Retrieve the builder end result based on json definition. The end result can be a report PDF/HTML, an API document etc. Please refer to Sample Plugins on how to implement this method.

Parameters:

json - the JSON definition to generate the builder result.

config - the additional configuration/parameters use for generate the result.

Overridable Methods

createNewJSON

public String createNewJSON(String id, String name, String description, BuilderDefinition copyDef);

Used to create the JSON definition of new object

getNameFromJSON

public String getNameFromJSON(String json);

Retrieve name from the JSON definition

getDescriptionFromJSON

public String getDescriptionFromJSON(String json);

Retrieve description from the JSON definition

getCreateNewPageHtml

public String getCreateNewPageHtml();

HTML to add to the create new page

Plugin Properties Options

• Please refer to Plugin Properties Options for more information.

Custom Builder Javascript Object

Utility methods and fields to use in the builder javascript. 

Methods

CustomBuilder.callback(name, args)

To call a method by name

Parameters

• • name - a method name.
  • args - arguments to pass to the method call

CustomBuilder.initConfig(config)

To initialize the builder configuration by the platform

Parameters

• • config - the configuration object.

CustomBuilder.initPropertiesOptions(options)

To initialize the builder properties tab  by the platform

Parameters

• • options - the builder properties options

CustomBuilder.initBuilder(callback)

To initialize the builder by the platform

Parameters

• • callback - the callback method to call after builder initialized.

CustomBuilder.showPopUpBuilderProperties()

To show the builder properties in a popup editor.

CustomBuilder.saveBuilderProperties(container, properties)

To save the builder properties

Parameters

• • container - the property editor container
  • properties - the properties to save

CustomBuilder.initPaletteElement(category, className, label, icon, propertyOptions, defaultPropertiesValues, render, css, metaData)

To populate elements(plugins) in the side palette.

Parameters

• • category - the category of the elements(plugins)
  • className - the classname of the elements(plugins)
  • label - the label of the elements(plugins)
  • icon - the label of the elements(plugins)
  • propertyOptions - the plugin properties options the edit the element(plugin)
  • defaultPropertiesValues - the default properties values to set to a new element object added to canvas.
  • render - set to false to not render the elements(plugins) in side palette
  • css - the css class to palette element
  • metaData - the additional data of the elements(plugins) to used by the builder 

CustomBuilder.loadJson(json)

To load a json to the builder

Parameters

• • json - the JSON definition to load

CustomBuilder.update(addToUndo)

Update the CustomBuilder.json based on the data stored in CustomBuilder.data

Parameters

• • addToUndo - true to add the previous stored JSON definition to undo stack.

CustomBuilder.updateJson(json, addToUndo)

Update CustomBuilder.json to the pass in JSON.

Parameters

• • json - the JSON definition to update to CustomBuilder.json.
  • addToUndo - true to add the previous stored JSON definition to undo stack.

CustomBuilder.getJson()

Get the value in CustomBuilder.json.

CustomBuilder.save()

To save the builder JSON definition.

Sample Plugins

• Page Buider  - page_builder.zip