Use the [Search] context with [founditems] to easily retrieve records from your databases.
numero = 69[search Criteria][founditems]Search results[/founditems][/search]It really is that simple. You may specify any search criteria, and put as many [Search] contexts into a template as you want. You may 'nest' them inside of each other to create relational searches among multiple databases. Basic example:
[search db=xx.db&eqCITYdata=Chicago]Your search found [numfound] items[founditems]<img src="[Picture]">[Name], [Address], [City][/founditems][shownext]previous/current/next page links go here[/shownext][/search]To display your results (using simple fieldname tags), note that you must place a [founditems]...[/founditems] context inside the [search] context. [founditems] will loop through the matching records. In addition to [founditems], three other special tags are valid within the search (but not normally used within the [founditems] portion): [numfound] will report how many records matched your criteria, and [shownext] [/shownext] will manage the links for additional pages of found items. [replacefounditems] [/replacefounditems] will replace specified fields with new values as each matching record is found.See Search Criteria for a summary of elements you can use here.See [founditems] for more details.See [shownext] for details on how to create your additional page links.See [replacefounditems] for instructions.SQL/ODBC Note: To search through an ODBC-compliant database, use the [SQL] context, not [search].The following tags are available inside a [search] context:
Tag | Description |
---|---|
[NumFound] | A number indicating how many records matched the search request. |
[sum field=fieldName] | Calculates the numerical sum of all the found records, using the fieldName column. |
[avg field=fieldName] | Calculates the numerical average of all the found records, using the fieldName column. |
[min field=fieldName] | Calculates the numerical minimum of all the found records, using the fieldName column. |
[max field=fieldName] | Calculates the numerical maximum of all the found records, using the fieldName column. |
[founditems]...[/founditems] | Normally you place a [founditems] loop inside a [search], so you can display all the matching records. You can put any database field names inside the [founditems] loop to display them in the HTML. |
[replacefounditems]...[/replacefounditems] | Loops though all the found items and replaces text in each record with the specified new text. |
[shownext]...[/shownext] | Creates a list of links that let visitors see 'chunks' of search results. |
[search db=yourdatabase&CityData=Chicago&ZipCodeSumm=t&ZipCodeSort=1&max=25&startat=[starthere]]Database Source (required)
db=yourdatabaseORtable=tablenameThe source of your data can be either a database (file on your server) or a table (temporary 'in line' database table that is local to the template and not part of the global database cache.)Data to look for (required)
CityData=ChicagoYou must indicate what data to search for by specifying the field to look in, and the text to look for. See the topic Search Data for how to refine this search with comparisons, partial strings, multiple fields, ranges, and a host of other options.Sort Order
LastNameSort=1Define your sort order with sort. See Sort for how to refine the sort using random, ascending, descending, no sorting, etc.Summary
ZipCodeSumm=tSummary will return just one record from each matching set of values. Use Summary to create headings and initiate subsearches. You should also sort on the field you are summarizing.Data Format
DeadlineType=dateClassTimeType=timeInventoryType=numUnless otherwise specified, data will be treated alphabetically. This would cause 10 to appear before 2, and 11/30/2008 to appear before 02/28/2008. This applies to both sorting and to finding data using ranges, greater than, less than, etc. (In the case of numbers of fixed length, such as zip codes and phone numbers, they will sort properly alphabetically anyway, so there's no need to specify that field as a number.)Maximum to display on each page
max=25startat=76Contrary to what this looks like, maximum only specifies how many results to display per page. The search will still find all the records you ask for, but when used with the [ShowNext] context to manage the links to more records, max=number and startat=beginning record of set will handle the proper sets displayed per page. See topic [ShowNext] for details.
eqStateData=New York&geCountyPopData=20000Required MatchAdd rq to the end to require the data be found. Otherwise, in the above example you would get other states with counties of over 20,000 population, and all New York counties, not just the big ones. Using rq makes this an AND comparison.
eqStateDatarq=New York&gecountiesDatarq=20Sometimes you want to match one field and another field at the same time -- this if often called "anding fields together". Examples are "Find all people whose first name is Grant and last name is Hulbert" or perhaps "Find all houses that have more than 5 bedrooms and a fireplace and 2 bathrooms".By default, if you do not specify certain fields are required to match, they are "or-ed" together, which in the above examples would read like "Find all people whose first name is Grant or last name is Hulbert" or perhaps "Find all houses that have more than 5 bedrooms or a fireplace or 2 bathrooms".Important: WebDNA automatically 'ranks' the best-match results to the top of the list of found items. In the "or-ed" example above, all the houses that have more than 5 bedrooms and a fireplace and 2 bathrooms are shown at the top of the list. Houses that match 2 out of the 3 criteria are listed just below those, and finally houses that only match one of the criteria are listed last. You can override this standard ranking by forcing a different sort order.
typically "and" will find fewer matches in a database, because it is more restrictive -- the chances of finding a house that matches all 3 criteria simultaneously is far lower than finding a house that matches any one of the criterion individually.
To require particular fields to match during a search, put the letters "rq" after the data specifier, as in the following examples:FirstName is Grant and LastName is Hulbert | eqFirstNamedatarq=Grant&eqLastNamedatarq=Hulbert |
Bedrooms > 5 and fireplace is True and Bathrooms is 2 | grBedsdatarq=5&eqFireplacedatarq=T&eqBathsdatarq=2 |
You can make all fields required in one simple step by putting "AllReqd=T" into the form.
The results file would contain a [founditems] loop that fills with all the matching records, and the resulting HTML would be sent back to the browser.you can also embed a [search] context in a template. Any browser accessing that HTML page (no special commands required - just link to the page) will see the 'live' search results. It might look like the following
<BODY>Here's an embedded search:<br>[search db=People.db&eqFirstNameDatarq=Grant&eqLastNamedatarq=Hulbert][founditems][FirstName], [Address], [City], [State], [Zip]<br>[/founditems][/search]</BODY>Search one field two different waysSearch two fields at onceBoth of these conditions are handled by grouping fields and it warrants its own section. Please refer to "Searching multiple fields" below.ComparisonsYou tell WebDNA how to compare by putting the two-letter comparison code in front. For instance, using gr means "Field value must be 'greater than' your search word"
grCountyPopData=20000
eq | equal to |
ne | not equal to |
gr | greater than. |
ge | greater than or equal to |
ls | less than |
le | less than or equal to |
rn | range. Specify two values separated by spaces (or any other delimiter specified by wbrk; i.e., ...&wbrk=,&...). The values may be dates, numbers, or text. If date, time or number, you must specify what type of data by using fieldnametype=xxx (where xxx is num, date or time).Example: rnBirthdaydata=02/28/2008 08/31/2008&Birthdaytype=date Note: When specifying a range, the smaller value must precede the larger value, i.e. rnZipCodedata=92069 93090, not rnZipCodedata=93090 92069. |
mr | minimum range value: if no maximum then ge is used instead |
mx | maximum range value: if no minimum than le is used instead |
cl | close to (numeric only). clZipCodedata=92069&clZipCodedata=10 finds all records whose ZipCode field is within 10 of 92069 (92059 - 92079) |
bw | begins with |
ew | ends with (from 8.6) |
ws | Interpret the words as a single string to be matched (including spaces etc.) This lets you find entire phrases, like "Joe enjoys butter" only if those 3 words are next to each other in that order, including spaces (unlike wa and wo, below) |
wa | Separate the words and "and" them together (all must match). Searching for 3 words using wa will match only if all 3 are in the field, but not necessarily next to each other. |
wo | Separate the words and "or" them together (at least one must match - default option for text). Search for 3 words using wo will match if any one of them matches. |
wn | word not equal - none of the words match text in the specified field |
Word breaks: Use Wbrk to define what constitutes a word. By default, a space is a word delimiter, but you can define your own delimiter(s) using wbrk; example: fieldnameWbrk=,-;. | |
Word position in field: Use Word to define where you want the word to be found. Example: fieldnameWord=ww | |
ss | SubString match. Looks for word anywhere, even inside larger words. Finds "I like typographic conventions" and "This is a graphic" and "Graphical user interfaces are cool." |
ww | Whole Word match. Looks for whole word; ignores if found inside a larger word. Finds "This is a graphic" |
sw | Start of Word. Looks for word at the beginning of words. Finds "This is a graphic" and "Graphical user interfaces are cool." |
Case sensitivity: Conducts case sensitive searches. Examples: fieldnameCase=t AllCase=t (apply to all fields) | |
Finding Empty Fields and Find All[blank] is a special WebDNA tag available in searches to explicitly find empty records. In practice, it is more often used to find records which are NOT empty, which is one way to "find all". Here are two popular ways to Find All: nefieldnameDatarq=[blank] nefieldnameDatarq=FindAllThe second example, of course, assumes you don't have a field value of FindAll.Alternately, you can use the form FieldNameBLNK=T, which makes it possible to use radio buttons or checkboxes to let the visitor decide how they want to search for blank fields. If you want to apply this to all the fields in your search at once, then set allBLNK=T. |
group1field=title+description+keywords&wogroup1data=BirdGroup1 becomes the name of the combined field, and is used just like a regular fieldname with the data parameter. In this case, all three fields are searched and if Bird is found in any of them, the record will be retrieved.Searching the same field in two different waysSometimes you need to compare a value two different ways, but the search parameter will only accept a fieldname once. In this case, create two group fields like this:
group1field=zipcode&group2field=zipcodeand do what you need to do in your search; for example:
negroup1datarq=08055&rngroup2datarq=08001 08099In this case, all the zip codes in one area are found, but one of them is excluded (perhaps the zip code that is currently being highlighted elsewhere on the page.)
When assigning groups, you must name them sequentially, without skipping numbers.
If you plan to work on several groups, the groupfields definitions must be placed at the beginning of the search string. For instancegroup1field=title+description&wogroup1data=Bird&group2field=title+keyword&wogroup2data=Birdhas to be written in this order:group1field=title+description&group2field=title+keyword&wogroup1data=Bird&wogroup2data=Bird
StateSort=1&CitySort=2(Cities appear alphabetically, grouped by State)
StateSort=1&deCityPopSort=2&CityPopType=num&CitySort=3(Cities appear in order of largest first, grouped by State. In the rare case that two cities have the exact same population, then they would be sorted alphabetically. Note the use of type=num to tell WebDNA to treat that field numerically. This is important. )
You cannot skip a number in the sorting hierarchy.
SummariesSee the Summary section for ways to use Sorting and Summaries togetheras | ascending (the default, if nothing specified) |
de | descending |
ra | random |
Maintain randomness: Sometimes you need a series of random sorts to always present the exact same 'random' order. You can force the randomizer to return items in the same order if you add another parameter "RandSeed=879" (or any other integer number). This is most helpful when you use [ShowNext] and you need each successive set of links to predictably return the results in the same order.RandSeed=integer | |
No sorting at all: Results are displayed in exactly the same order they appear in the database file.Rank=off |
[search db=yourdatabase.db&neStatedata=[blank]&StateSort=1&StateSumm=t][founditems]<b>[State]</b> <p>[search db=yourdatabase.db&eqStatedata=[state]&CitySort=1][founditems][city], population [citypop] <br>[/founditems][/search][/founditems][/search]When this plays out on the server, WebDNA will sort by state, but only return the first record of each state. As it finds each one, it displays the state name in bold, inserts a paragraph tag, then performs a new search for that state's cities (inserting the known state name in the [search]), then lists the cites with a line break tag after each one. Then it goes to the next state and repeats the process until the last state is taken care of.Counting Unique ValuesWorking from the above example, maybe all we want is to know how many cites are in each state. We will use almost the same code to determine this, but won't display the cites at all.
[search db=yourdatabase.db&neStatedata=[blank]&StateSort=1&StateSumm=t][founditems]<b>[State]</b> [search db=yourdatabase.db&eqStatedata=[state]]has [numfound] cities.<p>[/search][/founditems][/search]This time, WebDNA finds one record for each state as before, but this time, the second search doesn't care about sorting the cities, nor do we need the [foundItems] to display them. However, WebDNA still went to all the effort to find the cities that go with each state, and we can use [numfound] to get that value.Want to grab the population of each state, by adding the populations of the cities within? No problem with WebDNA. It is easy using the [math] context.
You can define your own custom list of word break characters with . By adding Descriptionwbrk=.,- to your search causes user-entered text surrounded by those characters in the HTML form field Description to be considered as individual words.
[search db=somebase.db&woDescriptiondata=graph&Descriptionword=sw&]
word | |
---|---|
ss | Descriptionword=ss looks for "graphic" and finds it anywhere inside phrases such as: "I like typographic conventions" and "This is a graphic" and "Graphical user interfaces are cool." |
ww | Descriptionword=ww looks for "graphic" and will not find it inside phrases such as: "I like typographic conventions". It will be found inside "This is a graphic." |
sw | Descriptionword=sw looks for "graphic" at the beginning of words, like "This is a graphic" and "Graphical user interfaces are good", but will not find it inside "I like typographic conventions." |
woDESCRIPTIONdatarq=2&DESCRIPTIONword=WW&DESCRIPTIONfbrk=[url],[/url]in the search string would not find a result if the field data is "400.2", whereas it would if the FBRK option was not specified.
Basically, "wbrk" tells WebDNA how to break up the values you pass in your search context, while "fbrk" tells WebDNA how to break up the values stored in the database.
[search Criteria]
[founditems]Search results[/founditems]
[/search]
[search db=xx.db&eqCITYdata=Chicago]
Your search found [numfound] items
[founditems]
<img src="[Picture]">
[Name], [Address], [City]
[/founditems]
[shownext]
previous/current/next page links go here
[/shownext]
[/search]
Tag | Description |
---|---|
[NumFound] | A number indicating how many records matched the search request. |
[sum field=fieldName] | Calculates the numerical sum of all the found records, using the fieldName column. |
[avg field=fieldName] | Calculates the numerical average of all the found records, using the fieldName column. |
[min field=fieldName] | Calculates the numerical minimum of all the found records, using the fieldName column. |
[max field=fieldName] | Calculates the numerical maximum of all the found records, using the fieldName column. |
[founditems]...[/founditems] | Normally you place a [founditems] loop inside a [search], so you can display all the matching records. You can put any database field names inside the [founditems] loop to display them in the HTML. |
[replacefounditems]...[/replacefounditems] | Loops though all the found items and replaces text in each record with the specified new text. |
[shownext]...[/shownext] | Creates a list of links that let visitors see 'chunks' of search results. |
[search db=yourdatabase&CityData=Chicago&
ZipCodeSumm=t&ZipCodeSort=1&max=25&startat=[starthere]]
db=yourdatabase
OR
table=tablename
CityData=Chicago
LastNameSort=1
ZipCodeSumm=t
DeadlineType=date
ClassTimeType=time
InventoryType=num
max=25
startat=76
eqStateData=New York&geCountyPopData=20000
eqStateDatarq=New York&gecountiesDatarq=20
typically "and" will find fewer matches in a database, because it is more restrictive -- the chances of finding a house that matches all 3 criteria simultaneously is far lower than finding a house that matches any one of the criterion individually.
FirstName is Grant and LastName is Hulbert | eqFirstNamedatarq=Grant&eqLastNamedatarq=Hulbert |
Bedrooms > 5 and fireplace is True and Bathrooms is 2 | grBedsdatarq=5&eqFireplacedatarq=T&eqBathsdatarq=2 |
You can make all fields required in one simple step by putting "AllReqd=T" into the form.
you can also embed a [search] context in a template. Any browser accessing that HTML page (no special commands required - just link to the page) will see the 'live' search results. It might look like the following
<BODY>
Here's an embedded search:<br>
[search db=People.db&eqFirstNameDatarq=Grant&eqLastNamedatarq=Hulbert]
[founditems]
[FirstName], [Address], [City], [State], [Zip]<br>
[/founditems]
[/search]
</BODY>
grCountyPopData=20000
eq | equal to |
ne | not equal to |
gr | greater than. |
ge | greater than or equal to |
ls | less than |
le | less than or equal to |
rn | range. Specify two values separated by spaces (or any other delimiter specified by wbrk; i.e., ...&wbrk=,&...). The values may be dates, numbers, or text. If date, time or number, you must specify what type of data by using fieldnametype=xxx (where xxx is num, date or time). Example: rnBirthdaydata=02/28/2008 08/31/2008&Birthdaytype=date Note: When specifying a range, the smaller value must precede the larger value, i.e. rnZipCodedata=92069 93090, not rnZipCodedata=93090 92069. |
mr | minimum range value: if no maximum then ge is used instead |
mx | maximum range value: if no minimum than le is used instead |
cl | close to (numeric only). clZipCodedata=92069&clZipCodedata=10 finds all records whose ZipCode field is within 10 of 92069 (92059 - 92079) |
bw | begins with |
ew | ends with (from 8.6) |
ws | Interpret the words as a single string to be matched (including spaces etc.) This lets you find entire phrases, like "Joe enjoys butter" only if those 3 words are next to each other in that order, including spaces (unlike wa and wo, below) |
wa | Separate the words and "and" them together (all must match). Searching for 3 words using wa will match only if all 3 are in the field, but not necessarily next to each other. |
wo | Separate the words and "or" them together (at least one must match - default option for text). Search for 3 words using wo will match if any one of them matches. |
wn | word not equal - none of the words match text in the specified field |
Word breaks: Use Wbrk to define what constitutes a word. By default, a space is a word delimiter, but you can define your own delimiter(s) using wbrk; example: fieldnameWbrk=,-;. | |
Word position in field: Use Word to define where you want the word to be found. Example: fieldnameWord=ww | |
ss | SubString match. Looks for word anywhere, even inside larger words. Finds "I like typographic conventions" and "This is a graphic" and "Graphical user interfaces are cool." |
ww | Whole Word match. Looks for whole word; ignores if found inside a larger word. Finds "This is a graphic" |
sw | Start of Word. Looks for word at the beginning of words. Finds "This is a graphic" and "Graphical user interfaces are cool." |
Case sensitivity: Conducts case sensitive searches. Examples: fieldnameCase=t AllCase=t (apply to all fields) | |
Finding Empty Fields and Find All [blank] is a special WebDNA tag available in searches to explicitly find empty records. In practice, it is more often used to find records which are NOT empty, which is one way to "find all". Here are two popular ways to Find All: nefieldnameDatarq=[blank] nefieldnameDatarq=FindAll The second example, of course, assumes you don't have a field value of FindAll. Alternately, you can use the form FieldNameBLNK=T, which makes it possible to use radio buttons or checkboxes to let the visitor decide how they want to search for blank fields. If you want to apply this to all the fields in your search at once, then set allBLNK=T. |
group1field=title+description+keywords&wogroup1data=Bird
group1field=zipcode&group2field=zipcode
negroup1datarq=08055&rngroup2datarq=08001 08099
When assigning groups, you must name them sequentially, without skipping numbers.
If you plan to work on several groups, the groupfields definitions must be placed at the beginning of the search string. For instance
group1field=title+description&wogroup1data=Bird&group2field=title+keyword&wogroup2data=Bird
has to be written in this order:
group1field=title+description&group2field=title+keyword&wogroup1data=Bird&wogroup2data=Bird
StateSort=1&CitySort=2
StateSort=1&deCityPopSort=2&CityPopType=num&CitySort=3
You cannot skip a number in the sorting hierarchy.
as | ascending (the default, if nothing specified) |
de | descending |
ra | random |
Maintain randomness: Sometimes you need a series of random sorts to always present the exact same 'random' order. You can force the randomizer to return items in the same order if you add another parameter "RandSeed=879" (or any other integer number). This is most helpful when you use [shownext] and you need each successive set of links to predictably return the results in the same order. RandSeed=integer | |
No sorting at all: Results are displayed in exactly the same order they appear in the database file. Rank=off |
[search db=yourdatabase.db&neStatedata=[blank]&StateSort=1&StateSumm=t]
[founditems]
<b>[State]</b> <p>
[search db=yourdatabase.db&eqStatedata=[state]&CitySort=1]
[founditems]
[city], population [citypop] <br>
[/founditems]
[/search]
[/founditems]
[/search]
[search db=yourdatabase.db&neStatedata=[blank]&StateSort=1&StateSumm=t]
[founditems]
<b>[State]</b>
[search db=yourdatabase.db&eqStatedata=[state]]
has [numfound] cities.<p>
[/search]
[/founditems]
[/search]
You can define your own custom list of word break characters with . By adding Descriptionwbrk=.,- to your search causes user-entered text surrounded by those characters in the HTML form field Description to be considered as individual words.
[search db=somebase.db&woDescriptiondata=graph&Descriptionword=sw&]
word | |
---|---|
ss | Descriptionword=ss looks for "graphic" and finds it anywhere inside phrases such as: "I like typographic conventions" and "This is a graphic" and "Graphical user interfaces are cool." |
ww | Descriptionword=ww looks for "graphic" and will not find it inside phrases such as: "I like typographic conventions". It will be found inside "This is a graphic." |
sw | Descriptionword=sw looks for "graphic" at the beginning of words, like "This is a graphic" and "Graphical user interfaces are good", but will not find it inside "I like typographic conventions." |
woDESCRIPTIONdatarq=2&DESCRIPTIONword=WW&DESCRIPTIONfbrk=[url],[/url]
Basically, "wbrk" tells WebDNA how to break up the values you pass in your search context, while "fbrk" tells WebDNA how to break up the values stored in the database.
Terry WilsonDOWNLOAD WEBDNA NOW!
A list of user-submitted tips ...
WebDNA reference...
Download WebDNA ApplicationsWebDNA applications...
Technical Change HistoryThis Technical Change History provides a reverse chronological list of WebDNA changes...
WebDNA LibrariesA list of available libraries for WebDNA...
WebDNA ModulesA list of the currently available modules...
Extracts a portion of the text (also known as substring or Mid$)...
[middle]Extracts middle portion of the text between any two strings...
[listfiles]When listing files...
[uppercase]Changes all lower case letters to upper case...
[createfolder]Create an empty folder on your webspace...
[SQLconnect]Opens and persists a 'named' connection to a SQL server...