alogblog's MTy plugins: webSSearchy, a click-and-get Web Service consumer

This entry is for MT 3.2 version. If you use MT 3.3, see this entry

webSSearchy is a Movable Type plugin which enables your visitors to easily search more related pages in the web space with a help of your own suggesting search queries, the AJAX technique, and some Web Service API. Currently I provide three CGI, which are for Google, Naver(for Korean), Yahoo web services, and one additional CGI which makes MT's original serach CGI(mt-search.cgi) work as a simple search webservice.

You can see its working.

When visiting other's blogs, we frequently have an experience that we want to know more on that subjects or techniques. In that case, we use search engines. As of now, most browsers have easy-to-use search input box, so doing search itself is a piece of cake. I think the most(?) time-comsuming and important step in doing search is the selection of suitable search keywords, or queries. Of course if we have a sufficient background on that subject, that also could be easy. But if that subject of an entry is new to us, we might hesitate in choosing search queries. In such a situation, one definite fact to be undeniable in general is that THE AUTHOR of that entry is more likely to know the subject. Once an author presents his/her visitors with search querties and one-click AJAX search system, some visitors will save their efforts on thinking proper queries and doing search. To view this in a broad prospect, it will help to increase the entropy of Web.

Screenshots

*The queries of webSSearchy in this entry are chosen as an example, so some are not related in this entry's subject.

Requirement

