Search Panel Wizard

The Search Panel Wizard helps the developer to quickly create a search screen for a datasource with the necessary PL/SQL code to run it. The wizard is accessible from the datasource right click menu on the navigation tree.

Search panels are integrated with datasource definition criteria feature. So any code generated by the search panel wizard will use the criteria of the datasource it is for.

Regions Screen

In the initial screen, the wizard asks the developer to create search regions. There are two types of regions.

Simple Region

A simple region consists of one label and one editable component which is associated to a bind variable.

It is highly recommended that a simple region always has a corresponding simple criterion in the definition of the datasource the search panel is for.

The simple region can use one of the four editable components, depending on the data type or the possible values for the bind variable.

Text Field: If the region has a text field, the developer can specify whether the user can override the default operator specified in the corresponding simple criterion. If override is enabled, Formspider uses the new operator, entered by the user to the region’s editable component, instead of the default operator specified in the simple criterion. The override operator must be entered as the first characters in the text field. The valid override operators are: <, >, =, >=, =<, !=, % (% can be entered both as first or last character.)

Combobox: If the ComboBox component is selected, the wizard displays three new fields for the developer to pick a list datasource, value column and a display column. All three fields are optional.

LOV Field: If the LOV Field component is selected, the wizard displays a new field in which the developer can pick the LOV she wants to use for the component.

Date Field: If the Date Field component is selected, the wizard displays a new field in which the developer can enter a date format.

Range Region

A range region is used to search matching rows in a range of values such as between two dates.

The region consists of two labels and two editable components. Each editable component can be assigned to populate a bind variable. The editable components can be one of the four components, depending on the data type or possible values for the bind variables they are used to populate. The additional fields that appear for the selected components are the same as in the simple region, with the exception that the text field component does not offer an override default operator checkbox.

It is highly recommended that a range region always has a corresponding advanced criterion in the definition of the datasource the search panel is for.

Customization Parameters Screen

In this screen, the wizard asks the developer values for a number of parameters to customize the generated FS Objects and the PL/SQL code for the search screen.

Object Names

Panel Name: Name of the search panel.

Package Name: Name of the PL/SQL package to be generated which drives the search panel.

Actions

Search Action: Name of the FS Action to be created to start the search operation. The wizard can create a new action, use an existing action or skip this step completely.

Clear Action: Name of the FS Action to be created to clear all the search fields in the search panel. The wizard can create a new action, use an existing action or skip this step completely.

Layout Settings

The generated search panel uses the table layout. This section of the wizard helps the developer to customize the design of the search panel’s layout.

Regions Per Row: Number of search regions in each table layout row in the search panel.

Space Between Rows: The blank space between each region row in the search panel, in pixels.

Region Height: Height of a region, in pixels.

Label 1 Width: Width of the first label in simple or range regions, in pixels.

Label 2 Width: Width of the second label in range regions, in pixels.

Search Button Label: The text on the button which performs search. (A multilingual key can be entered here.)

Clear Button Label: The text on the button which clears the fields in the search field. (A multilingual key can be entered here.)

Error Handling

Error Alert: If  there are errors while performing a search, the generated PL/SQL code can show the alert selected by the developer to display the error message.

Preview Screen

Before generating the objects, the wizard presents the Panel XML and the PL/SQL code in a preview screen. The developer can make edits on this screen to finalize the panel to be generated.

<panel>
<tableLayout>
  <!--Control row driving the layout-->
  <row height="0">
    <!--Left margin-->
    <cell width="20"/>
    <!--Start of region in column 1-->
    <!--Label 1-->
    <cell width="80"/>
    <!--Component 1-->
    <cell/>
    <!--Label 2-->
    <cell width="10"/>
    <!--Component 2-->
    <cell/>
    <!--End of region in column 1-->
    <!--Space between regions-->
    <cell width="20"/>
    <!--Start of region in column 2-->
    <!--Label 1-->
    <cell width="80"/>
    <!--Component 1-->
    <cell/>
    <!--Label 2-->
    <cell width="10"/>
    <!--Component 2-->
    <cell/>
    <!--End of region in column 2-->
    <!--Right margin-->
    <cell width="20"/>
  </row>
  <!--Space between rows-->
  <row height="5"/>
  <!--Start of row 1-->
  <row height="20">
    <!--Start of column 1-->
    <!--Left margin-->
    <cell/>
    <!--Start of simple region in row 1 column 1-->
    <!--Simple region label-->
    <cell hAlign="Full">
      <textLabel label="First Name  " text-align="Right"/>
    </cell>
    <!--Simple region component-->
    <cell hAlign="Full" columnSpan="3">
      <textField name="firstname" domain="DefaultVarchar2"/>
    </cell>
    <!--Simple region end-->
    <!--End of region in row 1 column 1-->
    <!--Start of column 2-->
    <!--Space between regions-->
    <cell/>
    <!--Start of simple region in row 1 column 2-->
    <!--Simple region label-->
    <cell hAlign="Full">
      <textLabel label="Last Name  " text-align="Right"/>
    </cell>
    <!--Simple region component-->
    <cell hAlign="Full" columnSpan="3">
      <textField name="lastname" domain="DefaultVarchar2"/>
    </cell>
    <!--Simple region end-->
    <!--End of region in row 1 column 2-->
    <!--Right margin-->
    <cell/>
  </row>
  <!--Space between rows-->
  <row height="5"/>
  <!--Start of row 2-->
  <row height="20">
    <!--Start of column 1-->
    <!--Left margin-->
    <cell/>
    <!--Start of simple region in row 2 column 1-->
    <!--Simple region label-->
    <cell hAlign="Full">
      <textLabel label="Employee ID  " text-align="Right"/>
    </cell>
    <!--Simple region component-->
    <cell hAlign="Full" columnSpan="3">
      <textField name="employeeid" domain="DefaultNumber"/>
    </cell>
    <!--Simple region end-->
    <!--End of region in row 2 column 1-->
    <!--Start of column 2-->
    <!--Space between regions-->
    <cell/>
    <!--Start of range region in row 2 column 2-->
    <!--Label 1-->
    <cell hAlign="Full">
      <textLabel label="Hire Date  " text-align="Right"/>
    </cell>
    <!--Component 1-->
    <cell hAlign="Full">
      <dateField name="hiredatestart" dateFormat="DD-MM-YYYY"/>
    </cell>
    <!--Label 2-->
    <cell hAlign="Full">
      <textLabel label="to  " text-align="Right"/>
    </cell>
    <!--Component 2-->
    <cell hAlign="Full">
      <dateField name="hiredateend" dateFormat="DD-MM-YYYY"/>
    </cell>
    <!--Right margin-->
    <cell/>
  </row>
  <!--Space between rows-->
  <row height="5"/>
  <!--Row for search, clear buttons-->
  <row height="20">
    <!--Left margin-->
    <cell/>
    <!--Place holder cell-->
    <cell columnSpan="6"/>
    <!--Clear button-->
    <cell hAlign="Right" childWidth="100">
      <button label="Clear" name="button_clear">
        <events>
          <buttonPress action="clearEmpSearch"/>
        </events>
      </button>
    </cell>
    <!--Space between components-->
    <cell/>
    <!--Search button-->
    <cell hAlign="Right" childWidth="100">
      <button label="Search" name="button_search">
        <events>
          <buttonPress action="doEmpSearch"/>
        </events>
      </button>
    </cell>
    <!--Right margin-->
    <cell/>
  </row>
