Search Context¶
Search context is a feature used to keep some parameters in the page and use them mainly for filtering the data in the elements. But those values can be used in other places as well such as commands, boolean expressions and string interpolations.
Figure 1 - Page Search Context
Figure 2 - List Search Context
Variations¶
None.
Limitations¶
- The search context panel can only be included in a page or a list.
- Values from the page search context can be used with all elements and commands in the page.
- Values from the list search context can only be used inside that particular list
When to use¶
Use the search context when you need to keep some non entity parameters in the page and use them for filtering data, string interpolations, boolean expressions and commands.
How to use¶
1. Create a structure in the projection to define search context attributes¶
Before creating search context fields, it is required to create a structure in the projection to define the attributes that the search context fields are based on. Metadata related to properties like data type, label, references required to create the fields in the client will be extracted using these attributes; see code example below
structure PageSearchContextStructure {
attribute FromDate Date;
attribute ToDate Date;
}
2. Implement a function to get the default values¶
This is an optional step. If it is required to assign some default values to search context fields when the page/list is loaded, a function should be created in the projection to get the default values. Define the function in the projection and implement it in the plsvc file. The return type of the function should be the same structure used to create the search context.
function GetPageSearchContextDefaults Structure(PageSearchContextStructure);
FUNCTION Get_Page_Search_Context_Defaults RETURN PageSearch_Context_Structure_Rec
IS
Page_Search_Context_Struct Page_Search_Context_Structure_Rec;
BEGIN
Page_Search_Context_Struct.From_Date := sysdate;
Page_Search_Context_Struct.To_Date := sysdate+30;
RETURN Page_Search_Context_Struct;
END Get_Page_Search_Context_Defaults_;
3. Define search context in client¶
Define the search context in the client and set the fields to be included inside that search context. Keep the label empty if you do not want to include a label for the search context.
searchcontext PageSearchContext for PageSearchContextStructure {
label = "Duration";
field FromDate;
field ToDate;
}
4. Add the search context into a page or list¶
Once the search context is defined in the client, it can be included into a page or a list. Same search context can be reused in different pages/lists. If there is a function available to get the default values, it can be specified using defaults property as shown below.
page SamplePage using SampleEntityset {
label = "My Sample Page";
searchcontext PageSearchContext {
defaults = GetPageSearchContextDefaults();
}
selector SampleSelector;
group SampleGroup;
list OrderList using OrdersSet;
}
page OrderOverview using OrdersSet {
list OrderList {
searchcontext ListSearchContext {
defaults = GetListSearchContextDefaults();
}
}
}
5. Use search context values to filter data in elements¶
The main usage of the search context is to filter data in elements like lists available in the page. It can be done in two ways:
- Use the search context values with the
filterproperty in list (provided the filter can be implemented as a filter expression in the marble code) - Populate the list using a function and pass the search context values as function parameters. Use this method if it is a complex WHERE statement that cannot be implemented as a filter expression in the marble code or if it is required to run a dynamic WHERE statement to get the result.
The following format must be used when accessing the search context values from the marble code: _searchcontext.<search_context_name>.<search_context_value>_
page SamplePage using SampleEntityset {
label = "My Sample Page";
searchcontext PageSearchContext {
defaults = GetPageSearchContextDefaults();
}
selector SampleSelector;
group SampleGroup;
list OrderList using OrdersSet {
filter = [StartDate > searchcontext.PageSearchContext.FromDate and EndDate < searchcontext.PageSearchContext.ToDate];
}
}
page SamplePage using SampleEntityset {
label = "My Sample Page";
searchcontext PageSearchContext {
defaults = GetPageSearchContextDefaults();
}
selector SampleSelector;
group SampleGroup;
list OrderList using GetDemoOrders(searchcontext.PageSearchContext.FromDate, searchcontext.PageSearchContext.ToDate);
}
6. Other usages¶
In addition to providing parameters to filter the data, search context values can be used in other places like boolean expressions, string interpolations, lov function parameters and commands.
// String interpolations
list OrderList for CustomerOrder {
label = "Customer Orders for ${searchcontext.PageSearchContext.CurrentDate}";
field OrderNo;
}
// Boolean expression
list OrderList for CustomerOrder {
field CustomerNo {
columnexclude = [searchcontext.PageSearchContext.IsValid = true];
}
}
// LOV datasource function
list OrderList for CustomerOrder {
lov PersonRef with PersonSelector using GetSupervisors(searchcontext.PageSearchContext.CurrentDate) {
label = "Person";
}
}
// Commands
command ApproveOrderCommand for CustomerOrder {
label = "Approve";
execute {
call DoApprove(OrderNo, searchcontext.PageSearchContext.IsValid, searchcontext.ListSearchContext.AccountDate);
}
}
7. Pass Search Context values when navigate¶
Values to the page search context fields can be passed in the URL when navigating to a page with a search context.
command GoToSamplePage for CustomerOrder {
label = "Sample Page";
execute {
navigate "page/DemoClient/SamplePage?searchcontext=FromDate:$[StartDate],ToDate:$[EndDate]";
}
}
8. Hide search context fields¶
If the search context values are not supposed to be shown to the user (that is if values are set from the background using default method or through navigation parameters), you can hide the fields by setting the visible property to false for the relevant search context fields that needs to be hidden from the user. If all the fields in the search context are hidden, then search context panel will not be visible in the client as well.
9. Auto update search context field values¶
When the value of a search context field has been changed by the user, it is possible to set some more search context field values to be changed based on the value changed by the user. This is achieved by using the validateCommand in search context field.
searchcontext PageSearchContext for PageSearchContextStructure {
field SiteRequired {
validate command {
execute {
set IsValid = false;
if[SiteRequired = true] {
call GetOrderSearchStructure() into SCStruct;
set CurrentDate = SCStruct.DueDate;
}
}
}
}
field IsValid;
field CurrentDate;
}
Keywords¶
Below is a list of keywords used within the control.
for
Properties¶
Below is a list of properties that can be used to customize the search context.
Example¶
Below is an example of search context values used in different areas:
searchcontext PageSearchContext for PageSearchContextStructure {
field IsValid;
field CurrentDate;
}
searchcontext ListSearchContext for ListSearchContextStructure {
field AccountDate;
}
page SiteForm using Sites {
label = "Sites";
searchcontext PageSearchContext {
defaults = GetPageDefaultValue();
}
selector SiteSelector;
group SiteGroup;
list OrderList using GetOrders(searchcontext.PageSearchContext.IsValid) {
searchcontext ListSearchContext {
defaults = GetListDefaultValue();
}
}
}
list OrderList for CustomerOrder {
label = "Customer Orders for ${searchcontext.PageSearchContext.CurrentDate}";
field OrderNo;
field CustomerNo {
columnexclude = [searchcontext.PageSearchContext.IsValid = true];
}
field OrderDate;
field Description;
lov PersonRef with PersonSelector using GetSupervisors(searchcontext.PageSearchContext.CurrentDate) {
label = "Person";
description = InternalDisplayName;
}
command ApproveOrderCommand;
}
command ApproveOrderCommand for CustomerOrder {
label = "Approve";
execute {
call DoApprove(OrderNo, searchcontext.PageSearchContext.IsValid, searchcontext.ListSearchContext.AccountDate);
}
}
Example 1 - Search context values used in different areas