Movable Type 3.2
Perl's Encode, CGI, XML::Simple, LWP::UserAgent, DB_File, SOAP::Lite modules
Google API key ( Go and get key in http://www.google.com/apis/ )

Installation

You may think complete installation steps are quite long. This plugin comprises three parts roughly. MT plugins(MT menu, MT tag) part itself, (Google/Naver/Yahoo/MT) CGI part, and AJAX related JS and designing CSS part. Yes, it's long, but not difficult. It needs a little TIME, no BRAIN. Why don't you have a coffee?

1.
Download this plugin (sorry plz wait a little)and untar it under (mt home) folder like $ tar xvfz webSSearchy-3.2.tar.gz.
Add AltTemplate search_rss search_rss.tmpl in (mt home)/mt-config.cgi file.

2.
You can move (mt home)/webSSearchy/ folder into others. In this case, From now on, I assume that webSSearchy/ folder was moved into under web root folder. And if you are not Korean, you can delete naver.* files.

3.
Check webSSearchy/*.cgi's execute permission. Open http:/ / your_domain/webSSearchy/check.cgi in browser. This CGI checks all required Perl modules and file write permission. (The webSSearchy CGIs use cache mechanism. Search results will not frequently changed in 1, 2, or 3 days. So CGI caches search results in a file DB for default 3 days.)

4.
Open MT's Individual Entry Archive template, and put below tags into a proper location.

<MTIfWebSSearchy>
<h3 id="webSSearchy-header">webSSearchy</h3>
<div class="webSSearchyLinks">
<MTWebSSearchys><MTWebSSearchyLink></MTWebSSearchys>
</div>
<div id="webSSearchyResult<$MTEntryID$>" class="webSSearchyResult"></div>
</MTIfWebSSearchy>

You can fully change its DIVs id, class or anything else to your taste later, but not now. And in the <head> section of Individual template, embed this plugin's Javascript and CSS file, and save it.

5.
Open google.cgi file. In the required section of it, two variables ($apiKey and $wsdl) MUST be set.

6.
Open webSSearchy/mt.cgi file. Change two variables, $service_alias and $mt_search_url.

7.
Open webSSearchy/webSSearchy.js file. Change CGIbaseURL, progressingImage variable.

8.
Open webSSearchy/webSSearchy.css file. In it, sync image url(..) parts of each service. Default URL is like 'url(/webSSearchy/google.gif)'. If you moved 'webSSearchy/' folder into web_root, you don't need to do it.

9.
Open (mt home)/plugins/alogblog/webSSearchy.pl file. In it, you can change 'mt's service_alias into yours.

10.
Like above screenshots, enter your queries into new test entry and save it. If you see its links working well, it's OK although you don't know below things.

webSSearchy Tags

These all tags should be used within entry context, for example, <MTEntries>[[ In here!!! ]]</MTEntries>, or in Individual Archive Entry template.

<MTIfWebSSearchy> : A conditional tag that displays its contents if the "Queries for webSSearchy" field has been defined.
<MTWebSSearchys> : A container tag which iterates over a list of entered queries.
<$MTWebSSearchyService$> : Displays service name. eg) 'yahoo', 'google'. It can be used as CSS id, class name, and so on.
<$MTWebSSearchyServiceAlias$> : Displays service nickname you customized. eg) 'Yahoo', 'Google'. It can be used as a localized service name.
<$MTWebSSearchyTarget$> : Displays service's target name. The term 'target' was named for convenience' sake. Each web services provide several sub-searches. For example, Yahoo search web service provides 'travel', 'image', 'news', 'video' search and so on. These are 'target's of Yahoo service.
<$MTWebSSearchyTargetAlias$> : Displays service's target nickname you customized.
<$MTWebSSearchyQuery$> : Displays query value you entered.
<$MTWebSSearchyLink$> : Displays <a href="#" onClick="...">..</a> link for your convenience.

Example 1

If you want to embed a search link, "What is Web 2.0?" by Google, and "Sharapova" image by Yahoo, you need to enter two queries in entry's "Queries for webSSearchy" textarea. And then you apply "Google Search" and "Yahoo Image" to each queries by selection menu. Then its content of that textarea will be as like
google.search.What is Web 2.0?
yahoo.image.Sharapova
Each line will be displayed like "service name (comma) target name (comma) query".

And suppose you designed template tags as follows,

then its published output will be

     <div>
        <p class="google">Google</p>
        <p class="search">Search</p>
      <p>What is Web 2.0?</p>

        <p class="yahoo">Yahoo</p>
        <p class="image">Image</p>
        <p>Sharapova</p>

    </div>

Example 2

In installation step, we used <MTWebSSearchyLink> tag. This tag is the combination of below tags.

<a href='#' class='webSSearchy <$MTWebSSearchyService$>' onClick='return new WebSSearchy("<$MTWebSSearchyService$>",this.innerHTML, <$MTEntryID$>).request()'><$MTWebSSearchyTargetAlias$>::<$MTWebSSearchyQuery$></a>

You could use above tags instead of <MTWebSSearchyLink> tag when you want other designs. Its output will be like,

<a href='#' class='webSSearchy google' onClick='return new WebSSearchy("google",this.innerHTML, 123).request()'>Search::What is Web 2.0?</a>

By default, this plugin used <a> tag to call AJAX function. However if you want to use <input> or <button> to call it, you need to design tags like above using several tags.

Anyway, in order to call AJAX javascript function to get search results, you must call "return new WebSSearchy('service_name', 'target_name::query', 'entry id').request();"

Customization

Templates for search results

By default, each search results are display as <ul><li>Result 1</li><li>Result 2</li>...<li>Result 10</li></ul>. You can fully customize its display as you want.

For example, let's suppose you want to customize Yahoo's News search results using ordered list. Then open yahoo.cgi file. In the result template section of it, you can customize yahoo_template_header, yahoo_template, yahoo_template_footer varialbe. In template_header and template_footer, you can use __TARGET__, __TARGETALIAS__, __SERVICE__, __SERVICEALIAS, __QUERY__. In template body, you can use each target's vocabularies and __EVENODD__, which produce 'even' or 'odd' word as its resulting order.

What is target's vocabulary? For example, Yahoo's shopping search results have 'ProductName', 'PriceTo' fields. Yahoo's News search results have 'NewsSource' field. Generally speaking, each target has its own vocabulary. These are defined in yahoo_vacabulary variable in yahoo.cgi. As a result, we can display 'NewsSource' in results of news search. This vocabularry have to be presented like '__NEWSSOURCE__' in template.

Alias name

The service name('google', 'yahoo', 'naver') and target name('search', 'image', 'news', and so on) must not be changed. It is used for internal processing. Specially the service name is used as its CGI name. The 'google' service use 'google.cgi' file.

We can customize service/target's alias name. Each alias name can be used in localization of service/target name. For example, in german 'Suche'(means search) can be used as target alias. Then in (mt home)/plugins/alogblog/webSSearchy.pl(if you use Dynamic publishing, php/plugins/init.alogblog-webSSearchy.php file) and its CGI file, you must synchronize it.

Cacheing the results

Each (google|naver|yahoo|mt).cgi use cache mechanism. The result of search with one query will not frequently changable. You can set cache_life to each target differently. For example, the result of Yahoo's News search might be meaningless after more than one or two days. So cache_life of Yahoo News is set one day. But other general search results might not be variable in two or three days. So we cache its results and show visitors it. Also we can set cache_max_size. Its unit is record number. Each service has its own cache file. By default 300 query results are cached.

And others

Each web service provide its own search parameters. Those are defined in its CGI file. If you have time, you can browse its variables and customize it as you want.

Notes

You don't have to display "webSSearchy" in webSSearchy search links like me. <h3>webSSearch</h3> in Individual Entry Archive is just an example. If you run book-related blog, you can design it like "<h3>More books in web space?</h3>". No requied to use my selection.
Other web service APIs can be used with this plugin. If you made some CGI, please let me know. If you are a developer and see its CGI working, I believe you can easily make other service CGI.
There are many open tooltip scripts. I applied one which is called ArekorePopup. You can see its presentation in below webSSearchy section. I used it in a result related with image. Its usage is very simple. Download and unzip it. And then include two lines, <link href="/paths/ArekorePopup.css" rel="stylesheet" type="text/css"/>
<script src="/paths/ArekorePopup.js" type="text/javascript"></script> into your Indiv. template's header. By default, it display tooltip of all elements which have "title" attribute.
If your language uses multibytes UTF-8 enocoding and an error occurs in google.cgi when a search query is of your languages, you could use PHP version, google.php which uses NuSOAP library. Download this and move all into webSSearchy/ folder. Customize google.php and replace original webSSearchy.js with this one.

License

Relased under the Creative Commons License.

Version History

3.2.01 : PHP version of Google API included.
3.2.01 : First release.

Comments

As a developer working with MT for the past four years almost, this looks terrrific.
However, your instructions:
"From now on, I assume that webSSearchy/ folder was moved into under web root folder."
??? /cgi-bin/plugins/alogblog/*cgi files folders in there are /config /lib /temlate

"Open http:/ / your_domain/webSSearchy/check.cgi in browser."
http:/mydomain/cgi-bin/plugins/alogblog/webSSearchy-check.cgi is where it is.

websearchy-check.cgi (not check.cgi) says:
SOAP/Lite module not found or installed in your system.
YET
extlib/SOAP/ ,,,is right there

"Open google.cgi file. In the required section of it, two variables ($apiKey and $wsdl) MUST be set."
$wsdl) MUST be set. Where? No place there to set it.

"Open webSSearchy/mt.cgi file. Change two variables, $service_alias and $mt_search_url."

$mt_search_url Not found
$service_alias Not Found >> webSSearchy-mt.cgi ??

At this point I gave up.

Whats the secret and why the difference between instructions and results?

Thank you

Hi
I will check your comments, before that, this entry/plugin is for MT 3.2 version.. Do you recognize that? (New version is in another entry.) This version for MT 3.2 is a little clusmy, I think. Anyway I will check that tomorrow. Now is for me to go to bed(am 4:25). Please wait a little.

Posted by: bruce21 | October 21, 2006 12:51 AM

Also:
link rel="stylesheet" href="/webSSearchy/webSSearchy.css" type="text/css" />
script src="/webSSearchy/webSSearchy.js" type="text/javascript"/script
There is no such folders in your download, and no webSSearchy.js anywhere???

I doubt you downloaded webSSearchy-3.3.01 version, but you saw old entry(this page) for webSSearchy-3.2.01. I admit my instructions is not well documented and English is not good. Sorry...

Posted by: bruce21 | October 21, 2006 01:08 AM

alogblog's MTy plugins

MT is empty. We can fill it with our imagination.

webSSearchy, a click-and-get Web Service consumer