Difference between revisions of "Riena/UI filters"

From Eclipsepedia

Jump to: navigation, search
(Rules for navigation nodes)
 
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=UI Filters=
+
{{RienaBreadcrumbs |
 +
[[Riena Project]] | [[Riena Getting started|Getting Started]] | UI Filters}}
 +
 
 
==Introduction==
 
==Introduction==
With the help of the UI filters some restrictions can be added to certain UI elements of a Riena application. E.g. add a validator to a text field or hide a sub module in the navigation.
+
With UI filters, restrictions can be added to certain UI elements of a Riena application. For example you could add a validator to a text field or hide a sub module in the navigation.
  
UI Filters exits of a collection of rules. Is a filter added its rules are applied for the corresponding UI elements. A UI element can be a menu item, a node of the navigation or a ridget.<br>
+
UI Filters contain a collection of rules. When a filter is added, its rules are applied for the corresponding UI elements. A UI element can be a menu item, a node of the navigation or a ridget.
The UI Filters can be composed by adding any kid of rule. The UI filters themselves are added to any node of the navigation. The rules of a filter are only exploited for the node with this filter and all the child nodes.<br>
+
 
At every time filters can be added to and removed from the navigation model. The changes which are results are immediately visible at the GUI.<br>
+
The UI Filters can be composed by adding any kind of rule. The UI filters themselves are added to any node of the navigation. The rules of a filter are only exploited for the node with this filter and all the child nodes.
So the UI filter can be used in a very flexible way and they are also very dynamically.
+
 
 +
At any time can filters be added to and removed from the navigation model. The changes are immediately visible in the GUI. So the UI filter can be used in a very flexible way and dynamically.
  
 
==UI Filter==
 
==UI Filter==
An UI filter itself only consists of a collection of rules and an identifier.
+
A UI filter itself only consists of a collection of rules and an identifier.
 
<source lang="java">
 
<source lang="java">
 
public interface IUIFilter {
 
public interface IUIFilter {
 
 
Collection<? extends IUIFilterRule> getFilterRules();
 
Collection<? extends IUIFilterRule> getFilterRules();
 
 
String getFilterID();
 
String getFilterID();
 
 
}
 
}
 
</source>
 
</source>
Line 38: Line 38:
  
 
== Rules ==
 
== Rules ==
How the UI elements will be manipulated is defined by the rules of the UI-Filters.<br>
+
The way the UI elements will be manipulated is defined by the rules of the UI Filters. Therefore two scenarios exist.
Therefore two scenarios exist.
+
  
A UI Filter is added.<br>
+
=== Scenario 1: A UI Filter is added ===
The rule checks for every UI elements, if it is responsible for this element (<tt>matches</tt>).<br>
+
The rule checks for every UI element if it is responsible for this element (<tt>matches</tt>).<br>
Is this the case the rule is applied.
+
If this is the case, the rule is applied.
  
A UI Filter is removed.<br>
+
=== Scenario 2: A UI Filter is removed ===
Also the rule checks for every UI elements, if it is responsible for this element (<tt>matches</tt>).<br>
+
Also, the rule checks for every UI element if it is responsible for this element (<tt>matches</tt>).<br>
Is this the case the changes which are caused by this rule are removed.
+
If this is the case, the changes which are caused by this rule are removed.
 
<source lang="java">
 
<source lang="java">
 
public interface IUIFilterRule {
 
public interface IUIFilterRule {
Line 59: Line 58:
 
}
 
}
 
</source>
 
</source>
The rules can be divided in several categories.
+
The rules can be divided into several categories.
# What are the changes of the rules? Is a Marker added (IUIFilterRuleMarker) or a validator (IUIFilterRuleValidator)?
+
# What are the changes of the rules? Is a Marker added (<tt>IUIFilterRuleMarker</tt>) or a validator (<tt>IUIFilterRuleValidator</tt>)?
 
# Is the rule responsible for a navigation node or a ridget?
 
# Is the rule responsible for a navigation node or a ridget?
 +
 
=== Rules for navigation nodes ===
 
