RapidSearch Pro Documentation

Thank you for using RapidSearch Pro. RapidSearch Pro enables you to add powerful, self-sufficient, accurate, and up-to-date search to your RapidWeaver website. Search results are provided in realtime with AJAX by your very own full-text search engine. RapidSearch Pro also provides a secure online search index management application to help you fine-tune your search index.

Getting Started

Product Licensing

One RapidSearch Pro license entitles you to use the Software on a single primary domain and in a local development and client staging environment. Sub domain use is ok if the sub domain:

is a alternate language clone of the primary domain ie: http://en.mysite.com or http://it.mydomain.com
supporting content of the primary domain ie: http://help.mysite.com or http://faqs.mysite.com
If you're unsure contact us for clarification.

System Requirements

RapidWeaver 4+
Intel-based Mac OS X 10.5+
PHP 5.2+ with libcurl
One empty MySQL database
A sitemap.xml file for your website

RapidSearch Pro relies on your own sitemap.xml file to learn about your website's pages. RapidWeaver 5 will generate a sitemap.xml file for you automatically. If you are using RapidWeaver 4.x, you can generate a sitemap.xml file with LogHound's SiteMap plugin.

Your MySQL database user should have CREATE, INSERT, UPDATE, and DELETE privileges for RapidSearch Pro to work correctly. Contact your database administrator or web hosting provider if you have any questions about your database.

Installing RapidSearch Pro

Download and open the RapidSearch Pro DMG archive. A link to the file is included in the order confirmation email sent to you after your order is processed.

After the downloaded file is unzipped, double-click on the newly revealed "RapidSearchPro.rwplugin" file and re-start RapidWeaver.

Adding RapidSearch Pro to your website

Start RapidWeaver and open your website project file. Choose "File > Add Page" from the main menu bar. In the resultant screen that appears, scroll down until you see "RapidSearch Pro". Select "RapidSearch Pro" and click "Choose".

Activating RapidSearch Pro

Your product serial number is included in the order confirmation email sent to your email address after your order is processed. If you have not already, add a RapidSearch Pro page to your website project. Select the RapidSearch Pro page, and open its Page Inspector. In the Page Inspector, insert your serial number into the "Serial Number" text field and click the "Activate" button. You will be alerted when your product is activated. If you have trouble activating your product, contact me and I can assist you.

Setting up your account

Start RapidWeaver and open your website project file. Select your RapidSearch Pro page while in Edit Mode. Select the "Account" tab.

Your RapidSearch Pro account defines the username, password, and secret key for your online search index management console. Your username, password and secret key may be whatever you like. All fields are required.

Username: Used to log into the online search index management console
Password: Used to log into the online search index management console
Secret Key: Random string of characters used to encrypt the login cookie

You may change your account information at any time and re-publish the RapidSearch Pro page. Doing so, however, will immediately invalidate any users currently logged into the search index management console.

Setting up your database

Start RapidWeaver and open your website project file. Select your RapidSearch Pro page while in Edit Mode. Select the "Database" tab.

RapidSearch requires one empty MySQL database. Your MySQL database user should have CREATE, INSERT, UPDATE, and DELETE privileges for RapidSearch Pro to work correctly. Contact your database administrator or web hosting provider if you have any questions about creating your database.

After your empty MySQL database is available, enter the database server IP, the database server port, the database username, the database password, and the database name into the appropriate text fields.

If you change your database details and re-publish your RapidSearch Pro page, you will need to re-build your search index.

Specifying a sitemap.xml file

Start RapidWeaver and open your website project file. Select your RapidSearch Pro page while in Edit Mode. Select the "Sitemap" tab.

After you know the URL of your sitemap.xml file, you should insert the absolute path to the sitemap.xml file into the Sitemap text field. For example, if your sitemap.xml file is available at "http://www.domain.com/sitemap.xml", you would enter "/sitemap.xml" into the Sitemap text field.

The sitemap.xml file MUST exist on your website's domain. RapidSearch Pro currently does not support sitemap.xml files on domains different from your own.

Customizing the search page design

Start RapidWeaver and open your website project file. Select your RapidSearch Pro page while in Edit Mode. Select the "Design" tab. RapidSearch Pro helps you customize the appearance of your webite's public-facing search page.

