• Introduction
• Configuring Search for One or More Weblogs
• Creating a Search Form
• Customize the Default Search Template
• Adding Alternate Search Templates
• Setting Up Google Enabled Entries

Over time a lot of content will be generated by a site, especially a weblog or news-oriented site. Finding that content in a reverse chronological archive can be difficult and frustrating. Local search can make a site more accessible by providing readers with the means to dynamically zero in on the content they are looking for.

Built-In Search

Movable Type's public search interface originally began as an add-on to MT developed by Jay Allen before formal plug-ins existed. The code was later integrated into MT version 2.5.

The search engine provides a rudimentary means of querying an MT system for matching entries and comments with different configurable methods such as boolean queries, phrase searching, and regular expression matching, if desired. These different methods are covered in more depth in a bit.

The MT search engine also includes a comment search that lists all of the new comments posted to entries in the site in a specified interval. This particular search was used mainly as a listing function before comment moderation was introduced in version 3.0D and should be considered deprecated.

Back to top | Permalink | Comments (0)

Problem

You want to enable your system to provide users with search capabilities across one or more weblogs.

Solution

Add configuration directives to mt-config.cgi that are related to the search engine.

Discussion

The MT search engine features a number of configurable options which are maintained in the mt-config.cgi file rather than in a web interface. The search functionality is not tied to a specific weblog, and its configuration is applied system wide.

Because these functions are not tied to a specific weblog and due to the dynamic nature of its pages, search templates are stored as files in the search_templates directory located under the MT home directory.

When the mt-search.cgi script is called, the templates are read in, translated into HTML::Template layouts, and generated through the MT::App subclass, MT::App::Search. So in essence, search templates are spoofed and not true MT templates.

HTML::Template is the CPAN module that MT uses for all of its administrative scripts' templates such as mt.cgi. This module is better tuned for dynamic template generation, but is less user-friendly for non-developers to customize and requires that all data and formatting be prepared in Perl before it is invoked. MT Search attempts to balance the trade-offs between these two template generation methods. You can use most other Movable Type tags just as you can in standard templates, although some issues and inconsistencies do exist. For instance, since this page is generated each time a reader executes a search, using any tags that would require a lot of server resources and time (for example, MTArchiveList or MTCalendar) should be strictly avoided.

Also note that given the nature of the result-generation process, MT search template tags are only recognized in these specific templates and nowhere else.

Configuring the built-in search engine

As previously mentioned, the built-in search capabilities of MT are configured through the mt-config.cgi file. Here we review the directives related to the search functionality.

• SearchScript

  This is the site URI for the search script. By default this is set to mt-search.cgi in the MT home directory.

• SearchTemplatePath

  This optional directive allows for search templates to be stored in a different path. The default is ./search_templates relative to the MT home directory.

• DefaultTemplate

  The filename of the default search template directory specified by the SearchTemplatePath directive. The default value is 'default.tmpl'.

• AltTemplate

  This directive allows for systems hosting multiple weblogs to provide different search result layouts. Configuration values are in the form of key template_filename. For instance if you wanted to create an alternate template for "play," you would add a directive of...

   AltTemplate play play.tmpl

  ...where play.tmpl represents a search template in the configured path.

  You can define as many alternate templates as you want. The keys cannot be duplicated.

  See "Adding Alternate Search Templates" for more information on how this directive can be used.

• ExcludeBlogs
• IncludeBlogs

  Since the search functionality is a system resource, these directives are included to restrict which weblogs are searchable. These directives are essentially mutually exclusive and are not recommended for use simultaneously. (IncludeBlogs will override ExcludeBlogs.) The default is to search all system weblogs. The values of the directives are expected to be weblog IDs. Multiple weblogs can be specified with commas.

• RegexSearch
• CaseSearch

  These directives specify the default values for searches. These boolean settings can be overridden through form inputs. RegexSearch allows for regular-expression syntax to be used. CaseSearch allows for searches to be case-sensitive. The default value for each of these settings is 0 (false).

• SearchCutoff
• CommentSearchCutoff

  These directives set the number of days to filter a search or a comment search: SearchCutoff and CommentSearchCutoff respectively. The default for SearchCutoff is to search all entries in a weblog. Comment search default to entries made in the last month.

• MaxResults

  An integer specifying the default number of results to return.

  NOTE: In regards to comment searches, this directive specifies the number of entries with comments and not the number of comments to display.

• ResultsDisplay

  The sort order for the search results based on their created-on timestamp. The value of this directive must be 'ascend' or 'descend.' The default is 'descend.'

