ConQuery

resources:	Home Installation Betas Source Code Screenshots/Tutorial
query plugins:	Repository Documentation CookBook Submit plugin
talkback:	Mailing List Bugs / RFE Comments Support / Discussion Members
related projects:	Mycroft NeedleSearch

Manual (draft)

The basics

   The functionality of ConQuery can be basically divided into two parts:
1. Query storage;
2. Query proccessing engine.
   Query storage is based on a set of small text files called "search plugins". This files describes the parameters of web service: it's URL, all input fields, character encodig and some other - in a special format very similar to HTML.
There are two types of such plugins: Mycroft (Mozilla search) stored in *.src files and ConQuery - stored in *.cqr files. Mycroft requires that all plugin files should be located in the same directory: ./searchplugins/ in mozilla or firebird working directory.
   Mycroft plugins can be found and installed here. ConQuery plugins can be manually saved to the /searchplugins/ directory from this page. It is not necessary to restart browser after installing search plugins. Every time user calls context menu of the prowser, ConQuery automaticaly detects both types of plugins, and shows them in the list under "Query to..." entry. You can hide undesired plugins by blocking them in ConQuery config dialog.
   When user executes one of the plugins, query proccessing engine grabs all supported params from the page you are curriently browsing (like selected text, url), parses the plugin file, substitutes plugins variables (if any) with appropriate data, and finaly submits query to web service. You can configure query before submitting by holding Ctrl key while executing.

Mycroft plugins notes

Conquery supports Mycroft plugins with only two exceptions:

1. Not well-formed plugin files are not supported:
- With unclosed SEARCH tag
- With <INPUT name="" user=""> instead of <INPUT name="" user>
2. ConQuery uses only SEARCH and INPUT tags since there is no need to <INTERPRET> or <BROWSER update=""> by ConQuery engine.
For more information on Mycroft's plugins read Mycroft spec

Example of typical Mycroft plugin

<search
name="Google"
description="Google Search"
method="GET"
action="http://www.google.com/search"
update="http://www.google.com/mozilla/google.src"
updateCheckDays=1
queryEncoding="utf-8"
queryCharset="utf-8"
>
<input name="q" user>
<input name="sourceid" value="firefox">
<inputnext name="start" factor="10">
<inputprev name="start" factor="10">
<input name="ie" value="utf-8">
<input name="oe" value="utf-8">

<interpret
browserResultType="result"
charset = "UTF-8"
resultListStart=""
resultListEnd=""
resultItemStart=""
resultItemEnd=""
>
</search>

ConQuery plugins

Although Mycroft doesn't work with page context and POST method, it is possible to write Mycroft-like plugin for ConQuery. The file structure is based on Mycroft format, except that you can define ConQuery variables in <INPUT>s and lists of values in <INPUT>s.
ConQuery specific plugins have ".cqr" extention in filename and don't interfere with Mycroft engine.

Valid ConQuery variables:

[:selection] - selected text. If no selection found, user will be prompted for input;

[:prompt] - always prompt user for text input;

[:text] - optional text. Unlike [:prompt], doesn't force ConQuery to bring up Query Config Dialog;

[:cliptext] - holds clipboard text;

[:source] - HTML source of active page _without_ surrounding <html></html>;

[:host] - HOST extracted from page URL;

[:url] - page URL;

[:title] - page title;

[:linkurl] - target of right-clicked url;

[:imgname] - file name of right-ckicked image;

[:imgurl] - full URL of right-ckicked image;

[:matched] - showif's regexp (see below) matches (with the parenthesized submatches, if any). Matches are accessible through [:matched:1]...[:matched:n] variable. [:matched] and [:matched:0] holds whole substring match, [:matched:1] holds matches of first capturing parentheses, [:matched:n] holds matches of n-th capturing parentheses. If regexp does not match anything in selection, the [:matched] will contain the whole selection and [:matched:n] - nothing;

<SEARCH> tag params:

name="name" - used as title;

description="service description" - used as description;

action="http://url_to_script" - full http address to CGI script. Can be combined with or even replaced by ConQuery variables: action="[:selection]" are valid construction;

method="POST/GET" - HTTP-METHOD;

queryCharset="charset name" (ConQuery 0.7 and higher) - for proper encoding of international characters. If omitted, UTF-8 will be used.

opentarget="any string" open query results always in the one, named tab/window.

