Changes between Version 19 and Version 20 of BluePrintSearch


Ignore:
Timestamp:
11/08/12 00:09:52 (9 years ago)
Author:
Michael Howden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BluePrintSearch

    v19 v20  
    3939
    4040== Implementation ==
    41 
    42 === Back-End ===
    43 
    44 ==== REST Interface ====
    45 
    46 The '''S3Search''' class implements the '''[wiki:S3XRC/S3Method S3Method]''' interface, and is connected to the {{{search}}} URL method in [wiki:S3XRC/RESTfulAPI/s3_rest_controller s3_rest_controller]:
    47 
    48 {{{
    49 http://localhost:8000/eden/hms/hospital/search
    50 }}}
    51 
    52 '''S3Search''' implements both interactive and non-interactive search methods. Currently supported formats are:
    53 
    54   - HTML
    55   - JSON
    56 
    57 There is a generic '''S3Search''' default instance connected to all resources, which will be used unless there is a resource-specific instance configured. However, this default instance does '''not''' provide any interactive search methods (JSON only).
    58 
    59 To connect a custom {{{S3Search}}} instance to a resource (in order to add interactive search methods), use {{{s3xrc.model.configure}}}:
    60 
    61 {{{
    62 s3xrc.model.configure(table, search_method=my_s3search_instance
    63 }}}
    64 
    65 See the next paragraph for how to build and connect a custom '''S3Search''' instance for a resource.
    66 
    67 ==== Configuring Interactive search methods ====
    68 
    69 For interactive search, a custom '''S3Search''' instance can be configured per resource, using instances of classes implementing the '''S3SearchWidget''' interface to create search forms.
    70 
    71   ''Note:'' Since neither S3Search nor S3SearchWidgets actually contain any link to a particular resource, their instances can be re-used across multiple resources, as long as the search fields are the same.
    72 
    73 Two interactive search forms can be configured (both of which are optional): '''simple''' and '''advanced''', where the user can toggle between these forms (if both are defined).
    74 
    75 {{{
    76     # Use a variable to hold the S3Search instance
    77     hms_hospital_search = s3base.S3Search(
    78 
    79         # Simple search form as a tuple of widgets:
    80         simple=(
    81                   # simple full-text search widget:
    82                   s3base.S3SearchSimpleWidget(
    83                     name="hospital_search_advanced",             # widget name must be specified and unique in the form!
    84                     label=T("Name and/or ID"),                   # Label for the search field
    85                     comment=T("To search for a hospital, ..."),  # Tooltip text for the search field
    86                     field=["paho_uuid",                          # Names of fields to search in
    87                            "gov_uuid",
    88                            "name",
    89                            "aka1",
    90                            "aka2",
    91                           ]
    92                   ), # <-- note the comma!
    93         ),
    94 
    95         # Advanced search form as a tuple of widgets:
    96         advanced=(
    97 
    98                   # simple full-text search widget:
    99                   s3base.S3SearchSimpleWidget(
    100                     name="hospital_search_advanced",
    101                     label=T("Name, Org and/or ID"),
    102                     comment=T("To search for a hospital, ..."),
    103                     field=["paho_uuid",
    104                            "gov_uuid",
    105                            "name",
    106                            "aka1",
    107                            "aka2",
    108                            "contact.name",                       # "." separator: search in component
    109                            "organisation_id$name",               # "$" separator: search in records referenced by organisation_id
    110                            "organisation_id$acronym"
    111                           ]
    112                   ),
    113 
    114                   # MinMax search widget to filter for a range of values:
    115                   s3base.S3SearchMinMaxWidget(
    116                     name="hospital_search_bedcount",
    117                     method="range",                              # widget-specific attribute "method"
    118                     label=T("Total Beds"),
    119                     comment=T("Select a range for the ..."),
    120                     field="total_beds"                           # most widgets only support one search field
    121                   )
    122         ))
    123 
    124     # Set as standard search method for this resource
    125     s3xrc.model.configure(db.hms_hospital, search_method=hms_hospital_search)
    126 
    127 }}}
    128 
    129 The {{{simple}}} form usually consists of a {{{S3SearchSimpleWidget}}} which performs a simple full-text search through various fields of the resource. However, the {{{simple}}} form may also be configured with other search widgets. In the same manner, the {{{advanced}}} form can include the {{{S3SearchSimpleWidget}}}.
    130 
    131 When calling the {{{search}}} method, the {{{simple}}} form will be opened first, while the {{{advanced}}} form is hidden (if only the advanced form is defined, then it will of course not be hidden). By clicking the ''Advanced Search'' link below the form, the user can switch to the {{{advanced}}} form, and vice versa. The forms are independent, i.e. the user can only submit one of them.
    132 
    133   - {{{modules/s3/s3search.py}}}
    134 
    135 ==== S3SearchWidgets ====
    136 
    137 ===== S3SearchSimpleWidget =====
    138 
    139   - ''tbd''
    140 
    141 ===== S3SearchMinMaxWidget =====
    142 
    143   - ''tbd''
    144 
    145 ===== S3SearchSelectWidget =====
    146 
    147   - ''tbd''
    148 
    149 ===== S3SearchLocationWidget =====
    150 [wiki:BluePrintGISLocationsSearch]
    151 
    152 ==== S3Search Subclasses ====
    153 
    154 ===== S3PersonSearch =====
    155 
    156   - ''tbd''
    157 
    158 ===== S3LocationSearch =====
    159 
    160   - ''tbd''
     41* DeveloperGuidelines/Search
    16142
    16243----
    163 BluePrints
     44* BluePrints
     45* BluePrint/Search/Async