Data sourcesData sources are components that allow you to perform operations on data, such as reading data, writing, deleting or modifying it. A data source can be a table in a database, a database query, a file on disk, a webservice, etc. Data sources are not self-sufficient components like other components. Instead, they can be used in other components. For example, it could be Datachooser, which displays the data of a selected data source.
Defining a data sourceData sources are created based on their definition created by the user. Such a definition must contain the following elements: - @DataSource annotation (if the data source is not defined in the plug-in, it must come from the com.suncode package)
- A public method marked with an annotation
| Javadoc |
|---|
| displayValue | @Define |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.component.annotation.Define |
|---|
|
with one parameter DataSourceDefinitionBuilder - A public method named datasource, which is responsible for returning an implementation of DataSourceInstance with data source logic.
- (Optional) A public method named validator, which is responsible for returning an implementation of DataSourceValidator with data source declaration validation logic.
The definition can also contain an annotation | Javadoc |
|---|
| displayValue | @DataSourceScript |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.datasource.annotation.DataSourceScript |
|---|
|
. This annotation passes the path to the script (from classpath) that contains the definition of the dynamic form.You can also pass the path to the scripts you want to use on the form. To do this, use the @DataSourceInjectScript annotation. You can pass paths to multiple scripts by specifying them in the form @DataSourceInjectScript({scriptPath1, scriptPath2, ..}) A data source can also provide a script that builds the appearance of parameters when it is defined in the PWE. To do this, add another annotation for the class | Javadoc |
|---|
| displayValue | @ComponentsFormScript |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.workflow.form.component.annotation.ComponentsFormScript |
|---|
|
with the passed path to the script (from classpath).An example definition: | Code Block |
|---|
| language | java |
|---|
| linenumbers | true |
|---|
| @DataSource
@DataSourceScript("js/datasource.js")
@ComponentsFormScript( "path/example-form.js" )
public class DataSourceExample
{
@Define
public void definition( DataSourceDefinitionBuilder builder )
{
builder
.id( "example-datasource" )
.name( "datasource.example" )
.description( "datasource.example.desc" )
.category( Categories.TEST )
.operations( DataSourceOperation.READ )
.parameter()
.id( "tableName" )
.name( "datasource.parameter.tableName.name" )
.description( "datasource.parameter.tableName.desc" )
.type( Types.STRING)
.create();
}
public DataSourceInstance datasource( @Param String tableName )
{
return new DatabaseTableSource( tableName );
}
public DataSourceValidator validator() {
return new TableSourceValidator();
}
} |
Data source implementationThe data source must have a method named datasource. The method can have the following types of parameters: - a single data source parameter - the type of the parameter must conform to the defined type and must be preceded by the annotation
| Javadoc |
|---|
| displayValue | @Param |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.component.annotation.Param |
|---|
|
, - parameter mapping two array parameters (key, value) - the type of the parameter must be of type java.util.Map<K,V>, where K is the defined type of the component parameter being the key, and V is the defined type of the component parameter being the value for the key. The parameter must be annotated
| Javadoc |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.component.annotation.PairedParam |
|---|
|
with defined properties (key - id of the parameter being the key, value - id of the parameter being the value). - a single data source parameter
| Javadoc |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.datasource.DataSourceInstance |
|---|
|
marked annotation | Javadoc |
|---|
| displayValue | @Param |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.component.annotation.Param |
|---|
|
- if we have such a type, the DataSourceInstance object will be injected based on the value of this parameter, which must be the id of the data source. | Javadoc |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.component.Parameters |
|---|
|
- contains all the defined validator parameters with their values, this is an alternative to retrieving the parameter using the aforementioned annotation | Javadoc |
|---|
| displayValue | @Param |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.component.annotation.Param |
|---|
|
,| Javadoc |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.translation.Translator |
|---|
|
- Translator for this component, more information here,| Javadoc |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.administration.user.UserInfo |
|---|
|
- object containing information about the user using the data source.
This method must return an object implementing the DataSourceInstance interface. In fact, this implementation should extend the AbstractDataSourceInstance class, so that there will be no compilation errors in the future if any new methods come to the DataSourceInstance interface. Implementation example: | Code Block |
|---|
| language | java |
|---|
| linenumbers | true |
|---|
| public class DatabaseTableSource extends AbstractDataSourceInstance
{
private String tableName;
public DatabaseTableSource( String tableName )
{
this.tableName = tableName;
}
@Override
public CountedResult<Map<String, Object>> getCountedData()
{
return new CountedResult<Map<String, Object>>(0, Maps.newHashMap())
}
@Override
public void save( Map<String, Object> data )
{
}
@Override
public void update( Object key, Map<String, Object> data )
{
}
@Override
public void delete( Object key )
{
}
} |
The implementation does not have to implement all methods. Only data retrieval is required, as not every source needs to support all data operations. Data source validationThe data source can optionally have a method called validator. Method: - is without parameters
- returns an object implementing the DataSourceValidator interface
- the returned object should throw a DataSourceValidateException if the data source is declared incorrectly
The validator is used when saving (creating and updating) a data source. Implementation example: | Code Block |
|---|
| language | java |
|---|
| linenumbers | true |
|---|
| public class TableSourceValidator implements DataSourceValidator
{
@Override
public void validate( DataSourceDeclaration declaration )
{
ParameterDeclaration someParam = declaration.getParameter( "someParam" );
if ( !someParam.isArray() )
{
return;
}
ParameterValue someValue = someParam.getValue();
if ( someValue.getValue().equals( "zła wartość" ) )
{
throw new DataSourceValidateException( "Wartość jest nieprawidłowa" );
}
}
} |
Registration of the data source in the pluginIf the data source is defined in the plugin, then you must additionally indicate that the plugin provides components. To do this, add an entry in the suncode-plugin.xml file: | Code Block |
|---|
| <!-- Sharing autoamtic tasks-->
<workflow-components key="components" /> |
The dynamic form allows you to define a parameter form. | Code Block |
|---|
| language | js |
|---|
| title | File forwarded in @DataSourceScript annotation |
|---|
| PW.DataSources.register('system-database-with-build-param', { // Data source id
buildParams: function(form){ // The `buildParam` function, which will be used to build the data source parameter form
form.addField('param-1');
form.addTextAreaField('param-2');
form.addCombobox({
id : 'param-3',
values : [{id : 'activity', display : 'Activity'},
{id : 'stage', display : 'Stage'},
{id : 'process', display : 'Process'}]
});
form.addTable(['param-4', 'param-5', 'param-6'], {
tableId: 'fieldMap', name: 'Grupa', description: 'Grupa pól'
});
}
}); |
| Tip |
|---|
If, when adding an element to the form, we define its id and this value will refer to the id of the parameter defined in the component, then all properties for the field will be read from the parameter definition (name, description, requirement, type). If, on the other hand, we want to add a field that is not related to any parameter (it will not be stored in the source declaration), then we should define the name, description, type and requiredness. |
| Function | Parameters | Description |
|---|
| addField(definition, [position]) | definition - the identifier of the added parameter or the object containing the field definition position - the position at which the parameter is to be added. When position is not specified, the parameter will be added at the end of the form.
| Adding parameter Example: | Code Block |
|---|
| ...
form.addField('param-1');
... |
If we add a field unrelated to the component parameter, we can specify what type this field should be. The following types are available: string, integer, float, date, datetime, boolean. | Code Block |
|---|
| ...
form.addField({
id: 'custom',
type: 'date',
...
});
... |
| | addTextArea(definition, [position]) | definition - the identifier of the added parameter or the object containing the field definition position - the position at which the parameter is to be added. When position is not specified, the parameter will be added at the end of the form. | Adding a parameter as a field of type `TextArea` | Note |
|---|
The parameter must be of type | Javadoc |
|---|
| displayValue | String |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.core.type.Types |
|---|
|
. |
example: | Code Block |
|---|
| ...
form.addTextArea('param-1');
... |
or | Code Block |
|---|
| ...
form.addTextArea({
id: 'param-1',
...
});
... |
| | addCombobox(definition, [position]) | definition - the object containing the field definition The definition should include the following fields: position - the position at which the parameter is to be added. When the position is not specified, the parameter will be added at the end of the form
| Adding a parameter as a field of type `Combobox`. Example of adding a field of type `Combobox` local (local): | Code Block |
|---|
| ...
form.addCombobox({
id: 'param-1',
valueField: 'id',
displayField: 'display',
fields: [
{name: 'id', type: 'string'},
{name: 'display', type: 'string'}
],
values : [{id : 'activity', display : 'Zadanie'},
{id : 'stage', display : 'Etap'},
{id : 'process', display : 'Proces'}],
sort: [{
property: 'display',
direction: 'DESC'
}],
onChange: function(combo, newValue, oldValue){
...
}
});
... |
Example of adding a field of type 'Combobox' remote (remote): | Code Block |
|---|
| ...
form.addCombobox({
id: 'param-1',
valueField: 'id',
displayField: 'display',
fields: [
{name: 'id', type: 'string'},
{name: 'display', type: 'string'}
],
remote: {
url: Suncode.getAbsolutePath('plugin/com.suncode.example-plugin/example-combo/get'),
remoteSort: false,
pageSize: 20
},
sort: [{
property: 'display',
direction: 'DESC'
}],
onChange: function(combo, newValue, oldValue){
...
}
});
... |
| | addCheckbox(definition, [position]) | definition - identifier of the added parameter or object containing the definition of the field
position - the position at which the parameter is to be added. When the position is not specified, the parameter will be added at the end of the form | Example: | Code Block |
|---|
| ...
form.addCheckbox('param-1');
... |
If we plug this into a component parameter, the type of this parameter must be boolean. | | addTable( [definition] ) | definition - a basic definition of a table with parameters. It contains the following fields:
- id - identifier of the table
- name - displayed name of the table
- description - description of the table
| Adds and returns an "empty" table with grouped parameters. The returned table object allows you to add fields to it. Example: | Code Block |
|---|
| var table = form.addTable();
table.addField('param-1');
table.addField('param-2');
table.addCombobox(...); |
| | addRow( [definition] ) | definition - definition of a row. It contains the following fields: - id - row identifier (optional).
- fieldsSpace - space in pixels between the elements of the row. Default is 5.
| Adds and returns an "empty" row. The returned row allows you to add fields to it. The fields will be added side by side. Example: | Code Block |
|---|
| var row = form.addRow();
row.addField('param-1');
row.addField('param-2');
row.addCombobox(...); |
| | addButton(definition, [position] ) | definition - definition of the button.
It contains the following fields: - id - identifier of the button
- text - displayed text of the button
- handler - function that is called when the button is clicked
position - the position on which the parameter is to be added. When the position is not specified, the parameter will be added at the end of the form | Adding a button on the form. Example: | Code Block |
|---|
| form.addButton({
id: 'btn-1',
text: 'Przycisk',
handler: function(){
...
}
}) |
| | addPassword(definition, [position] ) | definition - identifier of the added parameter or object containing the definition of the field
position - the position at which the parameter is to be added. When the position is not specified, the parameter will be added at the end of the form | Adding a parameter as a field of type 'Password'. | Note |
|---|
The parameter must be of type | Javadoc |
|---|
| displayValue | String |
|---|
| property | javadoc.plusworkflow |
|---|
| className | com.suncode.pwfl.core.type.Types |
|---|
|
. |
Example: | Code Block |
|---|
| ...
form.addTextPassword('param-1');
... |
or | Code Block |
|---|
| ...
form.addPassword({
id: 'param-1',
...
});
... |
| | hide(elementId) | elementId - element identifier | Hides the field with the specified id. Example: | Code Block |
|---|
| ...
form.hide('param-1');
... |
| | show(elementId) | elementId - element identifier | Shows the field with the specified id. Example: | Code Block |
|---|
| ...
form.show('param-1');
... |
| | getValue(elementId) | elementId - element identifier | Retrieves the value of the parameter with the specified id. | Code Block |
|---|
| ...
form.getValue('param-1');
... |
| | setValue(elementId, value) | elementId - element identifier value - value to set | Sets the passed value to the parameter with the specified id. (Supports only header variables) | Code Block |
|---|
| ...
form.setValue('param-1', 'value');
... |
|
@ComponentsFormScript( "actions/example-form.js" ) Cache |