openwin="valid Gecko params for new window here" forces ConQuery to open query results in the new window with given params i.e. width, height, scrollbars e.t.c. For info on window parameters available see: Mozilla reference. Prefectly works with opentarget parameter.

forcein="predefined target identifier" open query results in targets other then defined by general settings. Valid target identifiers are:

win_bg force to open in the new window, on background
win_fg force to open in the new window, focused
tab_bg force to open in the new tab, on background
tab_fg force to open in the new tab, focused
same_win force to open in the same window
sidebar force to open in sidebar !works for FireFox only!)

Prefectly works with opentarget parameter.

showif="regexp" - evaluates selection with regexp. Results are saved in [:matched] variable(see above). If plugin is hidden from context menu and regexp matched selected text, plugin will be shown. For test cases see: http://conquery.mozdev.org/iptest.html

ShowIfTarget="[:Valid_ConQuery_Variable]" - tells on which ConQuery variable ShowIf should perform regex search. If omitted, ConQuery uses value of [:selection] variable;

category="plugin category" - for Online Repository maker. If omitted, the plugin will be shown as "Uncategorized".

<INPUT> tag params:

Note: inputs can be omitted. Then ConQuery will treat such plugins not as forms but as simple link.

name - input name. If multiple inputs has the same name, ConQuery will group them into dropdown list for Query Config. The first input in group is used as default;

value - input value or ConQuery variable(s). Can be mixed with text;

grouptitle - is used to label dropdown lists in Query config dialog. If omitted name will be used;

label - is used to label dropdown list items in Query config dialog. If omitted name will be used;

Example of typical cqr plugin

# Status: Working Full
# ConQuery plugin
# by Vasa Maximov
#
# Language: en
#
# Created: Dec 1, 2003
# Last updated: Dec 1, 2003
#
# Known issues: None
#

<SEARCH
name="AltaVista translate"
description="Babel Fish Translation @ AltaVista.com"
action="http://babelfish.altavista.com/babelfish/tr"
showif=""
queryCharset="UTF-8"
method="POST"
>

<input name="urltext" value="[:selection]">
<input name="url" value="[:url]">

<input name="tt" value="urltext" label="Selected text" grouptitle="Choose source">
<input name="tt" value="url" label="This page">

<input name="lp" value="ru_en" label="Russian to English" grouptitle="Translate way">
<input name="lp" value="en_zh" label="English to Chinese">
<input name="lp" value="en_fr" label="English to French">
<input name="lp" value="en_de" label="English to German">
<input name="lp" value="en_it" label="English to Italian">
<input name="lp" value="en_ja" label="English to Japanese">
<input name="lp" value="en_ko" label="English to Korean">
<input name="lp" value="en_pt" label="English to Portuguese">
<input name="lp" value="en_es" label="English to Spanish">
<input name="lp" value="zh_en" label="Chinese to English">
<input name="lp" value="fr_en" label="French to English">
<input name="lp" value="fr_de" label="French to German">
<input name="lp" value="de_en" label="German to English">
<input name="lp" value="de_fr" label="German to French">
<input name="lp" value="it_en" label="Italian to English">
<input name="lp" value="ja_en" label="Japanese to English">
<input name="lp" value="ko_en" label="Korean to English">
<input name="lp" value="pt_en" label="Portuguese to English">
<input name="lp" value="es_en" label="Spanish to English">

<input name="sourceid" value="Mozilla-search">
<input name="doit" value="done">
<input name="intl" value="1">
</search>

Cooking with ConQuery

See samples of using this extension

Share your plugins with community

If you feel plugin you developed will be useful for others, we will be glad to see it in Repository. Keep in mind that your query will be used by many people and some of them are not so experienced as you. So before publishing your cqr check out a few things:

Carefully explore FORM you are writing plugin for. Be creative, get all possible functionality from it;
If possible let your plugin run with most frequently used inputs by default. See Google Advanced Search for example;
Define "label" and "grouptitle" attributes when necessary. It looks much friendly when someone tunes up your query;
Define "showif" only for specific and recognizable data like IP addresses, ISBN codes or something like that. No "\w+", please :)
Define "category". Rubricator is grows with plugins added, so define your own category if there is no appropriate in Repository;
You do NOT need to pack your cqr in xpi. Send it just as is - the Online Repository Maker will do all the rest necessary work.

When your plugin is ready, please send it to us. We'll put it into Repository ASAP.

mozdev.org

Projects

Resources

Community