Opensearch Plug-In

OpenSearch Plug-in

Alterian Content Manager

Corporate Edition 6.2

28 May 2009

www.alterian.com

Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives.

Documentation feedback and comments: [email protected]

Alterian Content Manager and the Alterian Content Manager logo are trademarks of Alterian. Windows XP, SQL Server, ASP.NET, Visual Studio .NET and C# are trademarks of Microsoft Corporation. All other products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark.

www.alterian.com

Document Control

The following table details the revision history of this Installation and User Guide. It details significant changes to the text and the software version to which the changes apply.

Version History

Date Author Version Change reference

08 Dec 08 Jordanka Balkanska 6.1 Template Rebranded 09 Dec 08 Jordanka Balkanska 6.1 Initial revision 12 Feb 09 Jordanka Balkanska 6.1.3.0 Plug-in Installer enhancement, Plug-in installation into Multiple CMS websites 28 May 09 Jordanka Balkanska 6.2 Product Rebranding

Distribution List

Who Position

Jordanka Balkanska Technical Author

OpenSearch Plug-in i of ii

Table of Contents

1 Summary ...... 3

1.1 Example: FireFox 2 showing the available OpenSearch providers setup...... 3

1.2 Example: FireFox 2 showing OpenSearch being used with a suggestion service. ... 3

2 Overview...... 4

3 Installation ...... 5

3.1 Using the Plug-in Installer ...... 5

3.1.1 Run the Plug-in Installer: 5

3.2 Manual Installation: ...... 8

3.2.1 Copying the files 9

3.2.2 Stored Procedure Installation 10

4 Configuration ...... 12

5 Personalization ...... 15

5.1 Autodiscovery ...... 15

5.2 Clickable Link/Button ...... 16

5.3 Results Formatting ...... 19

5.4 Multi-language Support ...... 19

OpenSearch Plug-in ii of ii

1 Summary

CMC brings OpenSearch 1.1 capabilities.

