[[TOC]]
= !BluePrint: RESTful Search Methods =

== Introduction ==

  - ''coming soon''

== Description ==

  - ''coming soon''

== Use-Cases ==

  - ''coming soon''

== Requirements ==

=== Functional Requirements ===

  - ''tbd''

=== Usability Requirements ===

  - ''tbd''

=== Performance Requirements ===

  - ''tbd''

=== Implementation Requirements ===

  - ''tbd''

== Design ==

=== User Interface ===

  - ''add mockups here''

== Implementation ==

=== Back-End ===

==== REST Interface ====

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]:

{{{
http://localhost:8000/eden/hms/hospital/search
}}}

'''S3Search''' implements both interactive and non-interactive search methods. Currently supported formats are:

  - HTML
  - JSON

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).

To connect a custom {{{S3Search}}} instance to a resource (in order to add interactive search methods), use {{{s3xrc.model.configure}}}:

{{{
s3xrc.model.configure(table, search_method=my_s3search_instance
}}}

See the next paragraph for how to build and connect a custom '''S3Search''' instance for a resource.

==== Configuring Interactive search methods ====

For interactive search, a custom '''S3Search''' instance can be configured per resource, using instances of classes implementing the '''S3SearchWidget''' interface to create search forms.

  ''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.

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).

{{{
    # Use a variable to hold the S3Search instance
    hms_hospital_search = s3base.S3Search(

        # Simple search form as a tuple of widgets:
        simple=(
                  # simple full-text search widget:
                  s3base.S3SearchSimpleWidget(
                    name="hospital_search_advanced",             # widget name must be specified and unique in the form!
                    label=T("Name and/or ID"),                   # Label for the search field
                    comment=T("To search for a hospital, ..."),  # Tooltip text for the search field
                    field=["paho_uuid",                          # Names of fields to search in
                           "gov_uuid",
                           "name",
                           "aka1",
                           "aka2",
                          ]
                  ), # <-- note the comma!
        ),

        # Advanced search form as a tuple of widgets:
        advanced=(

                  # simple full-text search widget:
                  s3base.S3SearchSimpleWidget(
                    name="hospital_search_advanced",
                    label=T("Name, Org and/or ID"),
                    comment=T("To search for a hospital, ..."),
                    field=["paho_uuid",
                           "gov_uuid",
                           "name",
                           "aka1",
                           "aka2",
                           "contact.name",                       # "." separator: search in component
                           "organisation_id$name",               # "$" separator: search in records referenced by organisation_id
                           "organisation_id$acronym"
                          ]
                  ),

                  # MinMax search widget to filter for a range of values:
                  s3base.S3SearchMinMaxWidget(
                    name="hospital_search_bedcount",
                    method="range",                              # widget-specific attribute "method"
                    label=T("Total Beds"),
                    comment=T("Select a range for the ..."),
                    field="total_beds"                           # most widgets only support one search field
                  )
        ))

    # Set as standard search method for this resource
    s3xrc.model.configure(db.hms_hospital, search_method=hms_hospital_search)

}}}

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}}}.

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.

  - {{{modules/s3/s3search.py}}}

==== S3SearchWidgets ====

===== S3SearchSimpleWidget =====

  - ''tbd''

===== S3SearchMinMaxWidget =====

  - ''tbd''

===== S3SearchSelectWidget =====

  - ''tbd''

===== S3SearchLocationWidget =====
[wiki:BluePrintGISLocationsSearch]

==== S3Search Subclasses ====

===== S3PersonSearch =====

  - ''tbd''

===== S3LocationSearch =====

  - ''tbd''

----
BluePrints