Custom Header: You can use the styled text editor to customize the content that appers immediately before the search form. The styled text editor provides the same features available in the RapidWeaver Styled Text page.
Custom Footer: You can use the styled text editor to customize the content that appears after the search form and search results. The styled text editor provides the same features available in the RapidWeaver Styled Text page.
Custom Colors: You can change the colors of search result titles, excerpts, URLs, and relevance scores. Click the Color Picker buttons and choose the desired color.

You may also customize the search button label, the search text field placeholder text, the Clear hyperlink label, and the message displayed if no search restults are found. To customize these items, click the "Settings" button located at the bottom right corner of the RapidSearch Pro page editor in RapidWeaver Edit Mode.

Searching Your Website

Search with Boolean Logic

RapidSearch Pro supports Boolean Logic operators so your website visitors can find exactly the page they are looking for. The following operators and descriptions are from the official MySQL documentation.

+: A leading plus sign indicates that this word must be present in each row that is returned.
-: A leading minus sign indicates that this word must not be present in any of the rows that are returned. The - operator acts only to exclude rows that are otherwise matched by other search terms. Thus, a boolean-mode search that contains only terms preceded by - returns an empty result. It does not return "all rows except those containing any of the excluded terms."
[no operator]: By default (when neither + nor - is specified) the word is optional, but the rows that contain it are rated higher.
> <: These two operators are used to change a word's contribution to the relevance value that is assigned to a row. The > operator increases the contribution and the < operator decreases it.
( ): Parentheses group words into subexpressions. Parenthesized groups can be nested.
~: A leading tilde acts as a negation operator, causing the word's contribution to the row's relevance to be negative. This is useful for marking "noise" words. A row containing such a word is rated lower than others, but is not excluded altogether, as it would be with the - operator.
*: The asterisk serves as the truncation (or wildcard) operator. Unlike the other operators, it should be appended to the word to be affected. Words match if they begin with the word preceding the * operator.
": A phrase that is enclosed within double quote (“"”) characters matches only rows that contain the phrase literally, as it was typed. The full-text engine splits the phrase into words and performs a search in the FULLTEXT index for the words. Nonword characters need not be matched exactly: Phrase searching requires only that matches contain exactly the same words as the phrase and in the same order. For example, "test phrase" matches "test, phrase".

How to optimize your website

RapidSearch Pro indexes your site by analyzing each page's title, META description, and page content. Page titles are considered most important to page relevance, followed by META descriptions, followed by page content.

Page Title: This is the <title> tag in your HTML document. This should be unique and accurately describe the content and purpose of the HTML document. This is considered the most important factor when determining page relevance to search keywords.
Page META Description: This is the tag in your HTML document header. This should be unique and accurately describe the content and purpose of the HTML document. This is considered the second most important factor (second to the page title) when determining page relevance to search keywords. If a page does not have a META description, the first 156 characters of the page's content area are used instead.
Page Content: This is the content of your HTML document body. This should be unique and contain judicial use of relevant keywords that accurately describe the content of the page. This is considered the third most important factor (after the page title and META description) when determining the page relevance to search keywords.

Managing Your Search Index

Accessing the search index console

When you publish your RapidSearch Pro page to your web server, you will automatically have access to a secure online console to manage your website's search index.

To access the online console, first make sure you know the full URL of your RapidSearch Pro page (the page that shows the search form). To access the search index console, append "/files/admin.php" to the URL of your RapidSearch Pro page.

For example, if my RapidSearch Pro form is availabe at "http://www.domain.com/search/", I can log into the search index console at "http://www.domain.com/search/files/admin.php".

When you see the RapidSearch Pro search index console login form, enter the username and password you specified on the Account tab in RapidWeaver.

Building your search index

After you publish your RapidSearch Pro page, log into the search index console. The very first time you log into the search console, you should immediately build your search index. To build your search index, click the "Rebuild Index" link. You will be asked to stay on the current page until the process completes.

As your search index is built, you will see pages added interactively as they are indexed. You will be alerted when the rebuild process completes.

After you build your search index, you and/or you website visitors may now search your website on your public RapidSearch Pro form.

You must build your search index immediately after you first publish your RapidSearch Pro page. You should also re-build your search index if you make a lot of changes to multiple pages on your RapidWeaver website.

Adding a page to your search index

Log into your search index console. Let's assume you have already built your search index. Let's also assume that you just added one new page to your website. If you want this new page to appear in your RapidSearch Pro search results, you should add the new page to your search index.

