{"type":"doc","content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Background","type":"text"}]},{"type":"paragraph","content":[{"text":"Prior to OpenMRS version 1.8, the search widgets were written with dojo which involved writing a separate javascript file where you would have to extended the parent OpenmrsSearch for each Openmrs Object if it were to be searchable in the webapp. The widgets would fetch all hits in one ajax query which would take a while to return all the hits in case there are many making the widgets slow. In 1.8, this was changed by introducing a single and more generic search widget written with jquery, the widget is faster from a user's stand point in that it fetches just the exact number of results to display on the first page and then continue to query the server for the rest in the background while updating the table until all results are returned. The reason behind this is that it should take way less time to display the first N results to display on the first page rather waiting for all the matching hits to be returned in one call in case there are many. The objective is to increase the perceived speed from a user's point of view since they get back results for the first page in a nick of time even if it isn't all.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How to include a search widget for a domain object in a jsp","type":"text","marks":[{"type":"strong"},{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph","content":[{"text":"This can be relatively simple if the domain objects to search already have the required methods in the API. Currently the required methods have been added for Concepts, Encounters, Patients, Users, Locations, Providers, Drugs and ConceptReferenceTerms. Let's assume you wish to add an encounter search widget to your jsp, add the snippet below to your jsp (you can leave out the javascript and css files that you already have in the parent jsp).","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n<%-- (OPTIONAL) This should be the target DWR service that processes the http requests for results in case you fetch them via DWR --%>\n\n\n<%-- (OPTIONAL) Include this to apply css to improve the look and feel of the widget if the containing page doesn't include it --%>\n\n\n<%-- This is required if the containing page doesn't include it --%>\n\n\n<%-- REQUIRED --%>\n\n\n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The first four html includes are required because they contain the necessary scripts used by the widgets and the css file for improved styling via datatables' support for jquery-ui themes so that the widgets match the active theme on the page.","type":"text"}]},{"type":"paragraph","content":[{"text":"You call to the server needs to return a map of the results with the following key names:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"count","type":"text","marks":[{"type":"strong"}]},{"text":": Maps to the count of the total expected number of hits, this is only required for the first call, therefore in your code on the server, it is recommended to check when the start index is 0, you include the count","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"objectList","type":"text","marks":[{"type":"strong"}]},{"text":": Maps to the actual list of hits","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"notification","type":"text","marks":[{"type":"strong"}]},{"text":": Maps to an informative or error message you wish to display for the user about the results in the UI","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"searchAgain","type":"text","marks":[{"type":"strong"}]},{"text":": Maps to the phrase against which to search again, when this key is included with a value, the search widget machinery will discard the current results and re run the search against the new specified phrase, a use case for this is if there are no matches to what the user originally entered and you wish to send them back results based on a shorter phrase","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Next thing is to initialize the widget and there are 2 ways to do it, the one used above is the one which delegates to a helper function that takes in 6 arguments, the arguments are;","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"elementId","type":"text","marks":[{"type":"strong"}]},{"text":": the id of the element that will be the container of the widget","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"showIncludeVoided","type":"text","marks":[{"type":"strong"}]},{"text":": bool (default: false) - Specifies whether the 'includeVoided' checkbox and label should be displayed","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"searchHandler","type":"text","marks":[{"type":"strong"}]},{"text":": function(text, resultHandler, options) (default:null) The function to be called to fetch search results from the server","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"selectionHandler","type":"text","marks":[{"type":"strong"}]},{"text":": function(index, rowData)","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"fieldsAndHeaders","type":"text","marks":[{"type":"strong"}]},{"text":": Array of fieldNames and column header maps","type":"text"}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"otherOptions","type":"text","marks":[{"type":"strong"}]},{"text":": Array of mappings between the property names and their corresponding values, see below for the complete list of widget properties under the 'Widget properties' section","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"the id of the element inside which the widget should be embedded, the rest of them are configuration properties that are explained below under the 'widget properties' section.","type":"text"}]},{"type":"paragraph","content":[{"text":"Below is the other way of how to initialize the widget:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n$j(document).ready(function() {\n \t\t$j(\"#elementId\").openmrsSearch({\n \t\t\tsearchLabel:'',\n \t\t\tsearchPlaceholder: '',\n \t\t\tsearchHandler: doSearchHandler,\n \t\t\tselectionHandler: doSelectionHandler,\n \t\t\tfieldsAndHeaders: [\t{fieldName:\"personName\", header:\"Patient Name},\n\t\t\t\t\t{fieldName:\"encounterType\", header:\"Encounter Type},\n\t\t\t\t\t{fieldName:\"formName\", header:\"Encounter Form},\n\t\t\t\t\t{fieldName:\"providerName\", header:\"Encounter Provider},\n\t\t\t\t\t{fieldName:\"location\", header:\"Encounter Location},\n\t\t\t\t\t{fieldName:\"encounterDateString\", header:\"Encounter Date}\n\t\t\t\t]\n \t\t});\n \t});\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The arguments passed to the widgets are to used to customize the widget properties, in the example above, '","type":"text"},{"text":"searchLabel","type":"text","marks":[{"type":"strong"}]},{"text":"' specifies the label that appears to the left of the search input box, '","type":"text"},{"text":"searchPlaceHolder","type":"text","marks":[{"type":"strong"}]},{"text":"' specifies the text to display inside the input box as a place holder, '","type":"text"},{"text":"searchHandler","type":"text","marks":[{"type":"strong"}]},{"text":"' specifies the javascript function to be called to fetch the hits from the server, and '","type":"text"},{"text":"fieldsAndHeaders","type":"text","marks":[{"type":"strong"}]},{"text":"' specifies the properties of the returned objects to display in the table of results along with their respective column headers, see below for the full list of the widget properties. '","type":"text"},{"text":"SelectionHandler","type":"text","marks":[{"type":"strong"}]},{"text":"' specifies the function to be called when the user selects a row in the table, in our example above, we open the encounter form and the encounter to edit becomes the selected one.","type":"text"}]},{"type":"paragraph","content":[{"text":"'","type":"text"},{"text":"SearchHandler","type":"text","marks":[{"type":"strong"}]},{"text":"' specifies the function that will get called by the script to fetch results from the server, the function gets called at least once once the search is triggered. The first call is expected to return a map with 2 key-value pairs i.e the expected total count of results and results to display on the first page. Typically, you should have logic on the server that get called by this function via ajax and it is important to make sure it returns the expected map. The keys in the returned map are 'count' and 'objectList' and their values should be the total count of expected results and the results to display on the first page respectively. Any subsequent calls to the search handler after the first call don't require that the count gets returned.","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example, we call the DWREncounterService.findCountAndEncounters(String, boolean, Integer, Integer, boolean) method and below is how the code could like like:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\npublic Map findCountAndEncounters(String phrase, boolean includeVoided, Integer start, Integer length,\n\t boolean getMatchCount) throws APIException {\n\t\t//Map to return\n\t\tMap resultsMap = new HashMap();\n\t\tVector

Browser not supported