Overview
The Search User Item creates a search form on a custom Page. The form provides input fields visitors can use to search for people on the site. The form uses a script that executes in the visitor's browser and does not depend on any remote server, so it will work with sites published on the web and sites published on removable media.
The search facility uses a data index that GedSite creates when it makes the site. The index is loaded into the browser and all search operations are processed locally. Browsers on some devices may have limited memory available, and in those cases, the the browser may not be able to execute the search. Circumstances vary based on the number of people and the number of names in your genealogy data as well as the mix of names you have. A one-name study will typically have less unique surnames than other types of projects, for example, and that will reduce the size of the index. Sites with 75,000 or more people are using the search facility.
The Search facility relies on Javascript. If a visitor has Javascript disabled, the Search form will not appear on the page.
The Search User Item is a Content Item and does not create a page of its own. You must add it to a Page User Item or you will not see its content.
Properties
The Edit Search Item window controls the properties associated with a Search User Item including the configuration of the search form and the contents of the data index.
Title
Enter a title for the user Item. The title is not displayed as part of the search form, but the User Item must have a title to identify it in the list of User Items.
Enabled
The Enabled checkbox controls whether or not the User Item is processed when GedSite is making the site.
Max Pages
The maximum number of results that can be shown is determined by multiplying Max Pages times Items per Page.
The search results are split into sets called pages. The Max Pages property controls the maximum number of result pages. The choices are 1, 5, and 10, and the default is 5.
Items per Page
The search results are split into sets called pages. The Items per Page property controls the maximum number of results on a single result page. The choices are 10, 25, and 50, and the default is 25.
Match All Diacritics
When Match All Diacritics is checked, the Search feature will treat characters with and without diacritic marks as the same character. For example, if the visitor keys an "a" in the Surname field, the "a" will match á, à, â, ä, ã, å, and ą as well as the uppercase variations Á, À, Â, Ä, Ã, Å, and Ą. Similarly, if the visitor keys "ä" it will match all the same characters.
The Match All Diacritics feature has no effect on search processing when the method is set to "Regular Expression". See the Method property below.
Enabling the Match All Diacritics property makes it easier for visitors to find names when they do not know whether or not names include characters with diacritics.
Diacritics are sometimes called "accents", but accents are only a subset of the diacritic marks that may be part of a character. For more information about diacritics, see the Wikipedia entry.
In the table below, each row includes a set of characters that are considered equivalent. When a user enters text that includes one of the characters below, that character will match itself or any other character in the same row.
| Base Character | Equivalent Characters |
|---|---|
| A | a A á Á à À â Â ä Ä ã Ã å Å ą Ą |
| C | c C ç Ç ć Ć |
| E | e E é É è È ê Ê ë Ë ę Ę |
| I | i I í Í ì Ì î Î ï Ï |
| L | l L ł Ł |
| N | n N ñ Ñ ń Ń |
| O | o O ó Ó ò Ò ô Ô ö Ö õ Õ ø Ø |
| S | s S ś Ś |
| U | u U ú Ú ù Ù û Û ü Ü |
| Z | z Z ź Ź ż Ż |
There are several other characters that are given special treatment when Match All Diacritics is enabled. These characters are often converted from a single character to two characters. When a user enters text that includes the one or two-character versions, the search feature will match both the one and two character versions in the data.
| Base Character | One and Two Character Combinations |
|---|---|
| Æ | æ Æ ae AE |
| Œ | œ Œ oe OE |
| ß | ß ss SS |
Method
The Method pull-down menu controls the default text comparison method used by the search script, Basic or Regular Expression. Both methods treat upper- and lower-case characters the same, so a will match A and vice-versa. The two methods use different wildcard symbols. See the Search Methods section below.
Show RegEx Checkbox
The The Show RegEx Checkbox property controls whether or not the end-user can switch between the Basic and Regular Expressions search methods. When checked, a checkbox will appear on the search form and the user may check it to use a Regular Expression, or clear it to use the Basic method.
Search Methods
This section explains how the Basic search method differs from the Regular Expression search method.
On this help page, search terms are called patterns and appear like this. Data values are shown as quoted strings, "like this".
Basic Method
The Basic method uses two wildcard symbols, ? and *. ? matches any single character, and * matches any string of characters. The given pattern must match at word boundaries in the associated data field. So, for example, the pattern wood will match a surname of "Wood", but not "Atwood" or "Woodbury". The pattern wood* will match "Wood" or "Woodbury", but not "Atwood". The pattern *wood* will match "Atwood", "Wood", and "Woodbury".
Basic Method Symbols
| Symbol | Function |
|---|---|
| ? | Matches any single character
|
| * | Matches any string of characters.
|
Regular Expressions Method
The Regular Expressions method supports powerful text matching capabilities using a set of special characters to describe matching rules. By default, text fields on the search form are contains patterns, so a search for wood will match "Atwood", "Wood", "Woodbury", and more. You can make more restrictive patterns using the special characters shown in the table below.
Regular Expression Method Symbols
The following characters have a special meaning when the Search Method is set to Regular Expressions.
| Symbol | Function |
|---|---|
| . | Matches any character.
|
| * | Matches zero or more occurrences of the previous character or term.
|
| .* | Combining the two symbols above matches zero or more occurrences of any character.
|
| ^ | Matches the start of a field.
|
| $ | Matches the end of a field.
|
| \b | Matches any word boundary
|
| [abc...] | Matches any character specified between the brackets.
|
| (a|b|...) | Matches one of a set of alternatives.
|
The Example Help Text below describes some of the Special Characters available in Regular Expressions.
Help Text
If you wish to include text that explains how to use the search form, include the text and HTML in the Help Text property. When Help Text is present, a question mark icon appears on the form. Clicking the icon opens the help text in a pop-up panel. Example help text is shown below. You have my permission to copy this text, and amend it if desired, for use on your own web site. No attribution is required or expected.
Example Help Text
<h2>Basic</h2>
<p>The Basic method supports two wildcard characters, <code>?</code> and <code>*</code>. The <code>?</code> character matches any single character, and <code>*</code> matches any string of characters. The given pattern must match at word boundaries in the associated data field. So, for example, the pattern <code>wood</code> will match a surname of "Wood", but not "Atwood" or "Woodbury". The pattern <code>wood*</code> will match "Wood" or "Woodbury", but not "Atwood". The pattern <code>*wood*</code> will match "Atwood", "Wood", and "Woodbury".</p>
<h2>Regular Expressions</h2>
<p>Regular Expressions are powerful text matching facilities that use a set of special characters to describe matching rules. By default, text fields on the search form are contains filters, so a search for <code>wood</code> will match "Atwood", "Wood", "Woodbury", and more. You can make more restrictive filters by using pattern matching characters. <code>^</code> matches the beginning of the field, so to specify that a surname value must begin with "wood", enter <code>^wood</code>. <code>$</code> matches the end of the field, so to specify that a surname value must end with "wood", enter <code>wood$</code>.</p>
<p>You can use other pattern matching characters in the name fields.</p>
<ol>
<li>A period (<code>.</code>) matches any character, so a search for <code>mill.t</code> matches "Millet" and "Millit".</li>
<li>A plus sign (<code>+</code>) indicates that the last character may occur one or more times, so <code>mil+et</code> matches "Milet" and "Millet".</li>
<li>An asterisk (<code>*</code>) indicates that the last character may occur zero or more times, so <code>millet*</code> matches "Millet" and "Millett".</li>
<li>Brackets indicate alternative characters, so <code>mille[nr]</code> matches "Millen" and "Miller".</li>
<li>Parentheses indicate alternate terms, so <code>(bill|william)</code> matches "Bill" and "William".</li>
</ol>