• ExcerptWords

  Since the search functionality is not tied to a specific weblog, any configured limits on auto-generated excerpts via the MTEntryExcerpt are not applicable. The default is 40 words.

• SearchElement

  This directive determines which weblog entities to perform a search on. Possible values are 'entries,' 'comments,' or 'both.' The default is 'entries.'

  NOTE: A comment search is more resource intensive and can take a considerable amount of time to perform if the weblog(s) has/have an extensive number of comments.

• NoOverride

  This directive locks the search configuration from being overridden in a search query. By default, the built-in search engine allows most of the above configuration directives to be overridden by parameters passed into the mt-search.cgi script. This can have damaging side effects in that a user could override those settings through URL manipulation. This could be exploited to display hidden private weblogs by overriding the ExcludeBlogs or IncludeBlogs directives.

  The value of this directive is a comma-separated list of the other search directives that cannot be overridden. By default none of the configuration directives are locked.

Back to top | Permalink | Comments (0)

Problem

Your system is configured to enable search. Now you want to make it available to readers of your weblog.

Solution

Add an HTML form to your template that submits a "search" field to the Movable Type Search script.

Discussion

Like any CGI application, we insert an HTML form into a layout to make those services accessible to readers. Here is a basic form that may be used:

 <form method="get" action="<$MTCGIPath$><$MTSearchScript$>">
 <label for="search" accesskey="4">Search this  site:</label><br />
 <input id="search" name="search" size="20" /><br />
 <input type="submit" value="Search" />
 </form>

This form requires one parameter: search, (default values are used for the rest) and passes it to the search script.

Most of the bells-and-whistles in this form may not be overridden by the reader. Here is an HTML form that exposes those options to the reader:

 <form method="post" action="<$MTCGIPath$><$MTSearchScript$>">
 <input size="30" name="search" value="<$MTSearchString$>" />
 <input type="submit" value="Search" /><br />
 <input type="checkbox" name="CaseSearch" /> Match case 
 <input type="checkbox" name="RegexSearch" /> Regex search<br />
 <b>Search:</b>
 <input type="radio" name="SearchElement" value="entries" /> Entries 
 <input type="radio" name="SearchElement" value="comments" /> Comments 
 <input type="radio" name="SearchElement" value="both" /> Both <br />
 <b>Sort By:</b>
 <select name="SearchSortBy">
 <option value="created_on">Authored On Date</option>
 <option value="title">Title</option>
 </select><br />
 <b>Sort Order:</b>
 <select name="ResultDisplay">
 <option value="ascend">Ascending</option>
 <option value="descend">Descending</option>
 </select><br />
 <b>Exclude Weblogs:</b>
 <MTBlogs>
 <input type="checkbox" name="ExcludeBlogs" value="<$MTBlogID$>" /> <$MTBlogName$>
 </MTBlogs><br />
 <b>Search entries from:</b>
 <select name="SearchCutoff">
 <option value="9999999">the beginning</option>
 <option value="7">one week back</option>
 <option value="14">two weeks back</option>
 <option value="30">one month back</option>
 <option value="60">two months back</option>
 <option value="90">three months back</option>
 <option value="365">one year back</option>
 </select><br />
 <b>Results per weblog:</b>
 <select name="MaxResults">
 <option value="5">5</option>
 <option value="10">10</option>
 <option value="25">25</option>
 <option value="50">50</option>
 <option value="100">100</option>
 <option value="9999999">All<code>/option</code>
 </select>
 </form>

This form exposes all of the options to the reader for tailoring to their own liking. Optionally, these parameters can be passed to the search script via hidden input tags. A benefit of using this approach is that configured options are set only for the reader and won't alter parameters in the MT configuration file that may be used by the search elsewhere in the site.

Keep in mind, that depending upon the system's contents, it may not be advisable for all parameters to be overridden through HTML forms and query parameters.

If you've created an Alternate Search Template, and want to tell Movable Type which template to use when outputting the search results pages, you will use a hidden form input with a name of 'Template.' For example, to use the "play" template instead of the default, insert this hidden form input into the form above:

 <input type="hidden" name="Template" value="play" />

If you're not using Alternate Search Templates, you may still wish to "Customize the Default Search Template" which is used to display the results.

Back to top | Permalink | Comments (0)

Problem

You want to customize the look of your search engine results.

Solution

Edit the default.tmpl file in the search_templates directory.

Discussion

MT provides a handful of search tags which are only recognized in these special templates. Let's take a look at those tags and their usage:

