Custom Search

A flexible power search creator for Plone

Version

Version 0.5.0

Copyright and licence

Copyright 2006 Red Innovation

Licenced under GPL.

Purpose

Custom Search aims to making custom search queries for Plone sites as easy as possible. The search result listing can be customized to be more descriptive than with the standard Plone search. Powerful search features help to target searches better.

More example screenshots can be found at the documentation area.

Features

• Search queries appear as standard Plone content objects. They are in navigation tree, they have permissions, etc.
• Searches can be based on any indexable Plone content field
  • Custom attributes on custom content, like price and other measurements
  • Document body text
  • Content type
  • Creation date
  • etc.
• Easily customizable result listing templates
• Many out-of-the-box search query fields
  • Value search - match fields by direct value
  • Text seach - match fields by partial text (the default Plone search)
  • Listing search - match fields by one listed value
  • Minimum and maximum number bounding
• Limiting searches to certain section of a site
• Limiting searches by content type

Future features

These features are not yet in Custom Search, but are planned in the future

• Batches (e.g. display results 1-100, 101-200...)
• Selection list options for the end user
• Boolean queries
• Integrating with criterias used with Smart Folders (ATContentTypes/criteria) and reworking the
• Internationalization

Dependencies

Following Plone add-on products are needed to run Custom Search

• AdvancedQuery
  • AdvancedQuery is a Zope product, by Dieter Maurer, aimed to overcome several limitations of ZCatalog's native search function
  • Internally Customs Search uses this Zope product. It enhances portal_catalog search abilities with boolean conditions and many other features.
  • Bundled with the download package
• DataGridField
  • Used for edit search query form
  • Bundled with the download package
• PloneInstallation
  • Installer utilities
  • Bundled with the download package

Installation

For the sake of easy installation, AdvancedQuery and DataGridField are bundled inside the download package. These might collide with your versions, so don't let them overwrite your existing installations.

1. Put AdvancedQuery to your Plone 's Products folder
2. Put DataGridField to your Plone's Products folder.
3. Put CustomSearch to your Plone's Products folder.
4. Run Plone quick installer for DataGridField and CustomSearch

Quality

This is a beta release and still a bit proof-of-concept. The product is in limited production usage, but to make more generalized and bullet proof, more work is needed. Please contact the authors if you need to make work based on this product for joint efforts.

The product has few unit tests to ensure basic functionality. The product has been tested with Plone 2.1.x branch only. Plone 2.5 compatibility is not guaranteed yet.

References

A little demo is available at List it your way -site.

Usage

Edit mode

The purpose of edit mode is to allow the site manager to customize the search easily. In edit mode, Custom Search appears as any standard Plone content with edit fields available. Since the edit mode form is quite crowded, use Plone's full screen edit mode (the icon at top right corner). If you manage to get Custom Search to non-working state, add /edit after Custom Search URL and you get yourself back to edit mode again.

One can create Custom Search as any other content type from Add XXX content drop down menu.

Title and description are self-explaining and they will be used in Plone folder listing, navigation tree and site map.

Body text allows the site manager to give some help text for the usage of the search.

The search result listing page template is for site creators who wish to use custom page templates for their search result listing. Don't touch this unless you know what you are doing!

The last field, fields, is a table defining search fields.

Search fields descriptions

• Friendly name
  • User readable label for the search query field