To add a new page to your search index, click the "Add Page" link in the search index console. Enter the full absolute URL of the new page (including the http:// prefix) when prompted and click "OK". You should see the new page interactively added after it is indexed.

You may also add pages to your search index that do not belong to your own website.

Updating a page in your search index

Log into your search index console. Let's assume you have already built your search index. Let's also assume that you just updated a page on your website. If you want the new content of the updated page to appear in your search index, you will need to re-index the updated page.

To re-index a particular page in your search index, find the given page line-item and click its "Re-Index" button. You will see the "Last Indexed" time update after the page is re-indexed.

Removing a page from your search index

Log into your search index console. Let's assume you have already built your search index. Let's also assume that you want to remove a page from your search index.

To remove a particular page from your search index, find the given page line-item and click its "Remove" button. The page line item will be removed as soon as the page is removed from the search index. The page will no longer appear in search results.

For Developers

CSS Selectors

RapidSearch Pro provides default CSS styles so that the public-facing RapidSearch Pro search form looks great out of the box. However, it is also possible to disable the default CSS styles so they may be overriden with your own CSS. Use the following CSS selectors to style the RapidSearch Pro search form with your own styles:

#rapidsearch: The container around the search form and search results
#rapidsearch-form: The search form
#rapidsearch-form input[type="text"]: The search form text input
#rapidsearch-form input[type="submit"]: The search form submit button
#rapidsearch-form a.clear: The search form clear hyperlink
#rapidsearch-results: The ordered list element that contains search results
#rapidsearch-results li: A search result
#rapidsearch-results a.rapidsearch-link: A search result title
#rapidsearch-results p.rapidsearch-excerpt: A search result excerpt
#rapidsearch-results span.rapidsearch-score: A search result relevance score
#rapidsearch-results span.rapidsearch-url: A search result URL

JSON Search API

RapidSearch Pro provides a JSON search API so you can implement custom search results into your RapidWeaver website or even into an external website. Before you can use the API, you must first know the full absolute URL of your public-facing RapidSearch Pro page. The API endpoint URL is the same URL as your public-facing RapidSearch Pro page with a "/files/api.php" suffix.

For example, if my RapidSearch Pro form is availabe at "http://www.domain.com/search/", I can find the API endpoint at "http://www.domain.com/search/files/api.php". To request JSON search results, send a GET request for:

api.php?cmd=search&query=the+keywords

The API request requires two GET parameters:

cmd: This should always be "search"
query: URL encoded string of keywords. This may contain boolean logic operators.

Search results are returned with the "application/json" mimetype as an array of Javascript objects ordered by relevance (most relevant to least relevant):

[{
	"id":"53",
	"title":"RapidWeaver Themes and Plugins - NimbleHost.com",
	"url":"http:\/\/www.nimblehost.com",
	"description":"Shop for professional RapidWeaver themes...",
	"score":"0.8"
}]

Each search result object contains the following keys:

id: The database-assigned page unique identifier
title: The page title
url: The page URL
description: The page description
score: The page's relevance score to the search keywords, represented as a decimal between 0 and 1

The API may return a 400 Bad Request status if your request is malformed, a 405 Method Not Allowed status if your request is not a GET request, or a 500 Error status if the API malfunctioned on the server. If all goes well, the API will return a 200 OK status. If you receive a 400, 405, or 500 status code, the HTTP response body will contain information about the error.

Integrate RapidSearch Pro into your themes

It is very easy to add a search form to your theme's header, sidebar, or footer that will integrate with RapidSearch Pro. The form should submit a GET request to the public-facing RapidSearch Pro page URL with a "query" parameter whose value is a URL encoded string of search keywords. The following markup is a good example. Just be sure to change the form's action attribute.

<form action="/path/to/rapidsearch/pro/" method="get">
	<fieldset>
	<input type="text" name="query" value=""/>
	<input type="submit" value="Search"/>
	</fieldset>
</form>

Free RapidSearch Pro license for developers

If you are a RapidWeaver theme developer and implement RapidSearch Pro into your themes, I will be happy to send you a complimentary RapidSearch Pro license. This does not apply to freelancers or design studios developing custom themes for clients.

Disable jQuery

RapidSearch Pro requires jQuery 1.4.3 or higher. If you know your RapidWeaver theme already includes jQuery 1.4.3 or higher, you can disable RapidSearch Pro's built-in jQuery framework in the RapidSearch Pro settings.