Overview

The Search User Item is a Content Item that 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 such as CDs, DVDs, and flash drives.

You can see a working example of the search form on the Second Site demonstration site.

The search facility uses a data index that Second Site creates when it makes the site. The Search User Item includes properties to define the contents of that data index. You can manage the size of the data index by adjusting those properties. For users whose sites include more than 10,000 people, you may find it necessary to eliminate some of the data in the index to ensure that the browser is able to load the data index file.

The index includes people who are included on the site, and it also includes parents, spouses, and children who are not included on the site but whose names appear in the person page entries of other people.

The Custom Page Help page includes examples of how to use User Items.

The search facility is designed for sites with 15,000 people or less. On larger sites, the data index may be too large for the browser to load, and the search form will not operate properly as a result. However, circumstances vary based on the exact content of your site, and even if you have more than 15,000 people, you should test the feature to see if it works for you. 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.

Edit Search

The Edit Search window controls the properties associated with a Search User Item including the configuration of the search form and the contents of the data index.

Enabled

See Enabled on the User Items page.

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 indentify it in the list of User Items.

Max Pages

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.

The maximum number of results that can be shown is determined by multiplying Max Pages times Items per Page.

Default Search Method

The Default Search Method pull-down menu controls the default text comparison method used by the search script, Basic or Regular Expressions. 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.

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

SymbolFunction
? Matches any single character

Sm?th matches "Smith" and "Smyth".

* Matches any string of characters.

Wood* matches "Wood" and "Woodbury".

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.

SymbolFunction
. Matches any character.

sm.th matches "Smith" and "Smyth".

* Matches zero or more occurrences of the previous character or term.

millett* matches "Millet" and "Millett".

.* Combining the two symbols above matches zero or more occurrences of any character.

mill.* matches "Millet", "Millett", "Miller", and more.

^ Matches the start of a field.

^a matches the first "A" in "Anita".

$ Matches the end of a field.

a$ matches the last "a" in "Anita".

\b Matches any word boundary

\bwill matches "Will" in "Charles William" and "William Charles".

[abc...] Matches any character specified between the brackets.

sm[iy]th matches "Smith" and "Smyth". You may also use ranges, i.e., "[0-9]".

(a|b|...) Matches one of a set of alternatives.

(bill|william) matches "Bill" and "William". (bill|will)* matches "Bill", "Billie", "Billy", "Will", "Willy" and "William".

The Example Help Text below describes some of the Special Characters available in Regular Expressions.

Show Method Checkbox

The The Show Method 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 Regular Expressions, or clear it to use the Basic method.

Include Non-primary Names

The Include Non-primary Names checkbox controls whether or not non-primary names are included in the index. When checked, the name fields for the Subject will be compared to the person's non-primary names, if any, as well as the primary name. The primary name is always in the index.

The data index will only include non-primary names that appear in the main name index for the site. If Primary Tags Only in the Database Section is checked, the data index will not include any non-primary names. See the Names Section for other information about how to control which names are included in the site.

Include Spouses

The Include Spouses checkbox controls whether or not the data index entry for each person includes a list of spouses. Spouses include both marriage partners and people with whom the subject shares children. When spouses are included in the index, the search form will include a Spouse section which can be used to find people based on the name of a spouse or partner.

Include Parents

The Include Parents checkbox controls whether or not the data index entry for each person includes the person's parents. When parents are included in the index, the search form will include a Father section and a Mother section which can be used to find people based on the names of parents.

Include Places

The Include Places checkbox controls whether or not the data index entry for each person includes a list of places referenced by the person's events. When places are included in the index, the search form will include a field to filter people based on places in their events.

Show Excluded Place Data

The Show Excluded Place Data checkbox controls how Second Site treats single-excluded place parts. When checked, Second Site will include single-excluded parts in the index. When unchecked, Second Site will exclude single-excluded parts in the index.

This option is similar to an option in the Master Place Index. It is intended for users who single-exclude place parts to avoid redundancy. So, for example, you may have a place "Boston, -Suffolk County, -Massachusetts", where the sentence output is "Boston". If Show Excluded Place Data is checked, the place will appear in the data index as "Boston, Suffolk County, Massachusetts".

When Show Excluded Place Data is checked, it should help to reduce the size of the data index. Even though more of the place data is shown, like-entries are collapsed into a single entry, and fewer places are included in the person record in the data index.

Show Places in Results

The Show Places in Results option controls whether the list of places associated with a person is included in the person summary in the result list. The default is unchecked, and places do not appear unless the search includes a place term, in which case the first place that matched the term is shown.

Index Content Properties

The checkbox properties that are marked with an asterisk (*) control the contents of the data index. If an item is checked, the index will include the data, and the search form will include controls to filter the results by that content.

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

<p>This Search form supports two search methods, <strong>Basic</strong> and <strong>Regular Expressions</strong>.</p>

<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>