Using Search Profiles

Introduction
A search profile is a predefined search query where its search results are displayed in a block positioned on some Drupal pages. These search profiles are normally used to display list of information that match a search query. Search profiles are also to some extend aware of their context. For example, if the main topic of a page is about  and if we have a search profile that displays list of events, then when the search profile is used in the context of that page about cancer, then cancer related events should be displayed. That is one of the core purpose of the search profiles.

Three things needs to happen with search profiles
 * 1) Initially, the search query to be used in a search profile need to be created using the OSF Query Builder
 * 2) Then the search profile need to be embedded into a Drupal Block
 * 3) Finally, the Block need to be positioned in the Drupal portal

Using the Query Builder
The query builder (QB) is a generalized search utility for querying the datasets within a OSF instance. The QB has three purposes:
 * 1) It is a basis for learning about the structured data within a OSF instance
 * 2) It is a testbed for exploring the effect of attribute and value boostings on the ranking order of search results sets, and
 * 3) It is a means to refine queries and then generate query code that can be embedded into Web pages and templates.

General Overview and Operation
The QB consists of a top-line search box, followed below by a series of expand-and-collapse panels. Specialized actions take place within these panels. The operations of each of these panels is described below. Each panel also has a help icon, which when clicked brings up contextual help for that panel.

Upon invoking a search, a results listing appears at the bottom of the standard panels. Please make sure and review the  section since how results are presented in the query builder is one of its benefits.

The overall screenshot for the query builder is as follows:

Search Box and Input
Any standard site query may be entered into the search box. For legal and available query syntax, see the Search Syntax page.

A search is conducted upon invoking the  button. The resulting results set is then listed at the bottom of the page in scoring rank order. A  causes all settings throughout the QB to be returned to its default (start-up) settings, as if the application were reloaded. The one exception is that if a query had been entered into the top-line search box, it is kept.

The gear icon at far right turns inferencing on or not. By default, inferencing is on. To test the effect of inferencing, conduct the same search with inferencing on or not and select the 'type' attribute in one of the lower panels. When inferencing is on, generally the results set is much larger since matches to related (inferred) concepts are brought into the results.

Dataset Panel
Clicking on the Dataset panel causes it to expand. The panel then shows all datasets available on the default OSF endpoint: Each of the datasets may be included or not in the content basis used by the query builder by checking or unchecking its associated checkbox. Alternatively, all datasets may be selected or not using the global links at the top of the panel.

Each dataset shown also provides a count (in parentheses after the dataset title) for how many records it contains. If a query has already been entered into the top-line search box, these counts pertain to the number of record instances where the search query exists. If there is no query in the search box, the counts shown are for total numbers of records in each dataset.

As datasets are selected, their total number appears in the panel header. Whatever dataset selections are made in this panel remain active during the current QB session or until you actively change them. Upon next startup of the QB, all available datasets are selected as active by default.

Advanced Search Panel
The Advanced Search panel allows quite complicated queries to be built. These extensions are added to whatever query already exists in the top-line search box. If there is no query in that search box, then the specifications in this panel apply on their own.

Like the other panels, clicking on it causes it to expand; clicking on the expanded header causes it to collapse. Also, like all other panels, contextual help is provided via the icon button at the upper right of the panel.

When first expanded, a single line of new query expansion is presented. This line, from left to right, has an operator box, followed by an attribute selection dropdown, and then a means to assign a value to that attribute in the next box. At the end of the line a  button allows a new line to be added for additional query expansion. If the  button is selected, the current line is removed. The basic aspect of this panel is as shown:

The operator box enables multiple query expansion lines to be combined together or nested. The available operators are AND, OR or NOT, in combination or not with parentheses if nesting is also desired. They are selected via this dropdown list:

For a single expansion line, no operator needs to be designated in this first operator box. Thereafter, an operator must be specified to "chain together" more query expansion lines.

Once the operator is selected (or not, for a single line), it is next necessary to select one of the available attributes. These appear as a dropdown list in the next box. This attribute box features autocompletion, so beginning to type a few letters will match those same letters in the attribute titles no matter where the matching string may occur (beginning, middle or end of a word). As more letters get typed into the combobox entry, the selections get fewer.

The available attributes to select from also may be reduced in number based on prior selections or a query already entered into the top-line search box. That is, the attributes available for selection at any given step are limited to those that are active for the query that has been built to that point, with the narrowing occurring each time the 'Search' button is invoked without an intervening 'Clear'.

Thus, very complicated query constructions may result in very few attributes being available for further filtering.

The attributes themselves are of two types: There are free text entries and controlled vocabular entries, with these icons appearing in the adjacent values dropdown combobox. For free text entries, any term or string may be entered into this box; for controlled vocabulary entries, you must pick from one of the available options, which are presented to you via a dropddown list, also shown with an autocompletion icon. Like other autocompletion fields, typing more characters causes the possible entries to be narrowed to those that match the string. A good attribute to try this feature with is Subject, since there is a long list of subjects within the available ontologies.