• MTSearchResults

  Similar to MTGoogleSearch, MTSearchResults is a container tag that creates the search results context and loops through each of the returned items. This tag creates an entry context so that any of the MTEntry tags will be valid. The search also creates a blog context for the entry so that any MTBlog tags can be used.

• MTSearchResultCount

  The number of results found across all of the weblogs searched.

• MTNoSearchResults

  A container tag whose contents are displayed if a search is performed but no results are found.

• MTNoSearch

  A container tag whose contents are displayed only if there is no search performed. This is the case if a visitor were to go directly to your script (perhaps through a bookmark) without submitting any parameters through a form or query string. A good use for this tag might be to display some explanatory text search instructions or a more advanced search form.

• MTBlogResultHeader

  When displaying standard search results, the results are grouped by the weblog in which they were found. This container tag's contents are displayed if the result in context is the first result in the weblog grouping. This is useful for displaying the name of the weblog, and perhaps a link to the main index for the weblog.

• MTEntryEditLink

  This is a utility tag for providing authors with an alternate means of editing a link within MT. This tag creates a link to edit the entry represented by the search result, if the user displaying the search results page is logged in to Movable Type and has permission to edit the entry listed.

• MTSearchString

  An HTML-encoded search query.

With these tags we can assemble our template. Here is a sample template.

 <MTNoSearch>
 <h2>Instructions</h2>
 <p>Blah blah blah....</p>
 </MTNoSearch>
 <MTNoSearchResults>
 <h2>Searched for "<$MTSearchString$>"</h2>
 <p>No pages were found containing "<$MTSearchString$>".</p>
 </MTNoSearchResults>
 <MTSearchResults>
 <MTBlogResultHeader><h2>Results from <$MTBlogName$></h2></MTBlogResultHeader>
 <h3><a href="<$MTEntryLink$>#<$MTEntryID pad="1"$>"><$MTEntryTitle$></a></h3>
 <p><$MTEntryExcerpt$> <$MTEntryEditLink$><br />
 <div class="posted">Posted in <$MTBlogName$> on <$MTEntryDate$></div>
 </p>
 </MTSearchResults>
 

See also Default Search Template Changes in the Knowledge Base.

Back to top | Permalink | Comments (0)

Problem

You want to use an alternate design or layout for the search results returned by Movable Type's public search engine.

Solution

Create the template and use the AltTemplate configuration directive to define its use.

Discussion

Typically, when a search is performed, the default template, search_templates/default.tmpl, is rendered to display the results. The built-in search can perform a comment search in which the template search_templates/comments.tmpl is used.

However, if you have multiple weblogs that employ the search functionality, you may very well want the search results from one weblog to look different from that of another. To do this, you can use alternate search templates.