=== Rules for navigation nodes ===
For navigation nodes only two different rules for adding markers exists. One rule adds a DisabeldMarker (viz. the node is disabled) the other one adds a HiddenMarker (viz. the node is not visible).
+
For navigation nodes only two different rules for adding markers exists. One rule adds a <tt>DisabeldMarker</tt> (viz. the node is disabled) the other one adds a <tt>HiddenMarker</tt> (viz. the node is not visible).
  
The constructor of both rules (UIFilterRuleNavigationDisabledMarker and UIFilterRuleNavigationHiddenMarker) takes a pattern that is used to identify the navigation nodes. This simple pattern may contain '*' for 0 and many characters and '?' for exactly one character.
+
The constructor of both rules (<tt>UIFilterRuleNavigationDisabledMarker</tt> and <tt>UIFilterRuleNavigationHiddenMarker)</tt> takes a pattern that is used to identify the navigation nodes. This simple pattern may contain '*' for 0 and many characters and '?' for exactly one character.
  
 
====Matches====
 
====Matches====
A rule is applied if the ID of the navigation node matches the pattern of the rule. Not only is the ID of one navigation node used for the match, also the IDs of the parent nodes. All these IDs together are called longID or complete ID. Example:
+
A rule is applied if the ID of the navigation node matches the pattern of the rule. Not only is the ID of one navigation node used for the match, also the IDs of the parent nodes. All these IDs together are called longID or completeID. Example:
  
 
Tree structure of a navigation model:<br>
 
Tree structure of a navigation model:<br>
Line 87: Line 87:
  
 
====DisabledMarker====
 
====DisabledMarker====
The rule UIFilterRuleNavigationDisabledMarker adds a DisabledMarker to the navigation node, if the pattern of the rule matches the ID of the node (longID). The node is still visible but it cannot be selected.
+
The rule <tt>UIFilterRuleNavigationDisabledMarker</tt> adds a <tt>DisabledMarker</tt> to the navigation node, if the pattern of the rule matches the ID of the node (<tt>longID</tt>). The node is still visible but it cannot be selected.
 +
 
 
====HiddenMarker====
 
====HiddenMarker====
The rule UIFilterRuleNavigationHiddenMarker adds a HiddenMarker to the navigation node, if the pattern of the rule matches the ID of the node (longID). The node is not displayed.
+
The rule <tt>UIFilterRuleNavigationHiddenMarker</tt> adds a <tt>HiddenMarker</tt> to the navigation node, if the pattern of the rule matches the ID of the node (<tt>longID</tt>). The node is not displayed.
 +
 
 +
===Rules for Ridgets===
 +
For ridgets two different kinds of rules exist. There are rules for adding markers and rules for adding validators.
 +
 
 +
Like creating rules for navigation nodes the constructor takes a pattern (<tt>ridgetIdPattern</tt>), that‘s used to identify the ridgets. The method <tt>matches</tt> decides, if the rule is applied.
 +
 
 +
====Matches====
 +
Also the rules for ridgets are only applied, if the pattern of the rule matches the id of the ridget.<br>
 +
And also like the rules for the navigation nodes the method <tt>matches</tt> compares the pattern with the complete ID of the ridget. The complete ID is composed of the IDs of the navigations nodes and the ID of the ridget.
 +
A ridget with the ID “lastname” is part of the sub module “Demo1”. The complete ID:<br>
 +
<tt>/application/subApp1/uiprocessGroup/uiProcess/demo01/lastname</tt>
 +
 
 +
====Marker Rules====
 +
The following four rules add a marker, if the pattern of the rule matches the ID of the ridget:
 +
 
 +
; <tt>UIFilterRuleRidgetDisabledMarker</tt>
 +
: This rule adds a <tt>DisabledMarker</tt>. The ridget is visible, but no value is displayed.
 +
; <tt>UIFilterRuleRidgetHiddenMarker</tt>
 +
: This rule adds a <tt>HiddenMarker</tt>. The ridget is not displayed.
 +
; <tt>UIFilterRuleRidgetMandatoryMarker</tt>
 +
: This rule adds a <tt>MandatoryMarker</tt>. The ridget is marked as long not value is entered.
 +
