The Metadata Plugin Metadata Management for Manila

Site last updated 2/24/2006; 12:33:21 PM

Home Why Features FAQ Updates Documentation Download Developers Bugs Feedback Discuss Planned Features				query() Macro Here is the parameter list (note that only the first two parameters are required): metaDataMacros.query (metaname,metavalue,sortBy:"score", header:"<ul>",footer:"</ul>", beforeItem:"<li>",afterItem:"</li>", maxItems:nil,includeSelf:"includeself", sortDirection:"", constrainBy:"",dateformat:"",adrFormatter:@metaDataSuite.keyIndex.qry_formatResults,msgNum:nil,operator="equalTo",msgReaderURL:"",storyReaderURL:"") Parameter Default Description Notes metaname the name of the meta type you wish to query metavalue the value of the meta type you wish to query --related-- is a special value, see below sortBy score which meta type to sort the results by header <ul> the header for the list of results may contain macros* footer </ul> the footer for the list of results may contain macros* beforeItem <li> the text to insert before each result item may contain macros* afterItem </li> the text to insert after each result item may contain macros* maxItems the maximum number of items to return includeSelf includeself whether to include the page containing the query macro in the results list (if it matches) May be a msgNum. The msgNum is then excluded from the result set, even when the query macro is called via the includeMessage macro. sortDirection which direction to sort the results by set to reverseSort to reverse sort order constrainBy provides filtering for results syntax: metaname=metavalue or metaname!=metavalue dateformat if a date field is included in the results, how to format it shortstring, abbrevstring, or longstring adrFormatter @metaDataSuite .keyIndex. qry_formatResults address of the formatter that processes the results You could write your own. msgNum nil optional Sometimes needed for newsitems and included pages operator equalTo optional the Attribute Search Engine operator you wish to pass to the query (see Date Range Searching, below) msgReaderURL optional Advanced feature, provides base URL for msgReader results storyReaderURL nil optional Advanced feature, provides base URL for storyReader results *Macros without parameters, that is, like {clock.now())} Setting metavalue to --related-- means "for the value of the meta type I used in the metaname parameter, use whatever value is set for that meta type on this page." You don't have to set the adrFormatter parameter unless you've written your own formatter. If this macro isn't returning anything from within a news item and you think it should be returning something, set the msgNum parameter to the msgNum of the news item. Here's an example of all the pages on this site that contain the keyword 'metadata'. I've included the postTime and member built-in meta types in the beforeItem and afterItem parameters. Here's the macro verbatim, then the macro results beneath: {metadatamacros.query("keywords","metadata","postTime", "<table border='1'><tr><th>postTime</th><th>Page</th><th>member</th></tr>", "</table>","<tr><td>\{-postTime}</td><td>","</td><td>\{member}</td></tr>")} [Macro error: Internal database error: attempted to read a free block. Try to Save a Copy and relaunch with the new database.] Those of you with sharp eyes will wonder why we used {-postTime} instead of {postTime} when we want to display the built-in meta type postTime. It turns out that postTime gets evaluated before the Metadata Plugin even sees it, which results in the postTime of the page containing the macro being used over and over, instead of the postTime for the messages being used. By using the hyphen, we sneak it in unscathed. Dateformat parameter can be set to shortstring, abbrevstring, or longstring. Date Range Searching The operator parameter in the query macro allows you to do date range searching. If you have a metadata field that is indexed and of type 'date' you can construct querys that search date ranges including: range, rangeInclusive, equalTo, greaterThanOrEqualTo, greatherThan, lessThan, lessThanOrEqualTo, MIN & MAX. For example, supppose you have a metaData field called requestDate of type date and you wanted to find all messages that had a requestDate between 05/01/03 and 06/31/03. Construct a call to query using parameters as needed and then pass 1) metavalue as {"05/01/03", "06/310/03"} and 2) pass operator as operator:"rangeInclusive" at the end of the query parameter list. Other Notes Because of the way Frontier tables sort, sorts are case-sensitive. If you want to make sorts case-insensitive, go to metaDataSuite.keyIndex.qry_formatResults and change the line item^ = metavalRetrieved to read item^ = string.upper(metavalRetrieved) Note that there will be a speed penalty for doing this, since every search match must be converted to uppercase. For details on the constrainBy parameter, see The showIndex() macro documentation. David Bayly has put together a graphical front end for the query macro. You can view it by clicking Query Builder on the Manage Meta Types page. This is handy for tweaking parameters to the query macro to get them just right. Here's what the query builder interface looks like: Comments...