You may construct as many query expansion lines as you would like, again with the caveat that attribute choices will continue to narrow with more filters. If you want to back up a step, you can delete the entire line.

At the bottom of the panel, a search may be invoked via the 'Search' button or all QB settings may be 'Clear' back to original settings. These buttons may be applied here, on this panel, or via the same buttons on the top-line search input.

Attributes Restrictions & Boosting Panel
The Attributes Restrictions and Boosting panel allows you to filter search results by attribute and to change boost values to affect the rankings of the results set. The attribute filters work in conjunction with any other specifications that have been made above, namely simple or advanced search.

Like the other panels, clicking on the Attributes panel causes it to expand; clicking on the expanded header causes it to collapse. Also, like all other panels, contextual help is provided via the icon button at the upper right of the panel. Here is the basic view of this panel: The attributes combobox works similarly to what was described for Advanced Search. Via autocompletion and the entry of a few characters, the listing of possible attributes to select from gets narrowed. Further, only those attributes that meet the dataset and query selections made elsewhere appear on this list.

Any attribute selected in this panel MUST exist in a given record in order for that result to appear in the results list. Thus, any entry, no matter the boosting weight assigned, must appear for a positive search hit. However, also note that ANY value for that attribute will satisfy the condition and be acceptable. (For actual value filtering, see next section.)

Once a filter is selected, it is then possible to indicate its relative weight in the results set ranking order. You do this by changing the value at the right of the entry line.

The plus button allows you to enter another filter or weighting boost. You may add as many of these filters as you wish.

At the bottom of the panel, a search may be invoked via the 'Search' button or all QB settings may be 'Clear' back to original settings. These buttons may be applied here, on this panel, or via the same buttons on the top-line search input.

Values Boosting Panel
The Values Boosting panel allows you to boost values to affect the rankings of the results set. It will not act to do any filtering whatsoever; for that purpose, see the Attributes panel above. The values boosts work in conjunction with any other specifications that have been made above, namely simple or advanced search or attribute boosting or filtering.

Like the other panels, clicking on the Values Boosting panel causes it to expand; clicking on the expanded header causes it to collapse. Also, like all other panels, contextual help is provided via the icon button at the upper right of the panel. Here is the basic view of this panel: The first combobox presented enables you to select which attribute you want to select for boosting values. The attributes themselves are of two types: There are free text entries and controlled vocabulary entries, with these icons appearing in the adjacent values dropdown combobox. For free text entries, any term or string may be entered into this box; for controlled vocabulary entries, you must pick from one of the available options, which are presented to you via a dropddown list, also shown with an autocompletion icon. Like other autocompletion fields, typing more characters causes the possible entries to be narrowed to those that match the string. A good attribute to try this feature with is Subject, since there is a long list of subjects within the available ontologies.

Once an attribute value is selected, it is then possible to indicate its relative weight in the results set ranking order. You do this by changing the value at the right of the entry line.

The plus  button allows you to enter another filter or weighting boost. You may add as many of these filters as you wish.

For a given document or result to receive this scoring boost, it must both have the applicable attribute AND the specific value you specified. Without both of those conditions being met, the record receives no scoring boost and its overall score is unaffected. (However, its absolute rank order might be lowered if other records or documents receive the boost causing them to appear higher in the results listing.)

At the bottom of the panel, a search may be invoked via the 'Search' button or all QB settings may be 'Clear' back to original settings. These buttons may be applied here, on this panel, or via the same buttons on the top-line search input.

Search Query Code Panel
The Search Query Code panel presents the internal query specification resulting from any of the prior search, dataset selection, filter selection or boosting factors. The code that is presented here may be copied by developers for Web page or layout template use. The code in this panel is also a good way to understand the various components in your queries.

Here is an example screen showing one of these code samples:

There are two sections available:
 * 1) This is the OSF-WS-PHP-API code that can be used to query the OSF instance using the Search web service endpoint
 * 2) This is an intermediary JSON object representation of the query. This is what is used to create the Search Profiles.
 * 1) This is an intermediary JSON object representation of the query. This is what is used to create the Search Profiles.
 * 1) This is an intermediary JSON object representation of the query. This is what is used to create the Search Profiles.

Search Profile
This section let you save the query you created as a OSF for Drupal Search Profile. The only thing you have to do is to define a name for that new search profile, and to click the  button. Once you saved a search profile, it will appears in the list of available search profiles (see below).

Results Listing
The results listing appears at the bottom of the expand/collapse panels discussed above. The results listing is one of the major benefits of the query builder in that it provides the full structural detail for each result and also displays its internal search score, which is shown at the upper right of each individual result record.

The results listing itself begins with a summary of the count for the results set produced by the various filters and query specifications in the query builder. These results are then paginated, in groups of ten, across potentially multiple results pages.

The basic appearance of the results listing, showing an example first result, appears as follows: The results section begins with the standard help icon and the paginator, as well as showing the total number of results for the current query and datasets. Then, each results listing follows a similar display format.

