Creating query strings

Manual: v5 - Pages 256-258, v6 - PortWeb manual Pages 9-14

Does PortWeb demand a strict layout for its parameters? No, but if you look at the links produced by PortWeb's %next% macro you'll see it uses a consistent layout to product 'GET' method form URLs which it is sensible to follow (though you may omit the optional parameters). Note that the parameter order they indicate is slightly different from that described in the manual. Before reading this article you would if you have some understanding of the HTML Form methods 'POST' & 'GET' - both have implications for your project but these are beyond the scope of this article.

First some terminology that we'll use in this article:

A Command is the description of the action your carry out via PortWeb, e.g. query, add The Command is also given as first the parameter (qv) in the query string.
A Parameter is one of a list or mandatory or optional arguments making up a Command (qv), e.g. &catalog, &template.
Parameters are formed of Name and Value pairs. With the exception of the quickfind parameter, the first parameter in the query string (i.e. the Command) does not take a Value and is preceded by a ? instead of an &, i.e. ?remove not &remove. Otherwise parameters are used in the manner &Name=Value. (See the note at the bottom of page on how the quickfind Command differs in this regard).
Confusingly, the manual describes an Argument as the term(s) to be checked in the query. There may be up to 10 arguments in a query (as opposed to 5 in the app's Find dialog), e.g. Keyword matches dog OR description contains dog AND Horizontal Resolution is less than 300. The Argument value is usually the main unknown furnished by the user.

The result is "../PortWeb.dll?[Command Parameter][Parameter][Parameter] etc." or in other words...
"../PortWeb.dll?command&name=value&name=value etc."

The general order is (optional parameters in blue):

[Command] (query, add, show etc with no preceding &)
catalog
template
field
op
value
sorton
ascending
offset

... and if we add a second argument...

join
field
op
value

... and so on up to a maximum of 10 Arguments (including the first one) just as in the client's Find dialog. This makes sense as via PortWeb you are effectively simulating a Find sent from a client to a Catalogue. When using several Arguments, a good cross-check is to check you have that the number of join parameters is one less than the number of Arguments.

Case sensitivity. The casing of the DLL name (e.g. portweb.dll, PortWeb.dll, Portweb.DLL), the commands (query, QuickFind, etc.) and parameters (catalog, template, join) and parameter values (myTemplate, dog, 2.45) are all case insensitive. All parameter values appear to also be case insensitive but with one important exception. This is the use of the field names as values for the 'field' and 'sorton' parameters. Thus you must use 'Keywords' but not 'keywords'. It is therefore a good idea to use the capitalisation used in the client UI; for field and op values, use the client find dialog drop-downs as a guide.

Spaces in parameter values. Note that in the 'GET' method URL queries such as created by PortWeb's macros (e.g. %next%), spaces are replaced by a plus (+) so that the string 'starts with' becomes 'starts+with'. If creating queries in scripts you must remember to make this alteration yourself. You don't need to worry about this nuance unless you are actually creating the query strings via scripting as opposed to via HTML as below.

Command - GET vs. POST method
Depending on the submission Method used, there is a difference in the way the Command is specified when using <FORM> and <INPUT> tags (as opposed to as a pre-coded URL string). With the GET Method the Form's action and command are specified separately:

<form action="../scripts/PortWeb.dll?" method="get">
<input type="hidden" name="query" value="">
etc.

With the POST Method the command is appended to the Action string:

<form action="../scripts/PortWeb.dll?query" method="post">
<input type="hidden" name="query" value="">
etc.

The same holds true for other commands such as Add, Remove, etc. This is a subtle difference which can easily catch you out especially if you change from the GET to the POST Method during the course of a project by just amending code. Using the POST style of code and changing the Method to GET will cause your query to fail. Conversely, using the GET style if you simply change the Method to POST the code will work. So it is recommended that you use the GET-style syntax throughout the templates if you think you may need to change the form submission Method at a later date.

Now let's look at the individual parameters (see also the manual pages 256-8):

catalog
This is important as it tells PortWeb which of the catalogues it is serving to interrogate. Even if only one Catalogue is being served via PortWeb this Parameter is still mandatory. The name you use is not the FDB's filename but the 'alias' you gave the Catalogue when serving it via the adminshow page. If you've forgotten it, just open the adminshow page or open the PortWeb.ini - the alias is the first work on the line before the path to the FDB. Although it is not documented it is suggested you do not attempt to use PortWeb 'Alias' values that have spaces in them; in this regard see also template names (below).

template
This is optional, although if you don't supply a template Parameter you'll get a default thumbnail/filename 4-up result page. In reality, for a decent PortWeb site you are going to want to create your own templates - in fact more than one, unless you're just viewing results. Don't forget that any template you call by this method must be in the Catalogue given in the preceding catalog Parameter. If you've forgotten the exact name of the template, open a Catalogue in the client program and click Ctrl+H/Cmd+H and you will have a list of the Catalogue's stored templates named as you need to use them here. Although Portfolio allows you to save templates with spaces in the name these will not work with PortWeb (though they will work for static web page export), so ensure none of your templates have spaces in them.

field
This is the name of the field whose data you wish to search against. The actual field name must be cased exactly as in the client - use the client's Find dialog to check capitalisation and spaces in names. Note - RID is not a field and can't be used in queries, as explained here.

op
This Parameter - the 'operator' - is the most easily accidentally omitted when writing queries via code. Failure to include it will cause a 'no matching records result' result to be returned by PortWeb. The default usage - for strings anyway - tends to be "starts with". Ignore the comments on page 257 of the manual about this Parameter as they appear to be incomplete and in some cases incorrect. The best way to check compatibility of field type with op type, and op casing/spelling is to use the client's Find dialog - select the field you'll use (or one of the same type) in the Find dialog and the op drop-down will only list of compatible op types available for use. Operators and their meanings are discussed in further detail in a separate article.

value
This is actual value you will search against and will probably be supplied via the user interface in a text box or the like. You may well wish to apply some scripting to the user input to check valid submissions are being made.

sorton
The name of the field the results are to be sorted on. This includes most built-in and custom fields with a few exceptions. If this Parameter is not passed, the results use client's built-in default sort on the Cataloged field which is none too intuitive a sort format for most users - it is the order images were added, i.e. in order of RID. Do give a little thought to your choice here as it can aid usability. If in doubt, Filename is probably the best choice.

ascending
This takes a '0' value for ascending order, '1' for descending. It's that simple. If omitted the default value is ascending. It appears from testing that this feature is actually implemented in reverse, i.e. 1 = ascending and 0 = descending so make sure you check this in your own code when testing (I'm not sure if this is a documentation error, a global bug or only affects some query types - so test before deployment!).