</tableLayout>
</panel>

The developer can also view the search panel in the preview tab.

The Code tab is not editable. It shows the code that drives the search panel.

The doSearch procedure executes when the user clicks the search button. The clearSearchFields procedure clears the values the user entered to the fields in the search panel XML. Below is a sample package generated by the wizard.

CREATE OR REPLACE PACKAGE BODY HR.empsearch_pkg IS

--Comments in the code explain how the doSearch procedure works. 
--They are not part of the code generated by the wizard. They are added for this tutorial.
procedure doSearch is
  --PL/SQL table variable that stores the values entered by the user to the search
  --fields. Each value is coupled with a bind variable that it will populate when the
  --datasource query is executed.
  v_searchFields_t api_datasource.tt_bindvarValue;
begin
  --The generated search panel's name is empSearch.
  --get the value entered to the textField component named firstname.
  v_searchFields_t(1).value_tx:=api_component.getValueTx('empSearch.firstname');
  --associate the bind variable :firstname to the value. The value will populate
  --this bind variable when the query is executed.
  v_searchFields_t(1).bindvar_tx:='firstname';
  --indicates if Formspider should look for override operators in the value
  --such as >,=,<.
  v_searchFields_t(1).allowoverride_yn:='N';
  --repeat the steps above for every search field in the search panel.
  v_searchFields_t(2).value_tx:=api_component.getValueTx('empSearch.lastname');
  v_searchFields_t(2).bindvar_tx:='lastname';
  v_searchFields_t(2).allowoverride_yn:='N';
  v_searchFields_t(3).value_nr:=api_component.getValueNr('empSearch.employeeid');
  v_searchFields_t(3).bindvar_tx:='employeeid';
  v_searchFields_t(3).allowoverride_yn:='N';
  v_searchFields_t(4).value_dt:=api_component.getValueDt('empSearch.hiredatestart');
  v_searchFields_t(4).bindvar_tx:='hiredatestart';
  v_searchFields_t(4).allowoverride_yn:='N';
  v_searchFields_t(4).formatmask_tx:='DD-MM-YYYY';
  v_searchFields_t(5).value_dt:=api_component.getValueDt('empSearch.hiredateend');
  v_searchFields_t(5).bindvar_tx:='hiredateend';
  v_searchFields_t(5).allowoverride_yn:='N';
  v_searchFields_t(5).formatmask_tx:='DD-MM-YYYY';
  --Update the where clause of the datasource to be queried.
  --api_datasource.all_criteria keyword indicates that every criteria specified for
  --the datasource definition must be evaluated to construct the where clause.
  --Unless you are doing something very complex use this as the second input
  --parameter.
  --v_searchfields_t is sent to the setWhereClause API so that the API can
  --populate the bind variables in the datasource.
  api_datasource.setWhereClause('EMPLOYEES1',
  api_datasource.all_criteria,
  v_searchFields_t);
  --run the query.
  api_datasource.executeQuery('EMPLOYEES1');
exception
  when api_exception.e_conversion then
    raise;
  when api_exception.e_missingMandatoryCriterion then
    raise;
  when api_exception.e_atLeastOneCriterion then
    raise;
end;

procedure clearSearchFields is
begin
  api_component.setvalue('empSearch.firstname','');
  api_component.setvalue('empSearch.lastname','');
  api_component.setvalue('empSearch.employeeid',to_number(null));
  api_component.setvalue('empSearch.hiredatestart',to_date(null));
  api_component.setvalue('empSearch.hiredateend',to_date(null));
end;

END;

Clicking the Create button in the Preview Screen, generates the search panel in the application, and the PL/SQL code in the datasource schema of the application.