; <tt>UIFilterRuleRidgetOutputMarker</tt>
 +
: This rule adds a <tt>OutputMarker</tt>. The ridget is visible and also the value is displayed, but the value cannot be edited.
 +
 
 +
====Validator Rules====
 +
Only one rule exists for validators. Validators (<tt>IValidator</tt>) can be added to a ridget and validate the value. If the value is invalid, an error marker is displayed. To construct this rule (<tt>UIFilterRuleRidgetValidator</tt>) the pattern for the ID, the validator and the time of validation are necessary.
 +
 
 +
The validator must implement the interface <tt>IValidator</tt>. Riena provides a set of validators: e.g. <tt>MinLength</tt>, <tt>MaxLength</tt>, <tt>ValidEmailAddress</tt>.
 +
 
 +
For adding a validator to a ridget it is necessary to specify at what points in time the values shall be validated:
 +
 
 +
; <tt>ValidationTime.ON_UI_CONTROL_EDIT</tt>
 +
: The value is validated after every change.
 +
; <tt>ValidationTime.ON_UPDATE_TO_MODEL</tt>
 +
: The value is validated before writing the value into the model.
 +
 
 +
===Rules for Menu and Tool Bar===
 +
Menus, menu items and tool items are also ridgets of Riena. But for these, other rules are used.
 +
 
 +
====Matches====
 +
The method <tt>matches</tt> decides whether a rule is applied. This method compares the ID of the ridget with the pattern of the rule. Unlike the other ridgets, only the ''simple'' ID of the ridget is compared.
 +
 
 +
====DisabledMarker====
 +
The rule <tt>UIFilterRuleMenuItemDisabledMarker</tt> adds a <tt>DisabledMarker</tt> to a menu, menu item or a tool item. The menu or item is visible but is cannot be selected.
 +
 
 +
====HiddenMarker====
 +
The rule <tt>UIFilterRuleMenuItemHiddenMarker</tt> adds a <tt>HiddenMarker</tt> to a menu, menu item or a tool item. The menu or item is invisible.
 +
 
 +
==Extension==
 +
UI filters cannot only be composed programmatically; they can be also composed by extensions of eclipse RCP.<br>
 +
Riena provides the extension point <tt>org.eclipse.riena.filter.uifilter</tt>.
 +
; filter
 +
: At top level only <tt>filter</tt> elements can be added. This element has only on Attribute: <tt>filterID.</tt>
 +
; nodeID
 +
: This element defines to with navigation node this UI filter will be added. It is possible to add a filter to different nodes, so the <tt>filter</tt> element can has more than one <tt>nodeID</tt> element.
 +
; ruleMarkerNavigation
 +
:This element creates a rule which adds a marker to a navigation node. The atrribute <tt>nodeID</tt> identifies the navigationn node and marker the type of the marker: <tt>hidden</tt> or  <tt>disabled</tt>.
 +
; ruleMarkerRidget
 +
: This element creates a rule which adds a marker to a ridget. The attribute <tt>ridgetId</tt> identifies the ridget and <tt>marker</tt> the type of the marker: <tt>hidden</tt>, <tt>output</tt>, <tt>mandatory</tt> or <tt>disabled</tt>
 +
; ruleValidatorRidget
 +
: This element creates a rule which adds a validator to a ridget. The attribute <tt>ridgetID</tt> identifies the ridget, <tt>validator</tt> defines the class of the validator and <tt>validationTime</tt> the point in time of validation (<tt>onUIControlEdit</tt> or <tt>onUpdateToModel</tt>).
 +
: Some validators need some arguments to validate a value correctly. So these arguments can be added behind the class name of the validator. A colon separates class name and arguments. The arguments are separated by comma. A simple example is the <tt>MaxLength</tt> validator. You would set the maximum length like this: <tt>org.eclipse.riena.ui.ridgets.validation.MaxLength:12</tt>. The order of the arguments is according the parameter of the constructor.
 +
; ruleMarkerMenuItem
 +
: This element creates a rule which adds a marker to a menu, menu item or tool item. The attribute <tt>itemID</tt> identifies the item and <tt>marker</tt> the type of the marker: <tt>hidden</tt> or <tt>disabled</tt>.
 +
 
 +