offset
You won't tend to use this in your initial query. The value given indicates the number of records from the (as-sorted) returned recordset that have been viewed already. To hand code the offset you must know the number of items the template used will display per returned page (# items = template rows x columns). Thus a 2 x 2 page will show 4 records and the offset for page number 2 is 4 as items 1-4 have already been displayed. Page 2 will then start with sorted record 5, displaying items 5-8. The sort referred to is, of course, the one applied in the 'sorton' parameter' or else the default. This Parameter comes into it's own when you are returning more than one page of records. Good examples to study are the link generated by the template macros %previous% and %next%. For consistency, you can put offset="0" for the first page, i.e. no offset! If you are going to be manipulating the query string in client or server side scripting you may well wish to include the offset parameter from outset.

join
If you use more than one Argument in your query, you must insert a join Parameter to link the second or subsequent Argument. There should thus always by one less join Parameter then the total number of Arguments (good check when de-bugging). Conversely, do not use this Parameter if you are only using one Argument in your query.

Below is listed specimen HTML code that will create a text box and submit button. The word typed in the text box will be used to do a "Starts With" Find against the Keywords field in the Catalogue whose PortWeb alias is given. The matching records will be returned using the template stated - the latter's settings decide how may items are returned per page and (can) generate page lists. On each result page the results will be sorted by (for this query) the Filename, in ascending alphanumeric order. The actual value of the argument is blank until the user enters a search keyword in the text box. We also include a button so the query can be submitted to PortWeb.

... it looks like this in the browser:

This is the (URL version) query that results, when you use using a value 'man' for the Value field in the above query:
"www.mydomain.com/scripts/portweb.dll?query&catalog=newtest&template=u_show&field=Keywords&op=Starts+With&value=man&sorton=Filename&ascending=0"
(The name/value pair for the submit parameter get passed as well but you can ignore this for your purposes).

