addedValues Plugin

...Powerful Free! Database Expansion for Manila
logoBottle:

(1 or more words)


Get tropes here!
Click to see internals
Report bug


Imperia Winter Regatta

sitepic_iwr.jpg:
Viewable with Any Browser

Members
Join Now
Login

addedValueMacros.search

Syntax

{addedValueMacros.search(formID,reportID="", sortedBy="", sortDirection="", flResultsPage=false, flSuppressForm=false, flFormFollowsHits=false, flRetainPostargs=true)}

Examples

{addedValueMacros.search("myFirstSearch","myFirstReport")}  
{addedValueMacros.search("siteSearch","Your Search Results", flresultsPage:true)}

Semantics

This macro generates a forms which allow users to perform searches. It accepts and validates their submission according to the way the form was defined, then generates a query to perform a search. The query generates a hit list (possibly empty) in the same way as the addedValueMacros.query does, possibly sorting the hits by the values of the sortedBy variable and passing it to the specified report. The report handles all aspects of pagination and next and previous linkage according to its definition. A value of sortdirection = "reverse" inverts the normal order of processing, all other values leave it unchanged.

Search handles submissions from the form itself, there are no other macros involved (this is different to how the metadata plugins does things). There are two ways to handle the output from the search macro. The first, returns it as a result of the macro; the second redirects it to another page. In the first mode, search resembles most other macros that generate a string response.

In the second mode where flResultsPage = true, reportID is the Manila shortcut of the page where the results are to be displayed. That page MUST contain another call to search, and in that call flResultsPage must be false, and the value of ReportID must be a report identifier.

Output of the macro after a submission can include a form, allowing the user to refine the search, or not (depends on the value of flSuppressForm), preceding or following the hit results (flFormFollowsHits), pre-filled with the current search values or not (flRetainPostargs). These settings are ignored if the output is redirected to another page.

If a form has 3 fields from 3 variables called X, Y and Z and the user provides values for all 3 (a, b and c respectively), the resulting query looks for candidate messages (members, gems or shortcuts) (hits) that satisfy all 3 conditions - the intersection -

X = "a" AND Y = "b" AND Z = "c"

If in the form layout, one variable shadows another, the query will contain an OR term, so if the variable V shadows Z in the above example, the query becomes

X = "a" AND Y = "b" AND (Z = "c" OR V = "c")

One common use for this technique is to search on subject,. with body shadowing subject. The form has one form element, but the search is made thru 2 indexes.

Searches of text variables can be beginswith searches if the user entry ends with *; that is if the user entered a* into field X, the query becomes
X beginsWith "a"

See also