<!--
  PreConfigured Search XML Example v1.28
  Andrew Taylor <andy.taylor@qtility.com>
  Wed 22 Oct, 2008
  
  XML as parsed from specification with in-place comments and markup.
   
  The following markup prefixes are used: 
    - AT: Comments by Andrew Taylor

  Tue 25 Nov, summary
    SEARCH/WHERE/ROW/CONTROL/MULTI_SHOWN: added 
    
  Thur 6 Nov, comment summary
    SEARCH/WHERE/ROW  
    SEARCH/WHERE/ROW/CONTROL/DEFAULT_SEARCH_OP
    SEARCH/WHERE/ROW/CONTROL/CTRL_TYPE
    SEARCH/WHERE/ROW/CONTROL/INLINE
    SEARCH/WHERE/ROW/CONTROL/REQUIRED
-->

<!DOCTYPE SEARCH_CONFIG SYSTEM "custom/pcs/search.dtd">
<!-- overall search page functionality and appearance -->
<SEARCH_CONFIG>
  <!-- 
    Search page access object used to construct the search selector
    the search page access object document type in the target installation
    
    This is the type of the contentless object used to construct the dynamic
    search nodes.  The type has a name, parent name and acl, among possible others, which
    is used to create the hierarchy.  
  -->
  <SEARCH_PAGE_ACCESS_OBJECT>type_name</SEARCH_PAGE_ACCESS_OBJECT>
  
  <!--  
    This entry will lookup defined PCS in search.xml and do a UNION full text searches against all
    defined searchable attributes in the defined PCS against the specific types, with the last UNION
    select on report's object name.
  -->
  <SIMPLE_SEARCH>
    <!--
      The result will start with object_type as the first column, then the attributes from the included PCS
      searches.
    -->
    <INCLUDE_PCS>
      <!-- Search1 from PCS being used -->
      <PCS>Search_Data_Control_Object_Name</PCS>
      <!-- Search2 from PCS being used -->
      <PCS>Search_Data_Control_Object_Name</PCS>
      <!-- ... There may be multiple rows -->
    </INCLUDE_PCS>
    
    <!--
      Show attribute will mark the following attributes as visible by default (overriding PCS settings if
      applicable)
    -->    
    <SHOW_COLUMNS>
      <!-- 
        Attribute name 
      -->
      <DM_NAME>attribute1</DM_NAME>
      <!-- ... There may be multiple rows -->
    </SHOW_COLUMNS>
    <!--
      Hide attribute will mark the following attributes as invisible by default (overriding PCS settings if
      applicable)
    -->
    <HIDE_COLUMNS>
      <!-- Attribute name -->
      <DM_NAME>attribute2</DM_NAME>
      <!-- ...There may be multiple rows -->
    </HIDE_COLUMNS>
  </SIMPLE_SEARCH>
  
  <!--
    This entry will create a distinct doctype lists from all the included PCS along with their parents up
    to the enterprise_document level to form the drop down list for available objects in the search
    page
  -->
  <ADVANCED_SEARCH>
    <!--
      The default search result (if the type being searched is not specified by a PCS) will show all non-
      inherited custom attribute of that type besides object_name
      
      The search result will use the attributes defined by the PCS if one exists
    -->
    <INCLUDE_PCS>
      <!-- Search1 from PCS being used -->
      <PCS>Search_Data_Control_Object_Name</PCS>
      <!-- Search2 from PCS being used -->
      <PCS>Search_Data_Control_Object_Name</PCS>
      <!-- ... There may be multiple rows -->
    </INCLUDE_PCS>
    
    <!--
      Show attribute will mark the following attributes as visible by default (overriding PCS settings if
      applicable)
    -->
    <SHOW_COLUMNS>
      <!-- Attribute name -->
      <DM_NAME>attribute1</DM_NAME>
      <!-- ... There may be multiple rows -->
    </SHOW_COLUMNS>
        
    <!--
      Hide attribute will mark the following attributes as invisible by default (overriding PCS settings if
      applicable)
    -->  
    <HIDE_COLUMNS>
      <!-- 
        Attribute name
      -->
      <DM_NAME>attribute2</DM_NAME>
      <!-- ... There may be multiple rows -->
    </HIDE_COLUMNS>
  </ADVANCED_SEARCH>

  <!-- Pre-Configured Search element -->
  <!-- 
    AT: name should be without underscores or strange characters.  Spaces
        are replaced with underscores for component names
  -->
  <SEARCH name="Test Search Name">
    <!--
      The General section configures the house keeping environment settings for the PCS
      Search title displayed on the very top of the search attribute page
    -->
    <GENERAL>
      <TITLE><![CDATA[Search title Text]]></TITLE>
      <!-- Doctype being search against -->
      <DOC_TYPE>type_name</DOC_TYPE>
      <!-- Date format Pattern used through out the search and search result list -->
      <DATE_FORMAT>MM-dd-yyyy</DATE_FORMAT>
      <!-- 
        Should the search result list grid fit all to the visible screen estate? Default is FALSE.
        If set to TRUE then the Heading label is allowed to wrap and all fields are auto sized as much as
        possible, scroll bar is still allowed
      -->
      <WRAP_HEADER>FALSE</WRAP_HEADER>
      
      <!--            
        Max. results to return from this search. This value overrides DFC configuration settings.
        For DQL, max results can be via the ENABLE clause.  
        
        ie: SELECT * FROM AP ENABLE(TRY_FTDQL_FIRST, OPTIMIZE_TOP 500, RETURN_TOP 500)
         
        Also, the possibility of hitting limits should be explored.
        ie: "the search limit has been reached and only the first xxx results have been returned"
      -->
      <MAX_RESULT>3000</MAX_RESULT>
      
      <!--
        Use full text indexing.  [true|false] default true.  Required for installs without
        fulltext.
        AT: added
      -->
      <USE_FULL_TEXT>true</USE_FULL_TEXT>
      
      <!--
        Default is Standard, which allows user to input search values in the search attribute page
       If set to External then the attribute defined in <ROW> is used as URL parameters and search
        does not show up in web listing.

       (i.e. vendorkey=5167273&filenumber=776625)
       the search operator for each URL parameters is "=" unless defined in <DEFAULT_SEARCH_OP>
      -->
      <SEARCH_TYPE><![CDATA[Standard]]></SEARCH_TYPE>
      
      <!--
       Global search clause operator (AND/OR), the default if unspecified is "AND"
       This entry determines what operator to use during the DQL constructions between the search
       values in the WHERE clauses
      -->
      <GLOBAL_SEARCH_OP>AND</GLOBAL_SEARCH_OP>
      
      <!--                                                                                                                           
       Notes:                                                                                                         
       - Search attribute page must not expand so wide that a horizontal scroll bar appears
       - Search Operators and search configuration parameter are read from the data dictionary (i.e. set
         from DAB), all operators must be supported.
       - For Date controls the Between operator when selected (whether by default or manually) will
         dynamically add an additional calendar control behind the original one with label " - " so the user
         can input the range values.
       - Also For Date controls, when the user decided not to use the Between operator all dynamically
         added controls will be set to Null and removed from screen
       - If the "Between" search operator is used in an external search it will read 2 consecutive
         parameters from the URL rather than the normal 1.
      -->
    </GENERAL>

    <SELECT>
      <!-- This applies to the entire search result -->
      <SORT>
        <!--                                                                                    
          Custom sort will place a column like the lock icon column to the left of the grid (OPTIONAL)
          Fields in the custom sort filed separated by comma will be combined to form a single value which
          will be used to sort the list when the header is clicked, the actual value will not be shown in the grid
          however (it would appear to be a blank column)
          If defined, override default sort
          
          NOTE: this is not practically possible once the results are shown.  It is possible to have the sorting
          done at query time, but not to reshuffle and maintain paging, etc.  Basically, the only way to properly sort
          is to iterate through all results, or to resubmit the query with sorting altered.
        -->
        <CUSTOM_SORT>
          <!-- Sorting for one attribute -->
          <SORT_ATTR>
            <!-- Name of attribute -->
            <DM_NAME>attribute1</DM_NAME>
            <!-- Sorting direction for attribute -->
            <SORT_ORDER>asc|desc</SORT_ORDER>
          </SORT_ATTR>
          <!-- could have multiple sort_attr -->
        </CUSTOM_SORT>
        
        <!--
          The attribute on which the search result list will be sorted. If it is undefined, or if it is invalid then
          creation_date will be used as default sort
        -->
        <DEFAULT_SORT>attribute_name</DEFAULT_SORT>
        <!-- The values are ascending/descending (default is asc) -->
        <SORT_ORDER>asc or desc</SORT_ORDER>
      </SORT>
      
      <!--
       Config the display of each attribute in the search result list
      -->                                                      
      <ATTRIBUTE>
        <!--
          Exact width of column in pixels (OPTIONAL)                                                                                          
          auto or undefined means to use default Webtop behaviour
          i.e. 50 means the control will wrap the field content at every 50 pixels
        -->                                                                       
        <WIDTH>auto</WIDTH>
        <!--
          The length property specify how many of the initial characters it will display from the value, excess
          characters with end with "..."
          the tip pop-up will still show the full content (default Webtop behaviour)
        -->                                                        
        <LENGTH>255</LENGTH>
        <!--
          Attribute Display Alignment (OPTIONAL: default is center, center)                                                         
          i.e. left, top = All cells in this column will align to upper left hand corner
        -->                                                
        <ALIGNMENT>
          <HORIZONTAL>center</HORIZONTAL>
          <VERTICAL>center</VERTICAL>
        </ALIGNMENT>
        
        <!--
          Show this attribute as a column in the browse components?  If not given, 
          defaults to true
          
          AT: added
        -->
        <BROWSE_SHOWN>false</BROWSE_SHOWN>
        
        <!--                                                                                                                                 
          if label is not defined, then the Docapp label will be used and at last if a label does not exist then
          the attribute name will be used
        -->                                                                                                                                       
        <LABEL><![CDATA[Attribute Label Text]]></LABEL>
        <!--
          Display formats must support, text, dollar, number, link, and date (format is specified in XML)
          Default is Webtop best guess
          
          AT: to be in line with webtop adv search, 'text' should be 'string' and 'date' should be 'time'
              Also, there's nothing in spec for boolean type 
        -->                             
        <DISPLAY_FORMAT>Attribute Display Type</DISPLAY_FORMAT>
        
        
        <!--
          Attribute name for data source
          If name is invalid print "N/A check config" in the value
          when error, this would be a SELECT "N/A check config" as attribute_name statement                                      
          
          NOTE: this will require a pre-check query for the dm_name.  This pre-check is best done at deploy time.  If
          done at query time, there is the additional overhead of running the queries for each attribute.
        -->                                                                                            
        <DM_NAME>Attribute Name</DM_NAME>
      </ATTRIBUTE>
      <!-- ...  additional attributes -->
    </SELECT>

    <!--
      This Tag allows administrators to specify the search attribute page table layout
    -->                 
    <CONTROL_TABLE>
      <!--
        Default column that contains the labels of the search fields
      -->                                          
      <CONTROL_COLUMN name="search_label">
        <!-- 
          Exact width of column in characters in pixels (OPTIONAL) 
          auto or undefined means to use default Webtop behaviour                                                           
        -->                                                                           
        <WIDTH>20</WIDTH>
          
        <!--
          Column header text (OPTIONAL)
          i.e. Display a section header like Attributes on top of all the labels
        -->                                              
        <HEADING><![CDATA[Attributes]]></HEADING>
        
        <!--
          Column Alignment (OPTIONAL: default is right, center)                                                      
          i.e. left, top = All cells in this column will align to upper left hand corner
        -->
        <ALIGNMENT>
          <HORIZONTAL>left</HORIZONTAL>
          <VERTICAL>top</VERTICAL>
        </ALIGNMENT>
      </CONTROL_COLUMN>
      
      <!--
       Default column that contains the search operators
      -->
      <CONTROL_COLUMN name="search_operator">
        <!-- default is blank -->
        <WIDTH></WIDTH>
        <HEADING><![CDATA[]]></HEADING>
        <ALIGNMENT></ALIGNMENT>
      </CONTROL_COLUMN>
      
      <!--
       Default field that contains the search input(s) from user
        
       If a list control or multiple column controls are required then they would all fit into the cell           
       programmatically by the search page construction algorithm                                                          
      -->
      <CONTROL_COLUMN name="search_data">
        <WIDTH>30</WIDTH>
        <HEADING><![CDATA[]]></HEADING>
        <ALIGNMENT>
          <HORIZONTAL>left</HORIZONTAL>
          <VERTICAL>top</VERTICAL>
        </ALIGNMENT>
      </CONTROL_COLUMN>
      
      
      <!--                                                                                                               
       Default field that shows if a field is required and/or where validation had failed
       Usually it will display a red "*" or a 16x16 graphics
      -->
      <CONTROL_COLUMN name="search_indicator">
        <WIDTH>1</WIDTH>
        <HEADING><![CDATA[]]></HEADING>
        <ALIGNMENT>
          <HORIZONTAL>left</HORIZONTAL>
          <VERTICAL>top</VERTICAL>
        </ALIGNMENT>
        
        <!--
          Text used to indicate a required field.  Optional, default is *. If unspecified.
          REQUIRED_IMAGE will be used in preference, if given.
        -->
        <REQUIRED_TEXT>*</REQUIRED_TEXT>
        <!--
          URL to image to be used to indicate a required field.  Optional, default is to use
          REQUIRED_TEXT.  Will supersede REQUIRED_TEXT if both are given.
        -->
        <REQUIRED_IMAGE>some/required.png</REQUIRED_IMAGE>
        
        <!--
          Text used to indicate error.  Optional, default is ! If unspecified.
          ERROR_IMAGE will be used in preference, if given.
        -->
        <ERROR_TEXT>!</ERROR_TEXT>
        <!--
          URL to image to be used to indicate an error.  Optional, default is to use
          ERROR_TEXT.  Will supersede ERROR_TEXT if both are given.
        -->
        <ERROR_IMAGE>images/error.png</ERROR_IMAGE>
      </CONTROL_COLUMN>
      <!--
        Can be multiple columns ...
      -->
    </CONTROL_TABLE>
    
    <!--
      Search Attribute Page Controls Configuration
      Row definition. Can be multiple rows.
      
      AT: can this contain ROWs in addition to MULTI_CTRL-ROWs?
    -->
    <WHERE>
      <!--
        Multi-Controls Row defines if several search controls should be on 1 line (OPTIONAL)
        
        AT: contains one or more rows
        AT: changed from MULTI_CTRL_ROW to ROW due to XSL requirement
        AT: unique among siblings, no spaces
      -->                  
      <ROW name="series_name">
        <!-- The label for this group of controls -->
        <LABEL><![CDATA[Series Label Text]]></LABEL>
        <!--
         Multi-Controls Row search operator (AND/OR), the default if unspecified is "AND"
         This entry determines what operator to use during the DQL constructions between the search
         values in the WHERE clauses of this group of controls
          
         AT: the MULTI_CTRL_ prefix is indicated by position, could be named
         SEARCH_OP, or just OP
        -->                                     
        <MULTI_CTRL_SEARCH_OP>AND</MULTI_CTRL_SEARCH_OP>
        
        <!-- 
          nested row definition
        -->                                  
        <ROW name = "search_row_name">
          <!--
            Overriding label
            if label is not defined, then the Docapp label will be used and at last if a label does not exist then
            the attribute name will be used
          --> 
          <LABEL><![CDATA[Search Label Text]]></LABEL>
          <!-- 
            Attribute being searched against
          -->
          <DM_NAME>Attribute Name</DM_NAME>
          <!-- 
            Tip for what this field is and example

          -->
          <TOOL_TIP><![CDATA[Explanation of this field]]></TOOL_TIP>
          
          <!-- 
            Specify the width of the control in pixels 
            If undefined, the controls will be sized automatically base on the width of the cell
          -->
          <WIDTH>20</WIDTH>

          <!--
            specification of the configuration for the displayed control
          -->          
          <CONTROL>
            <!--
              The type of control to be used such as Text, Date, multi-select list box, drop down, cascading drop
              down, radio, calendar, and EXTERNAL
              All default existing controls found in Webtop should be made available besides the above
              mentioned controls. If control is set to EXTERNAL then the value will be read from the URL
              parameters in the order of the <ROW> tags defined in the <WHERE> section
              
              EXTERNAL SEARCHES
              Searches may be invoked immediately with parameters specified on the url.  To do so,
              create a search block and access it via:
              
              http://[webtophost]/[webtopprefix]/component/main?startupAction=pcs_[sname]&[rname1]=[rval1]&[rname1]_op=[rname1op]
              
              where:
              webtophost: host running webtop
              webtopprefix: prefix for webtop instance
              sname: name of search, as specified in search.xml (/SEACH_CONFIG/SEARCH@name)
              rname1: name of the row to set as appearing in search.xml (/SEACH_CONFIG/SEARCH@name=[sname]/CONTROL_TABLE/WHERE/ROW@name)
              rval1: search rname1 for this value
              rname1op: operator used in the search for rname1.  Operator is dependant on the row type...
                such as contains, is, not, etc.  See DEFAULT_SEARCH_OP for valid values.  The operator 
                is optional (and will default to the DEFAULT_SEARCH_OP), but the value *must* appear 
                for it to be found.
              
              a working example without operator would be
              
              http://devbp.xdocs.ca/bpdocs/component/main?startupAction=pcs_mysearch&somerow=some value
              which would use the mysearch search to search the somrow row for 'some value'
              
              and with ops
              
              http://devbp.xdocs.ca/bpdocs/component/main?startupAction=pcs_mysearch&somerow=some value&somerow_op=contains
              which would use the mysearch search to search for somrow rows containing  'some value'
              
              AT: valid values: [text,number,date,boolean,list,multi,radio,cascading,EXTERNAL]
            -->                              
            <CTRL_TYPE>type</CTRL_TYPE>
            
            <!--
              Number of lines to show in a multi row select, defaults to 4
              
              at: added
            -->
            <MULTI_SHOWN>8</MULTI_SHOWN>
            
            <!--
              Specify the default search operator
              If undefined then the default from data dictionary will be used, otherwise the default is "="
              
              AT: values are different for type, as given here
                  text: is,contains,not (!=),absent (not like '%x%')
                  number: is,not,greater,less
                  date: is,before,after
                  boolean: is
                  list: is,not
                  cascading: is
            -->
            <DEFAULT_SEARCH_OP><![CDATA[Contains]]></DEFAULT_SEARCH_OP>
            
            <!--
              XML for Drop Down and List control using DQL as source
              this section will be ignored if it is not a Drop Down or List control type in the <CTRL_TYPE>
            -->
            <QUERY>
              <!--
                Specify the DQL that will return the contents of a list box/drop down.  The full
                dql should be provided, as the query is not formulate and does not necessarily
                work with the search DOC_TYPE. The DQL should return two columns, the first being
                the option value and the second the option label.
                
                If this is a child cascading drop down then string '$PARENT' will be substituted
                with the value from the parent row (as indicated with PARENT_VALUE)
                
                The following is a basic query...
              -->
              <DQL>
                SELECT distinct VALUE, VALUE_LABEL from some_type 
                where VALUE is not null order by VALUE_LABEL asc
              </DQL>
              <!-- 
                 it shows an option list containing distinct values 
                from field VALUE with labels from the corresponding VALUE_LABEL field
                of the some_type type.  Values are distinct and not null and ordered 
                by label.  For a list, this would output something like:
                
                <select name="search_row_name">
                  <option value="another_value">Another Value</option>
                  <option value="some_value">Some Value</option>
                </select>
                
                A cascading example is
                
                <DQL>
                  SELECT distinct VALUE, VALUE_LABEL from some_type 
                  where VALUE is not null and $PARENT_CLAUSE
                  order by VALUE_LABEL
                </DQL>
                
                which select values and restricts to the parent.  Values would
                be output as above, but only value that also match the $PARENT_CLAUSE
                as specified in the PARENT_ROW are used.  The $PARENT_CLAUSE is 
                substituted with the DQL required to restrict to current chosen parent 
                value(s).
              -->
              
              <!--
                Specify if this is a child of a cascading drop down control (OPTIONAL)
                If specified, this will restrict selection of values to those conforming 
                with chosen parents.   See above for an example of using the $PARENT_CLAUSE
                to restrict within DQL statements.
              -->
              <PARENT_VALUE>ROW name</PARENT_VALUE>
              
            <!--
              Notes: suggestion - this should use the existing function that advanced search is using when the
              user select different objects and the attribute list is updated.
              
              AT: I take this to mean sticking with the default behaviour, which is a page refresh on data
              change, rather than in-page dhtml/ajax.
              AT: queryShow and queryOrder removed and replaced by fully specified DQL with
                  substitution
            -->
            </QUERY>
            
            <!--                                                                                                                               
              XML for Radio, Drop Down and List control using Hard Coded Values as source
              this section will be ignored if it is not a Drop Down or List control type in the <CTRL_TYPE>
              In file drop down definition section - Optional - used only of control is drop down or combo                     
              Specifies the list values being submitted to a search
            -->
            <INLINE>
              <!--
                AT: the fixed list definition has been changed to reflect possible 
                    requirements
              -->
              <!--
                An item to include in the fixed list.  If selected='true', the item
                will be selected by default.
              -->
              <LIST_ITEM [selected="true"]>
                <!--
                  The displayed name of the list item
                -->
                <NAME><![CDATA[User Choice 1]]></NAME>
                <!--
                  The value of the list item, which corresponds to a valid value
                  of the type as given in DM_NAME.  OPTIONAL.  If not given, the NAME
                  value is used
                -->
                <VALUE>uc_1</VALUE>
              </LIST_ITEM>
              <!-- can/will be more than one ITEM ... -->
              
              <!-- 
                AT: This was the old definition
                List index is the default showing column if <LST_LABEL> is undefined
              <LST_INDEX><![CDATA[1,2,3,etc...]]></LST_INDEX>
                List Label (OPTIONAL)
                List label if defined will be the showing column (the value being sent to search is still the index)
              <LST_LABEL><![CDATA[A,B,C,etc...]]></LST_LABEL>
                Notes: suggestion - this should use the existing function that advanced search is using when the
                user select different objects and the attribute list is updated.
              -->
            </INLINE>
            
            <!--
              Validation rule for this control's input
              Regular expression
              
              If given javascript regex validation against value should be triggered
              on change, displaying in-place VALIDATION_TEXT and prevent
              form submission.
              
              NOTE: if regex is invalid, might cause Unexpected Quantifier javascript error  
              
              AT: regex is in javascript notation, such as described at
                  http://www.regular-expressions.info/javascript.html
            -->
            <VALIDATION_RULE>[\d]*</VALIDATION_RULE>
            
            <!--
              Rule description for this control's input
              Description text
            -->
            <VALIDATION_TEXT><![CDATA[Must be 10 digits long]]></VALIDATION_TEXT>
            
            <!--
              AT: there is accomodation for required as a symbol, but no way to specify
                  a row to be required.
              
              Specify that a value must be given for this row.  Form submission is not
              possible without a value.
            -->  
            <REQUIRED>true</REQUIRED>
          </CONTROL>
        <!-- End of normal row definition -->                                 
        </ROW>
        <!-- ... there may be multiple rows -->
        
        <!--
          Postfix to the control.  On the same line after the control, 
          
          ie: Location: [55] - [46] - [002] M [100] W 
          W is postfix.
        -->
        <POSTFIX><![CDATA[postfix]]></POSTFIX>
      </ROW>
      
    </WHERE>
    
  </SEARCH>
  
  <!-- ... there may be multiple searches -->

<!-- end search config -->  
</SEARCH_CONFIG>
  