The first line of every result shows the record's title (prefLabel), what type of record it is as shown in italicized parentheses, and its search score at far right. Then, all structured data and metadata are presented below, with the attribute name shown in bold followed by its value. Note that if you mouseover any bolded property label (such as prefLabel) you will see a tooltip showing you the actual URI value for that property.

Most values are string text, but some are URLs, in which case a live link is presented. Some of the attributes or properties, too, also have records within one of the governing ontologies. Subject is a useful property to inspect in this manner. These are shown as a live link as well; clicking on them will take you to a structured data listing.

Saving a Search Profile
To create a search profile, we have to generate the search query that will be used by it. As we saw in the previous sections, the query is created using the OSF Query Builder. Then you have to save it using that same Query Builder. Once the search profile is saved, it will appear in the list of available search profiles as we will discover in the section below.

Creating & Configuring a Search Profile Block
The see the list of all available search profile, you have to click the top menu item. Then you have the click the  link under the   section. The  page does list all the search profiles you saved using the OSF Query Builder. From that page, you can create new search profiles using the  link. This link will redirect you to the OSF Query Builder page.

If you click the  link of one of the search profile, you will be be able to edit some information about that search profile. There are three main pieces of information in a search profile:
 * 1) This is the name of the search profile that appears in the Drupal user interfaces
 * 2) This is the description of the search profile
 * 3) This is the JSON object of the Search query that as been generated by the Query Builder. You can change that query directly in that box. But take care of what you are doing since it could break the search query.
 * 1) This is the description of the search profile
 * 2) This is the JSON object of the Search query that as been generated by the Query Builder. You can change that query directly in that box. But take care of what you are doing since it could break the search query.
 * 1) This is the JSON object of the Search query that as been generated by the Query Builder. You can change that query directly in that box. But take care of what you are doing since it could break the search query.

Positioning the Search Profile Block
Now that we have created a search profile, the last step is to add this search profile to a block, and then to position that block on the Drupal portal. To add a search profile as a block, you have to click the  top menu item. Then you have to click the  link. Then you have to click the. This will will redirect you to the page that you will use to configure how the search profile will be embeded in a new block. This page will let you create a new block that will embed a search profile. There are several settings that can be configured to make sure the search profile block behave as expected. Here are the different setting options that are available to you: Once you are done configuring the new search profile block, you can click the  button to save that new search profile block. Then you will be redirected to the list of available blocks of the portal. You can position the new block using the positioning drop-down box. Once you positioned the block, it will re-appear in the section you selected. At that point, you have to make sure to save that new positioning by clicking the  button. Finally, if you got to a Drupal page where the block should appear, you will see it appearing and displaying the results of the search query:
 * 1) This is unique Drupal identifier. It should be defined using alpha numeric characters and underscores
 * 2) This is the description of the block that will be created
 * 3) This is the title of the block that will be created
 * 4) This is the search profile you want to embed in that block. The search profiles listed in that list are the ones that have been created and saved by the OSF QueryBuilder module
 * 5) If this option is checked, it means that the block will try to use the context where the block was positioned to generate the search keywords. Here are the steps that will be performed
 * 6) Will check if topics are related to the page where the block appears. Topics can be added using the   hook.
 * 7) If there are more than one topic, they will be  ed
 * 8) If no topics are found, then the title of the page will be used as the search keywords
 * 9) This is the number of results to return in the block
 * 10) Two output types are possible:
 * 11) With this option, the results will be displayed as a list of links within the block
 * 12) With this option, the results will be fully themed search results. Also, if filter blocks are defined for the OSF Search API module, then they will appear in the page as well except if their blocks have been configured such that they doesn't appear on these specific pages
 * 13) This is an option search keyword that you can define for the query. This is optional and can remain blank
 * 14) Specifies if you want to hide the block if no results were found
 * 15) These are the block settings that let you position the block in the portal
 * 16) These are the normal block visibility settings that you can use to make the block visible in different places on the portal and to different users
 * 1) Two output types are possible:
 * 2) With this option, the results will be displayed as a list of links within the block
 * 3) With this option, the results will be fully themed search results. Also, if filter blocks are defined for the OSF Search API module, then they will appear in the page as well except if their blocks have been configured such that they doesn't appear on these specific pages
 * 4) This is an option search keyword that you can define for the query. This is optional and can remain blank
 * 5) Specifies if you want to hide the block if no results were found
 * 6) These are the block settings that let you position the block in the portal
 * 7) These are the normal block visibility settings that you can use to make the block visible in different places on the portal and to different users
 * 1) This is an option search keyword that you can define for the query. This is optional and can remain blank
 * 2) Specifies if you want to hide the block if no results were found
 * 3) These are the block settings that let you position the block in the portal
 * 4) These are the normal block visibility settings that you can use to make the block visible in different places on the portal and to different users
 * 1) These are the block settings that let you position the block in the portal
 * 2) These are the normal block visibility settings that you can use to make the block visible in different places on the portal and to different users
 * 1) These are the normal block visibility settings that you can use to make the block visible in different places on the portal and to different users