[[Category:Riena]]

Latest revision as of 04:09, 21 December 2010

Riena ProjectGetting Started ▶ UI Filters

Contents

[edit] Introduction

With UI filters, restrictions can be added to certain UI elements of a Riena application. For example you could add a validator to a text field or hide a sub module in the navigation.

UI Filters contain a collection of rules. When a filter is added, its rules are applied for the corresponding UI elements. A UI element can be a menu item, a node of the navigation or a ridget.

The UI Filters can be composed by adding any kind of rule. The UI filters themselves are added to any node of the navigation. The rules of a filter are only exploited for the node with this filter and all the child nodes.

At any time can filters be added to and removed from the navigation model. The changes are immediately visible in the GUI. So the UI filter can be used in a very flexible way and dynamically.

[edit] UI Filter

A UI filter itself only consists of a collection of rules and an identifier.

public interface IUIFilter {
	Collection<? extends IUIFilterRule> getFilterRules();
	String getFilterID();
}

UI filters can be added to any navigation node. They also can be removed. All nodes of the navigation (INavigationNode) are implemented the following interface:

public interface IUIFilterable {
 
	void addFilter(IUIFilter filter);
 
	void removeFilter(IUIFilter filter);
 
	void removeFilter(String filterID);
 
	void removeAllFilters();
 
	Collection<? extends IUIFilter> getFilters();
 
}

The implementation updates the GUI after adding or removing an UI filter.

[edit] Rules

The way the UI elements will be manipulated is defined by the rules of the UI Filters. Therefore two scenarios exist.

[edit] Scenario 1: A UI Filter is added

The rule checks for every UI element if it is responsible for this element (matches).
If this is the case, the rule is applied.

[edit] Scenario 2: A UI Filter is removed

Also, the rule checks for every UI element if it is responsible for this element (matches).
If this is the case, the changes which are caused by this rule are removed.

public interface IUIFilterRule {
 
	boolean matches(Object... args);
 
	void apply(Object object);
 
	void remove(Object object);
 
}

The rules can be divided into several categories.

  1. What are the changes of the rules? Is a Marker added (IUIFilterRuleMarker) or a validator (IUIFilterRuleValidator)?
  2. Is the rule responsible for a navigation node or a ridget?

[edit] Rules for navigation nodes

For navigation nodes only two different rules for adding markers exists. One rule adds a DisabeldMarker (viz. the node is disabled) the other one adds a HiddenMarker (viz. the node is not visible).

The constructor of both rules (UIFilterRuleNavigationDisabledMarker and UIFilterRuleNavigationHiddenMarker) takes a pattern that is used to identify the navigation nodes. This simple pattern may contain '*' for 0 and many characters and '?' for exactly one character.

[edit] Matches

A rule is applied if the ID of the navigation node matches the pattern of the rule. Not only is the ID of one navigation node used for the match, also the IDs of the parent nodes. All these IDs together are called longID or completeID. Example:

Tree structure of a navigation model:

RienaApplication                 (ID=application)
    NavigationSubApplication     (ID=subApp1)
        ModuleGroup              (ID=uiprocessGroup)
            UIProcess            (ID=uiprocess)
                Demo1            (ID=demo01)

The complete ID of the sub module “Demo1” is:
/application/subApp1/uiprocessGroup/uiProcess/demo01
The single IDs of the nodes are separated by a slash.
Because the rules can have pattern with wildcards, the following patterns matches:

  • /application/subApp?/uiprocessGroup/uiProcess/demo??
  • *demo01
  • */subApp1/uiprocessGroup/uiProcess/demo0*

[edit] DisabledMarker

The rule UIFilterRuleNavigationDisabledMarker adds a DisabledMarker to the navigation node, if the pattern of the rule matches the ID of the node (longID). The node is still visible but it cannot be selected.

[edit] HiddenMarker

The rule UIFilterRuleNavigationHiddenMarker adds a HiddenMarker to the navigation node, if the pattern of the rule matches the ID of the node (longID). The node is not displayed.

[edit] Rules for Ridgets