• Type
  • What kind of search field is this. For more information, read class comments in searchfields.py module.
  • Value search - match field directly by value
  • List search - possible values are given as a comma separated list (boolean OR for the field)
  • MinMax search - possible values are given by minimum and maximum limit. Works only with FieldIndex.
  • Image search - No search query input. Display an image thumbnail in the result listing.
  • Path search - Match values against item path (ExtendedPathIndex and displays a nice location path in the result listing.
  • Boolean - Matches boolean value (indexed attribute is Python True or False object).
• Index
  • Which portal_catalog index is used for the search
  • For more informartion about search indexes, read the paragraph "Indexes and metadata" below
• Default
  • The default value for the HTML field
  • Also, if this field is locked, this value is used as the input
• Visibility
  • Defines where the search field is visible
    • Query field - user is able to make queries based on this field. The field appears on the search query form only.
    • Result field - user is not able make queries based on this field. The field appears on the search result listing only.
    • None - the field is hard-coded and user is not able to affect it
• Mode
  • Defines how user can interact with the search field
    • User editable - user enters his wanted information for this search query field
    • Fixed value - the site manager specifies a hard value for the field and the users cannot change the value

View mode

When Custom Search content is displayed in view mode a seach query form appears. When user enters search query for the first time, results are displayed below the search query form. Search results are linkable (i.e. the link can be used to copy-paste search result listing for other people/pages).

Limiting search area

Often, for the sake of results clarity, the search needs to be targetted to specific content type or site area. Let's not leave this burden to our clueless users. With Custom Search, one can limit searches as well as one can make custom queries.

To limit searches

• Set search field visibility to none
• Set mode to fixed value
• Choose index which you want to use to limit searches
  • To limit by type
    • Use index Type
    • Use ValueSearchField or ListSearchField
    • Set default to values like "Document", "Folder", "Custom Search"
  • To limit by path
    • Use index path
    • Use PathSearchField
    • Set default to portal path where you want to limit the search, e.g. "/mysubarea/myfolder".
• Use value field or list field to choose how you set your limitations
• Put your limitation search query string to the default value of the search field

Partial text matching

The index defines how the text is matched during the search. With the stock Plone, fields which are indexed with ZCTextIndex, are automatically partially matched. Fields indexed with FieldIndex are matched by value.

Sorting

Custom Search can have forced in sort keys and user selectable sort keys. Unlike in stock Plone, many sort keys can be given since we use AdvacendQuery searching back end.

• Forced in sort keys are used for situations when there is only one meaningful way to sort the results and the user is not bothered to make any confusing choices.
• Forced in sort keys can be used with the combination of user selectable sort keys. Forced in sort keys have higher priority, so this way we can have "sponsored items" appear in the result listing first
• User available sort keys allow the search users to choose how the search results are sorted.

Sort key field descriptions

• Friendly name
  • User readable label for the search query field
• Index
  • Which portal_catalog index is used for the sort
  • For more informartion about search indexes, read the paragraph "Indexes and metadata" below
• Priority
  • If there are many forced in sort keys, their execution order is based on priority. Priority is an integer number. 0 is the highest priority, 9999 is the lowest.
• Mode
  • Defines how user can interact with this sort key defition
    • User can choose - the sort key is available for the user
    • Forced in - the results are always first sorted based on forced in keys and the user doesn't have control over them
• Order
  • Ascending or descending

Special note about sorting and ZCTextIndex

ZCTextIndex indexes (like Title and Description) are not sortable. To sort the results based on title, use sortable_title index.

Indexes and metadata

Indexes are the foundation of searching. Indexes hold copies of object information in easy to match form and index value->actual object mapping. Metadata is exact duplication of information which can be displayed without retrieving the actual object from database. Always when possible, indexes and metadata should be used for listing information, since retrieving individual content objects from Zope database is a very slow operation.

Every time object is created, edited or deleted, corresponding indexes and metadata are updated so that search catalog stays up-to-date.

Custom Search allows you to to pick indexes and metadata from Plone's portal_catalog tool values. To add more indexes and metadata, go to Zope management interface and portal_catalog tool. You can refer to how to Adding new fields to Smart Folders search.

Different Plone indexes

• ZCTextIndex: Text Indexes break text up into individual words, and are often referred to as full-text indexes. Text indexes sort results by score, meaning they return hits in order from the most relevant to the least relevant.
• Keyword Indexes index a sequence of objects that act as 'keywords' for an object. A Keyword Index will return any objects that have one or more keywords specified in a search query.
• A DateIndex indexes DateTime attributes.
• A DateRangeIndex takes the name of two input attributes; one containing the start date of the range, the second the end of the range. This index is filled with range information based on those two markers. You can then search for objects for those where a given date falls within the range.
• Field Indexes treat the value of an objects attributes atomically, and can be used, for example, to track only a certain subset of object values, such as 'meta_type'. FieldIndex support ranged min max searches.
• ExtendPathIndex holds object place data in site hierarchy. This is case sensitive.
• TextIndex is deprecated. Don't use it.

Note that FieldIndex cannot do partial text matching, you need to use ZCTextIndex always for that.

For example, if your custom content type has declared a field "price" in its schema and you want to make this field available for Custom Search

1. Create FieldIndex getPrice in portal_catalog, Zope management interface
   • The name of the index matches the corresponding field accessor method
   • This makes price searchable
2. Create metadata getPrice in portal_catalog, Zope management interface
   • This makes it possible to display price information in the search result listing
3. Create a custom search, with a search field definition
   1. Name = Price
   2. Index = getPrice
   3. Type = MinMax (suits for a price well)

This process should not be confused with setting "searcahble=True" in Archetypes schema declaration. searchable=True means that the field is text indexes and available for full text search in Plone default text search.

Sponsorship

This product development was sponsored by www.listityourway.com

Contact

To ask help, to sponsor Custom Search development, to take over the project or to hire skilled Plone developers, please contact us. Also, you can use plone.org product area issue tracker to report bugs and suggestions.

info@redinnovation.com

www.redinnovation.com

Wishing a happy Ploning,

Mikko "Moo" Ohtamaa