“OpenSearch is a collection of technologies that allow publishing of search results in a format suitable for syndication and aggregation. It is a way for websites and search engines to publish search results in a standard and accessible format.” (Wikipedia, http://en.wikipedia.org/wiki/OpenSearch )

“OpenSearch is a set of simple formats for the sharing of search results. Any website that has a search feature can make their results available in OpenSearch™ format. Other tools can then read those search results.” (A9, http://opensearch.a9.com/ )

Internet browsers IE7 and FireFox 2 natively support OpenSearch, allowing users to consume a web site’s search facilities directly within the browser UI without having to first visit the site.

1.1 Example: FireFox 2 showing the available OpenSearch providers setup.

1.2 Example: FireFox 2 showing OpenSearch being used with a suggestion service.

Further information on OpenSearch can be found at http://opensearch.a9.com/ .

OOOpenSearchOpenSearch PlugPlug----inininin Page 3 of 23

2 Overview

OpenSearch works on CMC 6.2. The steps that follow in this document explain how to install, configure, and then personalize an OpenSearch installation for your specific CMC published web site.

The directions need to be repeated for each site that OpenSearch is to be configured for, and need to be repeated for each server in a multiple server deployment CMC configuration.

OOOpenSearchOpenSearch PlugPlug----inininin Page 4 of 23

3 Installation

There are two ways to install the OpenSearch Plug-in, either running the plug-in installer or manually installing the plug-in to the CMC website.

3.1 Using the Plug-in Installer

These steps are a guide to the tasks necessary to install the OpenSearch Plug-in using the Plug-in Installer on your website.

3.1.1 Run the Plug-in Installer: 1. Run Start All Programs Alterian CMC 6.2 CMS Management Console and click Website Configuration . Click Plug-in Installer . The Welcome Dialog is displayed. Click Next to proceed.

OOOpenSearchOpenSearch PlugPlug----inininin Page 5 of 23

2. The Plug-in Setup dialog is displayed. This will provide an option to select the source plug-in folder and the available list of websites on which the plug-in can be installed. Select the Plug- in source path and the websites to install. Click NextNext to proceed with installation.

OOOpenSearchOpenSearch PlugPlug----inininin Page 6 of 23

The Confirm Installation dialog is displayed. Click Next to continue.

3. The Installing Plug-in dialog will display the installation progress. The user can stop the current installation by clicking the Cancel button at any time.

OOOpenSearchOpenSearch PlugPlug----inininin Page 7 of 23

The details of the OpenSearch Plug-in installation will be displayed. Click Next to continue. 4. Once you have clicked Next you will be shown the Installation Complete dialogue . If you click Finish having selected the Show log file on exit checkbox, a log file will be opened for you to inspect individual log entries. The log file will contain the entire details of the plug-in installation operation. If you unselect the checkbox clicking Finish will close the installer and complete the installation.

The installation of the OpenSearch plug-in is now complete.

The plug-in installation will deploy the plug-in in to your website. Note Please note that any configuration of the plug-in is likely to be manual and is explained in the plug-in’s configuration guide.

3.2 Manual Installation:

The following instructions explain how to install, configure, and then personalize an OpenSearch plug-in manually for your specific CMC published website.

The instructions will need to be repeated for each CMC website that requires an OpenSearch capability. In addition, the process will need to be repeated on each server in a multiple server deployment of CMC.

OOOpenSearchOpenSearch PlugPlug----inininin Page 8 of 23

3.2.1 Copying the files

Copy the contents of the webroot folder in the plug-in package to the webroot folder of your CMC website. Overwrite files if prompted.

OOOpenSearchOpenSearch PlugPlug----inininin Page 9 of 23

3.2.2 Stored Procedure Installation

Some CMC plug-ins use stored procedures to access the Alterian CMC database. To install the OpenSearch plug-in stored procedures, follow these steps: 1. Run Start All Programs Alterian CMC 6.2 CMS Management Console and click Website Configuration. Click Plug-in Stored Procedure Installer .

2. The Stored Procedure Installer dialog is displayed. By default the Automatic radio button is selected. This causes the installer to automatically detect the .imc file that exists for each configured site and populates the Select IMC File drop-down list with those detected. Alternatively, you can select the Manually Specify Database Details radio button and use the ellipsis button to browse to folder containing the .imc files and click the Refresh button to populate the Select IMC File drop-down list.

OOOpenSearchOpenSearch PlugPlug----inininin Page 10 of 23

3. Select the .imc file that corresponds to the site requiring the OpenSearch Plug-in from the drop-down list and click the Continue button. 4. The Stored Procedure Installer dialog now displays a pane into which the required .iuf files must be dropped.

5. Open the OpenSearch\SQL folder and drag and drop the OpenSearch-Install.iuf file into the pane in the Stored Procedure Installer dialog. Alternatively, use the ellipsis button in the Stored Procedure Installer dialog to navigate to the OpenSearch-Install.iuf file, select the file and click the Open button.

6. Once the OpenSearch-Install.iuf file is present in the pane, click the Apply button.

To uninstall the stored procedure, repeat the above process with the Note OpenSearch-Uninstall.iuf file.

The installation of the OpenSearch Plug-in is now complete.

OOOpenSearchOpenSearch PlugPlug----inininin Page 11 of 23

4 Configuration 7. Open \plugins\opensearch\opensearch.xml within the webroot of your CMC site (if necessary ensure the file is not read-only). 8. Modify the following values to customize the search to your target CMC site:

a. ShortName (A brief name that will appear in buttons, UI controls, etc., that reference this search content provider)

b. Description (A human readable text description of the search content provider)

c. Tags (A space-delimited set of words that are used as keywords to identify and categorize this search content)

d. Contact (An email address at which the developer can be reached)

e. Image (A URL that identifies the location of an image that can be used in association with this search content)

i. The sample image provided is \plugins\opensearch\Alterian_Icon.ico. If not using this image, the file can be deleted.

f. LongName (The name by which this search content provider is referred to in hypertext links, etc.)

g. Url (An element that describes a URL template that will undergo parameter substitution to be used for the retrieval of search results)

i. The sample XML document contains 4 Url declarations, which it is recommended you keep and leave in the same order, for browser compatibility (at time of writing).

• Atom/XML – used to output Atom formatted search results • RSS/XML – used to output RSS2 formatted search results • Text/HTML – used to output standard HTML formatted search results • X-Suggestions+JSON – used for the Suggestion Service to provide search suggestions based on current input

i. You should change the value of the template attribute in each element to reflect the URL of the site being configured – do not change the virtual path following the domain URI or the parameter query string.

For more information on configuring this XML file, please see Note http://opensearch.a9.com/spec/1.1/description/

OOOpenSearchOpenSearch PlugPlug----inininin Page 12 of 23

9. Save the XML file, and close it. 10. Open \plugins\opensearch\opensearch.ascx in a text editor or Developer environment such as Visual Studio .NET 2005/2008 (if necessary ensure the file is not read-only). 11. Modify the values within the following section:

// **** // User Variable Settings // - Change these to customise the opensearch // **** public const string siteURL = "http://localhost/cmcsample/"; // The base URL of the site including trailing / slash public const string siteSearchTitle = "Alterian CMC Search"; // The name of the open search public const string siteSearchName = "CMCSample.com"; // The name of the website/company public const string siteSearchImage = "Alterian.ico"; // The image file name in the opensearch plugin folder public string noResultsMessage = Resources.OpenSearch.NoResultsMessage; // Message to display when no results found public string noResultsMessageTitle = Resources.OpenSearch.NoResultsMessageTitle; // Message to display when no results found // ****

a. siteURL - The base URL of the site including trailing / slash

b. siteSearchTitle – The name of the OpenSearch provider instance for your CMC published site

c. siteSearchName – The name of the website / organization

d. siteSearchImage – The filename of an image residing in the \plugins\opensearch folder as referenced by point 2e.

OOOpenSearchOpenSearch PlugPlug----inininin Page 13 of 23

e. noResultsMessage – The message to display when no results are found. If you are not concerned with supporting multiple languages in the website, you can replace the ‘Resources.OpenSearch.NoResultsMessage’ text with your custom message in quotes.

12. Save the ASCX file, and close it. After completing these steps, your CMC published site will be configured correctly to support outputting search results in the OpenSearch 1.1 format to the next generation of browsers and allow submission to search aggregators such as http://www.a9.com . You can validate that you have modified the files correctly by draft submitting your search to a9.com http://opensearch.a9.com/newColumn.jsp (free account signup required), or configuring Microsoft Internet Explorer 7 or FireFox 2 with the URL of your OpenSearch Description, which will be: http://[siteurl]/plugins/opensearch/opensearch.xml

…where ‘[siteurl]’ is the URL to your site, for example http://www.immediacy.net/plugins/opensearch/opensearch.xml

OOOpenSearchOpenSearch PlugPlug----inininin Page 14 of 23

5 Personalization

This section describes how to configure your website templates to advertise to site visitors the fact your website provides OpenSearch 1.1 capabilities and allow for them to configure their browsers to add your provider instance.

5.1 Autodiscovery

The information is taken from Note http://opensearch.a9.com/spec/1.1/description/#autod iscovery

Autodiscovery provides a simple means for referencing the appropriate OpenSearch Description files from a web page (HTML). It makes use of the element within , as described in the HTML 4.01 Specification. Autodiscovery is not a requirement of OpenSearch Description files, but it is strongly recommended so that others can find it. Below is a simple example:

To enable this within an Alterian CMC published site, each ASCX template needs to be configured to add the following HTML element within the section:

OOOpenSearchOpenSearch PlugPlug----inininin Page 15 of 23

Modify the title and href attributes to represent the correct settings of your site.

Once configured, visitors of your site should notice their browsers indicating the presence of OpenSearch 1.1 capabilities on your website, by highlighting in orange (at time of writing) the search controls within the browser.

5.2 Clickable Link/Button

With some simple HTML and JavaScript, it is possible to create a link or button which when clicked will allow a site visitor to add your OpenSearch provider instance to their instance of Microsoft Internet Explorer 7 or FireFox 2:

The HTML above shows how to achieve this using a button, but the JavaScript in the onClick can be used elsewhere. If using the example above, ensure the URL specified in the call to AddSearchProvider () is the correct one for your site as described in the Autodiscovery section above.

An example of this implemented can be seen in the HTML/ASP.NET/JavaScript code snippet below, which could be inserted into a template. It uses server side browser detection to only show the floating dialog if the client browser is FireFox 2 or Microsoft Internet Explorer 7. It sets a cookie so that the client is not continually prompted with the dialog.

OOOpenSearchOpenSearch PlugPlug----inininin Page 16 of 23

Example use of HTML & JavaScript to allow users to add an OpenSearch provider from a CMC site to their browser.

Sample Code below: (Provided as-is without warranty)

<% if( Request.UserAgent.ToLower().IndexOf("firefox/2") != -1 || (Request.Browser.Browser.ToLower() == "ie" && Request.Browser.MajorVersion >= 7)){ %>

<% } %>

The above code serves only as an example, and is not meant to be used without adjustment. The image file \plugins\opensearch\ Alterian_Logo.gif supplied can be deleted from the site webroot if this example is not to be used and modified.

OOOpenSearchOpenSearch PlugPlug----inininin Page 18 of 23

5.3 Results Formatting There are three files provided with the OpenSearch deliverables for formatting the RSS & ATOM XML outputs, ‘opensearch_to_html.xsl’, ‘opensearch_to_html.css’ and ‘opensearch_to_html.js’. This allows browsers to display the XML generated search results in a style which conforms to a given design. Further information on these can be found at http://www.opensearch.org/Documentation/Stylesheet.

5.4 Multi-language Support

To support multiple languages configured in the CMC website, the following steps should be completed for each language: 13. Create a copy of the opensearch.xml file and rename it. A suggestion would be to use the language code as a suffix e.g. opensearch_de-DE.xml. 14. Open the new file using an XML or text editor. 15. Modify the template attributes in the URL elements to include a ‘lang’ query string parameter with its value set to the language code as below:

template ="http://[SiteURL]/plugins/opensearch/OpenSearch.aspx?lang=de -DE & q={searchTerms} & p={startPage} & c={count} " 16. Customize the other values for the language if necessary (e.g. translated ShortName, LongName, Description and Tag element values). 17. If you have included autodiscovery links in your website templates as described in the Autodiscovery section , you should insert a link for each language within language elements as below:

OOOpenSearchOpenSearch PlugPlug----inininin Page 19 of 23

18. If you have a link or button in your website templates to allow visitors to add your OpenSearch provider to the browser as described in the Clickable Link/Button section , you can also place these in language elements to specify different OpenSearch description files for each language. Example:

OOOpenSearchOpenSearch PlugPlug----inininin Page 20 of 23

Corporate and North American European Headquarters Headquarters

Alterian Plc Alterian Inc. The Spectrum Building 35 E. Wacker Drive Bond Street Suite 200 Bristol Chicago, Il 60601 BS1 3LG USA UK T +1 312 704 1700 T +44 117 970 3200 F +1 312 704 1701 F +44 117 970 3201

Other Offices

Alterian Alterian Alterian Insight House 1010 Washington Blvd. Building 34 Newbury Business Park 9th Floor Suakin Drive London Road Stamford Mosman Newbury, Berkshire CT 06901 NSW 2088 RG14 2QA USA Sydney UK T +1 203 653 9090 Australia T +1635 262000 F +1 203 653 9095 T +61 2 9968 2449 F +1635 262001 F +61 2 9969 1163

Alterian Alterian B.V. Alterian Technologies India Pvt. Ltd. Branksome House Naarderweg 16 3rd Floor Discovery Court Business Park 1217 GL Hilversum H.M. Rochester Wallisdown Road Postbus 371 197 Double Road Poole, Dorset 1200 AJ Hilversum Indiranagar BH12 5AG The Netherlands Bangalore – 560 038 UK T +31 35 625 7890 T +91 80 2521 0740 T +44 1202 250000 F +31 35 625 7899 F +44 1202 250001

Alterian Alterian Alterian Deutschland 25152 Springfield Court 125-B Sully’s Trail Theresienstra βe 6-8 Suite 360 Pittsford, NY 14534 80333 München Valencia, CA 91355 USA Germany USA T +1 585 586 0160 T +49 89 288 90 164 T +1 661 367 9970 F +1 866 537 1533 F +49 89 288 90 45 F +1 661 367 9969

Alterian Nordics Sjöhagsvägen 6 721 32 Västerås Sweden T +46 21 495 01 40