For ridgets two different kinds of rules exist. There are rules for adding markers and rules for adding validators.

Like creating rules for navigation nodes the constructor takes a pattern (ridgetIdPattern), that‘s used to identify the ridgets. The method matches decides, if the rule is applied.

[edit] Matches

Also the rules for ridgets are only applied, if the pattern of the rule matches the id of the ridget.
And also like the rules for the navigation nodes the method matches compares the pattern with the complete ID of the ridget. The complete ID is composed of the IDs of the navigations nodes and the ID of the ridget. A ridget with the ID “lastname” is part of the sub module “Demo1”. The complete ID:
/application/subApp1/uiprocessGroup/uiProcess/demo01/lastname

[edit] Marker Rules

The following four rules add a marker, if the pattern of the rule matches the ID of the ridget:

UIFilterRuleRidgetDisabledMarker
This rule adds a DisabledMarker. The ridget is visible, but no value is displayed.
UIFilterRuleRidgetHiddenMarker
This rule adds a HiddenMarker. The ridget is not displayed.
UIFilterRuleRidgetMandatoryMarker
This rule adds a MandatoryMarker. The ridget is marked as long not value is entered.
UIFilterRuleRidgetOutputMarker
This rule adds a OutputMarker. The ridget is visible and also the value is displayed, but the value cannot be edited.

[edit] Validator Rules

Only one rule exists for validators. Validators (IValidator) can be added to a ridget and validate the value. If the value is invalid, an error marker is displayed. To construct this rule (UIFilterRuleRidgetValidator) the pattern for the ID, the validator and the time of validation are necessary.

The validator must implement the interface IValidator. Riena provides a set of validators: e.g. MinLength, MaxLength, ValidEmailAddress.

For adding a validator to a ridget it is necessary to specify at what points in time the values shall be validated:

ValidationTime.ON_UI_CONTROL_EDIT
The value is validated after every change.
ValidationTime.ON_UPDATE_TO_MODEL
The value is validated before writing the value into the model.

[edit] Rules for Menu and Tool Bar

Menus, menu items and tool items are also ridgets of Riena. But for these, other rules are used.

[edit] Matches

The method matches decides whether a rule is applied. This method compares the ID of the ridget with the pattern of the rule. Unlike the other ridgets, only the simple ID of the ridget is compared.

[edit] DisabledMarker

The rule UIFilterRuleMenuItemDisabledMarker adds a DisabledMarker to a menu, menu item or a tool item. The menu or item is visible but is cannot be selected.

[edit] HiddenMarker

The rule UIFilterRuleMenuItemHiddenMarker adds a HiddenMarker to a menu, menu item or a tool item. The menu or item is invisible.

[edit] Extension

UI filters cannot only be composed programmatically; they can be also composed by extensions of eclipse RCP.
Riena provides the extension point org.eclipse.riena.filter.uifilter.

filter
At top level only filter elements can be added. This element has only on Attribute: filterID.
nodeID
This element defines to with navigation node this UI filter will be added. It is possible to add a filter to different nodes, so the filter element can has more than one nodeID element.
ruleMarkerNavigation
This element creates a rule which adds a marker to a navigation node. The atrribute nodeID identifies the navigationn node and marker the type of the marker: hidden or disabled.
ruleMarkerRidget
This element creates a rule which adds a marker to a ridget. The attribute ridgetId identifies the ridget and marker the type of the marker: hidden, output, mandatory or disabled
ruleValidatorRidget
This element creates a rule which adds a validator to a ridget. The attribute ridgetID identifies the ridget, validator defines the class of the validator and validationTime the point in time of validation (onUIControlEdit or onUpdateToModel).
Some validators need some arguments to validate a value correctly. So these arguments can be added behind the class name of the validator. A colon separates class name and arguments. The arguments are separated by comma. A simple example is the MaxLength validator. You would set the maximum length like this: org.eclipse.riena.ui.ridgets.validation.MaxLength:12. The order of the arguments is according the parameter of the constructor.
ruleMarkerMenuItem
This element creates a rule which adds a marker to a menu, menu item or tool item. The attribute itemID identifies the item and marker the type of the marker: hidden or disabled.