Note the capitalisation of the Parameter values where actual field names are used, e.g. Filename. The URL shown above equates to the GET method of submission and note that all Parameter values are displayed within it. as a result all the Parameter information is visible to the user in the browser's address bar. Using the 'POST' method the resulting URL seen in the browser is "www.mydomain.com/scripts/portweb.dll?query" - although the Parameters passed as name=value pairs to the server they are not displayed in the resultant URL seen in the browser's address bar.

If you use PortWeb macros in your templates to generate page links, they will create GET method URL links. If you want the more private POST method you will have to code these yourself and this will require scripting of some kind.

To see how these input fields relate to the client's Find dialog, look at this screenshot of a Find with 3 arguments:

Note the three Field/Op/Value parameters in the first argument and the four Join/Field/Op/Value parameters used by the remainder. All other parameters, such as sorton are only supplied once per query. It is the Join/Field/Op/Value parameters that vary from argument to argument. In the first argument above (the red #1), the parameters equate to this part of our HTML example:

Now, a more complicated version of the example above with an additional search Argument; the Argument is added with an 'and' join. The first argument does a 'Starts with' comparison of the user's supplied value with the Keyword field. The second Argument does a 'Less Than' match on the custom integer field 'Cost' also based on a keyword. Note that these elements would go in the above Form, between the "ascending" parameter and the submit button - i.e. before the last <input> element.

<form action="../scripts/PortWeb.dll?query" method="post">
<input type="hidden" name="catalog" value="newtest" />
<input type="hidden" name="template" value="show" />
<input type="hidden" name="field" value="Keywords" />
<input type="hidden" name="op" value="starts with" />
<input type="text" name="value" value="" />
<input type="hidden" name="sorton" value="Filename" />
<input type="hidden" name="ascending" value="0" />
<input type="hidden" name="offset" value="0" />
<input type="hidden" name="join" value="and" /> (note the join Parameter)
<input type="hidden" name="field" value="Cost" />
<input type="hidden" name="op" value="Less Than" />
<input type="text" name="value" value="" />
<input type="submit" name="Submit" value="Keyword Search" />
</form>

...which is displayed like this:

You can see that if you are providing several user-set inputs, you may also need to code HTML labels indicating what is required, e.g.:-

In the example above the and value of the join is hard-wired here but in reality you would provide a <select> field to offer an and/or choice to the user. As stated above, remember that the total number of arguments, i.e. separate search terms, may not exceed 10.

You may also wish to label the join/field/op/value HTML elements so that the individual arguments can be read or parsed, especially for debugging or reference by other scripts. For example, look at the value of the 'name=' parameter in the lines of code below:

This numbering is not essential as PortWeb splits the query data it receives into individual parameters (note: the numbering rules change in v7 NP). The first 'set' of field/op/value parameters will be used as argument #1, the next join/field/op/value is argument #2, etc. Thus the numbering is not essential for the query to be understood but rather the order the parameters are passed. Indeed, if you number the parameters but mix the 'sets', i.e. &field0="Keywords"&op2="matches"&value0="blue" etc. will not be interpreted as you might expect. Testing also seems to indicate that if you number the data sets #0 through #9 you may get unexpected results (why, I've no idea!) so I recommend numbering from #1 through #10. Notice the join is numbered for the set it is joining, i.e. the set it precedes if they are written in ascending numeric order; thus the first data set has no join argument.

The quickfind Command. It is worth noting that the quickfind Command is an exception to the above rules as the Command also acts as a Parameter. It must be placed first in the query string. It takes no ampersand (&) before it but unlike other Commands it has a value pair, e.g. dll?quickfind=chair&catalog=etc. as opposed to dll?query&catalog=etc.. This is because a quickfind query has no 'op' or 'value' parameter and is effectively a shorthand way of setting a "Keyword contains..." query such that you simply supply a search term that the quickfind Command/Parameter takes as its Value. See the manual 254-5 for more on quickfind.

Question: Creating query strings [FAQ00205.htm]
Last Update:- 01 June 2006

<< What are the max and min ...

Back to Portfolio FAQ index

Can I pass user-defined p ... >>

User-to-User Forums | Report error/typo/broken link | Request new topic | Ask a question

This FAQ is created and maintained using
Friday logo

Friday - The Automatic FAQ Maker