1. Create the template file

   For each different look-and-feel that you want, create a search results template file, and put them in your `search_templates/ directory.

   Usually, the best thing to do if you're starting out is to make a copy of search_templates/default.tmpl called, for example, search_templates/my_customized_search.tmpl and use that as a starting point. Of course, the name of the template is totally up to you and your visitors will never see it.

2. Tell Movable Type about it

   Open up your mt-config.cgi file in a text editor, and use the AltTemplate configuration directive to tell Movable Type about your new search template and the template file to use in rendering it.

   For example, if you have two weblogs, "Work," and "Play," and you want each weblog to have its own search results template, you might add something like this:

   AltTemplate work work.tmpl
AltTemplate play play.tmpl

   These two lines tell Movable Type that when the work template is requested in a search query, it should use the work.tmpl template file to display the results and that when the play template is requested, it should use the play.tmpl template file.

3. Search, customize, and reload

   At this point, you're probably going to want to customize your new template before unleashing it on the world.

   To do so, take the following URL:

   http://www.example.com/path/to/mt-search.cgi?Template=NAME

   ...and substitute the placehoders above with the:

   • correct domain and path to mt-search.cgi for your installation
   • template name you chose in the previous step for NAME.

   When the page loads, it should be showing your template, which you can edit and reload as many times as you like without ever affecting your visitors. If you've edited your blog templates before, the search templates will feel very familiar to you except that, in addition many tags you're used to, they also use the special search template tags.

   Once you have it just right, move on to step 4.

   Notes: If you get an error like "No alternate template is specified for the Template 'work'", check the AltTemplate setting in your mt-config.cgi file and make sure that both the template name is identical to the one used in the URL and that that the template filename is identical to the file in search_templates folder.

4. Configure the search form

   Now that your search template is perfect, it's time to let the world use it in their searches. If you don't already have a search form on, for example, on your main index, see "Creating a search form".

   To use your new template in your search form, specify it a hidden form input. Anywhere between the <form ...> and </form> tags, add the following substituting your template name for NAME:

   <input type="hidden" name="Template" value="NAME" />

   If you wish to restrict the search to just this one weblog, you may also
   want to add a hidden IncludeBlogs paramter with the blog ID like so:

   <input type="hidden" name="IncludeBlogs" value="<$MTBlogID$>" />

Related

• Public Search
• Default Search Template Changes

Back to top | Permalink | Comments (0)

Problem

You want to integrate Google search results into your entry.

Solution

Provide Movable Type with your Google API Key and use the MTGoogleSearchResult template tag.

Discussion

Movable Type is capable of making Google search queries and inserting the results into site layouts. This built-in functionality is geared toward inserting related links into an entry or a specific topic such as an author's name rather than providing unfettered access to the full power of the Google search engine. This is more a limitation of the Google API than anything related to MT's implementation.

This functionality requires that your system has the SOAP::Lite and LWP::UserAgent modules from CPAN. They also require a Google API key be obtained and configured to activate each weblog. Doing so is relatively straightforward process.

• 1. To obtain a Google API key go to http://www.google.com/apis/ to register for an account. Once registered you will receive a license key from Google that is good for 1000 queries a day.
• 2. Go into the Movable Type CMS and click the Edit Configuration link next to the weblog you want to enable or, within the weblog, click the Settings button in the Weblog Toolbar.
• 3. Under the General tab of the Settings screen enter your Google API Key and then press Save Changes.

The Google search features of this weblog have been enabled.

You can reuse your Google API key in multiple weblogs. Each weblog's usage will count towards the key's daily quota.

Integrating Google results into Movable Type is achieved through two action packed tags -- MTGoogleSearch and MTGoogleSearchResult.

MTGoogleSearch creates the search context by using the Google API to obtain results for a particular query or for pages that are similar to a particular entry. Once retrieved, the contents of this tag are looped through for each result. The type and parameters of the search are determined by the following supported attributes.

• query

  Issues a specific search to Google.

• related

  Return results that are similar to a certain page. The value of this parameter can be a URL or 1. Passing a value of 1 will cause your Site URL to be used. (You should have set your Site URL in your Weblog configuration -- if not you'll have to do so to make use of this option.)

• results

  An integer between 1 and 10 specifying the number of search results to insert.

• title

  Takes a boolean value. If set to 1 (true), the title of the entry in context will be used as the query.

• excerpt

  Takes a boolean value. If set to 1 (true), the excerpt of the entry in context will be used as the query.

  Is there a limit on words???

• keywords

  Takes a boolean value. If set to 1 (true), the keywords of the entry in context will be used as the query.

NOTE: query, related, title, and excerpt are mutually exclusive of each other.

MTGoogleSearchResult represents a field of an individual Google search result. This tag is used in the context of a MTGoogleSearch tag.

The tag recognizes a single attribute of property that specifies the field of the search result to be displayed. Values for property can be: "summary," "URL," "snippet," and "title." The default property is title.

Let's look at some example uses of these tags:

To list the top five search results for the query "movable type," insert this template code:

 <MTGoogleSearch query="movable type" results="5">
 <a href="<$MTGoogleSearchResult property="URL"$>">
 <$MTGoogleSearchResult property="title"$></a><br />
 </MTGoogleSearch>

Alternatively, to insert a list of related links based on a site's home page, insert this template code:

 <MTGoogleSearch related="1">
 <a href="<$MTGoogleSearchResult property="URL"$>">
 <$MTGoogleSearchResult property="title"$></a><br />
 </MTGoogleSearch>

Google search results on a per entry basis can be inserted into an Individual Search Archive template like so:

 <MTGoogleSearch title="1" results="3">
 <p><a href="<$MTGoogleSearchResult property="URL"$>">
 <$MTGoogleSearchResult property="title"$></a><br />
 <$MTGoogleSearchResult property="snippet"$></p>
 </MTGoogleSearch>

This of course assumes that entry titles are sufficiently descriptive to return relative results from Google.

Impact on Performance and Other Limitations

If you use the Google search tag in your Individual Archive Template, a call will be made to Google for each entry. This will significantly impact the speed of the rebuilding process. Depending on the number of posts in the weblog or how often entries are rebuilt, perhaps to display a new comment, the daily quota of Google permits could be exceeded.

Back to top | Permalink | Comments (0)