The CucuMe system works through a pair of programs communicating through the Internet.
This note describes the client.
|
The client has a number of other duties in addition to the above.
In addition to the information presented here, your attention is drawn to the Style Guide. |
In use, a CucuMe user will use his browser
to select a web page to view, and the browser will load the page and display
it. These are the transactions (a) and (b) on the diagram at right, and they
are entirely conventional. But additionally, the CucuMe client will report the
page being selected to the CucuMe server (d), and the server will consult its
database and respond in turn with a list of "eggs" to be displayed at (e).
In essence, eggs are like HREFs or bookmarks. Each comprises a text string (the title) linked to a URL (the reference). When the user clicks on an egg, the main browser window (not the CucuMe client window) switches to the egg's reference.
Note that the CucuMe client software is distinct from the web browser. The client is hosted by a web browser or other web client, and works alongside it. Generally, it will be a plug-in or add-on to the host web browser, though other arrangements are possible. (For example we have developed client functions into bookmarklets, and we have integrated clients into browsers.)
The core functions of the client are:
Additional functions of the client include:
The CucuMe client will, in general, be installed from an on-line source. All validated clients will be offered on the CucuMe website. Additionally, clients may be offered via proprietary websites (such as Mozilla's Firefox resources site) or shareware libraries.
Installation should be simple and quick, and once begun should require no user-interaction (apart from, possibly, language selection, where preferred language cannot be ascertained from the installation computer's language settings - see section 7). Once installation is complete, the client should be enabled (see section 6.4) and a message presented to the user describing how to reach the user options control surface (see section 6).
Clients must check periodically for available updates. All updates will be provided, in the first instance, on the CucuMe website. Update options are as described in sections 3.1.1 and 5.5. Updates must be able to run automatically, and previously-enabled user-preferences must be preserved across updates. Each successful or unsuccessful update must be notified to the user.
Generally speaking, every website should be displayed in largely the same manner no matter which browser is displaying it. Nevertheless, web users with certain types of disabilities will need specialised rendering, and specialised software exists to fill their need.
Similarly, it is important that CucuMe results are presented identically no matter what client is being used, and no matter what browser the client is hosted by. Additionally, it is important that the results should be presented in manner consistent with any special accessibility requirements which a user has specified.
For that reason, all CucuMe clients must follow this specification. Clients will be validated and accepted for use based on compliance with these requirements. Please see separate notes on validation and certification.
The CucuMe eggs lists must be provided to the user in at least one of the following forms. The use of multiple forms is encouraged. The forms are listed in decreasing order of preference (i.e. a menu must be provided, a sidebar presentation must be used if at all possible), but it is recognised that different platforms will have different requirements.
Every CucuMe client must offer, in addition to any other control surfaces, a dedicated menu system which is accessible and operable entirely using keystrokes. The menu may appear integrated into one of the other forms (for example, as a button or a contextual menu inside the sidebar), as a dedicated top-level menu, as a popup system under the add-ons menu, or in any other form that makes sense.
The menu system must provide access to at least the following systems and commands:
Most host browsers are designed to operate on a computer screen, where real-estate and resolution are generally not significant limits. In this case, CucuMe results should be offered in a supplemental window, alongside the main browser window.
The supplemental window provides several advantages to the user:
There are two types of supplemental window:
| Sidebar: Many browsers offer a sidebar to depict off-page information such as browsing history, bookmarks, or RSS feeds. Examples of such browsers include MS IE6 and 7, Firefox 1.5.x and 2.x, and others. In addition, it is now an accepted form for a website to present menu, navigation, and control information in a bar to the left of the main page. In general, users understand that the more leftward a vertical panel appears, the more "meta" will be the information presented in it. For these reasons, where a sidebar facility is present in the host browser, a CucuMe client must provide an option to present results sets in the sidebar. |  |
|
 |
||
| Popup window: Where the host browser does not provide a built-in sidebar facility, and where the host browser or the platform has an established culture of showing supplemental information in popup windows (such as Safari) it is acceptable to present the results set in popup window instead of a sidebar. | ||
 |
||
|
In either case, the supplemental window must be shown and hidden in the same manner that the host browser shows or hides any other built-in supplemental window (see right). Furthermore, if the built-in supplemental window provides for opening a link in a new tab or new window, the CucuMe supplemental window should offer the same facility. |
||
The supplemental window should show first the announcement if any (see section 4.2.1) followed by a series of eggs. The announcement should be drawn as unformatted text, wrapped to fit the available space, and should be presented in a distinctive typeface or style, or set off in some other way, to clearly distinguish it from the following eggs. Eggs are shown one per line, ranged left and truncated from the right. Detailed description of the layout of the eggs is given in section 3.2.
The CucuMe server request includes a facility to limit the number of responses to some number (see section 4.1.2). A supplemental window should estimate the number of eggs which can be displayed in the height of the window, and request only this number. (It is important for the ranking algorithms that the server knows which eggs have been shown to a user). Avoid requesting more eggs than can be displayed in the height of the window.
Some browsers do not lend themselves either to supplemental windows or to conventional menu use. Additionally, many "conventional" browser users prefer to switch off sidebars, in order to give more screen real-estate to the pages they're viewing. On-page display must be used where the output resolution is too limited to offer a sensible sidebar (e.g. PDAs), where the input controls are very restricted (e.g. TV remote controls), or where the browser is restricted in some other way. It should be provided as an option on all screen-based browsers.
Here's how on-page display works: Recall; after a webpage is requested by the browser, the CucuMe client sends a request to the server. The server responds with content as described in section 4.2. If the response contains no eggs, the CucuMe client takes no further visible action (though it should obey as normal any commands in the response).
If eggs are present, an icon is placed on
the screen, over the third-party webpage. The icon provides the following
functions:
The icon is provided in the files www.cucume.com/resources/onpage-icon.png and www.cucume.com/resources/onpage-icon.gif - there is no jpeg option. You should use whichever gives a better result on the browser you're using. In exceptional circumstances (very small screens, such as PDAs) you can reduce the size of the icon.
Do not download the icon on each use: the icon should be cached by the client. Check for updates using the normal update schedule (see section 6.5).
The icon
should be placed in a fixed DIV, at screen location 0,0 (that is, it will not
move as the screen is scrolled). If selected using either a mouse click (or
mouse hover), or a keystroke, it will display a popup frame or menu
comprising:
|
There are situations where a user may not be able to watch the screen intently: PDA users who are involved in other activities may rely on sound cues, and users who are watching streaming video or other animations may not notice actions taking place in spaces outside their attention. For that reason, if at all possible, a client must offer an option to deliver a non-visual cue whenever a new, non-empty eggs list is received - see section 5.4. If the hardware permits, options may include playing a sound, vibrating the device, or activating some other device. The standard CucuMe alert sound is provided in the file www.cucume.com/resources/cucu.wav. Do not download the sound on each use: the sound should be cached by the client. Check for updates using the normal update schedule (see section 6.5).
Fundamentally, each egg is like an HREF or a bookmark. It comprises some text and a URL. When the user clicks on an egg, the main browser window is directed to the egg's URL.
Within their allotted space (menu, subsidiary window, or on-page popup), eggs must all appear in the same standardised format.
Each egg is depicted as a single line of unformatted text, the content of which is the title of the egg (see section 4.2.2). All lines are of equal height. Eggs are left-ranged within their space. If an egg is too wide to fit in the available space, it is truncated from the right, and a tooltip is used to display the entire text (along with textual versions of the properties - see section 3.2.2) whenever the mouse hovers over it or focus is set to the egg using keyboard navigation.
In addition to their title, eggs must be prepared to depict a number of properties. There are a number of standard ways of depicting these properties which may be used singly or in combination. In decreasing order of preference, they are:
The "Hot" property depicts that CucuMe has determined that this link seems to be more popular or significant than others in the list.
Icon: www.cucume.com/resources/icon-hot.png or www.cucume.com/resources/icon-hot.gif
Style: Bold
text in red (#FF0000) e.g.
Click me
Character
icon: Bold "!" in maroon
(#800000)
Tooltip Text: "Hot"
The "Sponsored" property indicates that the owner of this link has improved its rankings in the list by a payment of some kind.
Icon: www.cucume.com/resources/icon-paid.png or
www.cucume.com/resources/icon-paid.gif
Style:
Background light green (#B0FFB0) e.g.
Click me
Character
icon: The system-set currency symbol, bold. e.g."£" in dark green (#004000)
Tooltip text: either "Sponsored" or "Paid"
Most modern computers have facilities to set system-wide options which fix the colours or magnification of screens to assist in readability. Any CucuMe client must respect such settings, and depict visual information in accordance with the system-wide preferences set by the user. In addition, as described in section 6.4 there must be a user preference to increase or decrease the size from the baseline size determined by the system preferences. Under no circumstances should text be rendered at a height smaller than 16 pixels (the size of the property icons).
Some computer users are unable to use a display screen at all. Generally they know who they are, and have special software which enables textual content (such as web pages, menus and alerts) to be read aloud. To enable such software to work, you must ensure that all textual content is depicted using standard textual forms.
Communication between the client and the server takes place over an HTTP link, through a GET or POST request. The server is available on port 80 at eggfactory.cucume.com. The response format is defined by the path. Thus:
http://www.cucume.com:2219/html?<query string>
The commands are declared below as either single or multiple.
Any or all of these commands can be delivered either in the query string or in the HTTP header (i.e. either GET or POST). The headers are interpreted first, followed by the query string.
For some formats, there is a minor addition to the HTTP protocol to handle snoop signals - see section 5.1.
| Cmd: url=xxx | Default: n/a | Single, Required |
Every server request should identify a third party webpage. The protocol, the domain, the path (if any) and the query string (if any) are all required. The url should generally be URL-encoded, though plaintext strings are acceptable so long as the total request is unambiguous. Examples:
A server request which does not identify a webpage or identifies a webpage which is not publicly accessible will result in a response comprising a well-formed structure (see section 4.3), and containing announcements (section 4.2.1), but not containing any eggs.
| Cmd: lines=xxx | Default: 10 | Single, Optional |
Generally, the CucuMe server will not serve all the eggs it has for a third-party webpage. Instead the client can ask for a specific number n, and the server will select the most appropriate n eggs.
Where the height of the CucuMe client frame is fixed (for example, when using supplemental windows (section 3.1.2), or when displaying on-page (section 3.1.3)), the client should estimate how many eggs will fit in the height of the window and ask for just that number. Where the eggs are being displayed in an unlimited space (for example, on a menu or being read to the user) the number should be defined by a user preference - see section 6.2.
The server is guaranteed to serve at most n eggs. It may serve fewer, or none at all.
| Cmd: wn=xxx | Default: none | Single, Optional |
The HTML and AJAX response formats express eggs as HREFs. Where the results are displayed in a window other that the main browser window, clicking on an egg must change the location of the main window, not the supplemental window. For that reason the HREFs returned in the format must have a target field specifying the main window.
If a client provides the name of a target window in the CucuMe server request:
| Cmd: cid=xxx | Default: none | Single, Optional |
In the same way that it can be useful for a website to know the identity of the browser which it is serving, it is useful for the CucuMe server to know the identity of the client it is serving. In particular, a snoop signal (see section 4.2.3) will only be sent to a client which declares a validated CID (or to the special test CID, see below)
A Client ID comprises three parts separated by the forward-slash character: A textual name, followed by a version number, followed by an optional Unique ID.
Example:
The CID should generally be URL-encoded, though plaintext strings are acceptable so long as the total request is unambiguous.
Except in exceptional circumstances, the CID should be reported in the HTTP header. A validated CID must be reported in the HTTP header.
For testing purposes, the following CID may be used:
More details about the test CID are provided in section 5.3
The Test CID is not intended for general release, and it is emphatically not an alternative to verification. The test CID will be changed at regular intervals.
| Cmd: was=xxx | Default: none | Multiple, Optional |
Where the browser location is set to a webpage which redirects the browser using a 301 (Moved Permanently), a 302 (Found), or a 303 (See Other) response code, the client will need to tell the server about it in order to enable it to select the most appropriate list of eggs.
Server requests should not be generated for every webpage in a chain of redirections. Instead, the client should wait for a webpage to generate some viewable content, and then make a request only for that page. However, all the other pages which have been redirected should be added to the request. Example:
then the client should generate the request
The server will respond with a list of eggs which is appropriate to the full set of reported pages.
| Cmd: has=xxx | Default: none | Multiple, Optional |
Where the browser location is set to a webpage which contains either a frameset or IFRAMES, the client will need to tell the server about it in order to enable it to select the most appropriate list of eggs.
It is not necessary to represent a frames structure exactly. It is necessary only to represent the list of pages which are depicted on the screen.
A new server request must be generated every time a new page is loaded into any frame.
| Cmd: lang=xxx | Default: user preference | Single, Optional |
It is generally good form to report the language preferred by the user - it helps the CucuMe server to select the most appropriate eggs. Use the abbreviated form as defined in section 7.
Every CucuMe server response contains the following kinds of information:
Announcements are short text strings which provide additional information about the eggs list, some property of the third party page, system-level announcements, or some other information about the request. Announcements should be shown as unformatted text before the list of eggs.
Eggs are the purpose of the system. They are short strings of text (the title) associated with a URL (the reference). They also have associated properties (described in section 3.2.2) Generally speaking, they resolve to HREFs. Like bookmarks, they are shown in a space conceptually distinct from the browser window, and clicking on an egg changes the main browser window rather than the client space.
On rare occasions, the CucuMe server will ask a client to report the contents of the third-party webpage which the browser has downloaded. This is an anti-cloaking feature. The full Snoop protocol and response is described in section 5.
A client can request the CucuMe results set in any one of a number of forms. The actual format is defined using the path. Thus:
http://eggfactory.cucume.com/<format>?<query string>
The XML format provides pure content in a platform-independent form. The client is responsible for all rendering and formatting.
Use http://eggfactory.cucume.com/xml?<query string>
Typical response is as follows:
<cucume version="0.2"> <snoop>url</snoop> <announce>announcement</announce> <item> <title>title</title> <link>url</link> </item> <item> <title>title</title> <link>url</link> <hot/> </item> <item> <title>title</title> <link>url</link> <sponsored/> </item> </cucume>
The snoop entity, if present, (see section 5) will give the name of the url being looked-up, one of the urls on the redirection chain, or one of the URLs in the frame system - see sections 4.1.5 and 5).
The HTML response format provides a fully-formatted webpage which can be displayed by a browser as-is. All eggs are shown as HREFs and are correctly formatted for display. The wn command is honoured (see section 4.1.3).
Snoops are signalled by a meta tag of the form <meta name=snoop" content="url">. The snoop entity, if present, (see section 5) will give the name of the url being looked-up, one of the urls on the redirection chain, or one of the URLs in the frame system - see sections 4.1.5 and 5).
Use http://eggfactory.cucume.com/html?<query string>
The AJAX response format provides a DIV of class cucume-list containing HTML which can be incorporated into some other page through DOM manipulation. All eggs are shown as HREFs and have styles set appropriate to their properties. The wn command is honoured (see section 4.1.3).
Snoops are signalled by adding an empty div whose class is snoop and whoseID is the URL of the page to be snooped. The snoop entity, if present, (see section 5) will give the name of the url being looked-up, one of the urls on the redirection chain, or one of the URLs in the frame system - see sections 4.1.5 and 5).
Note that there is no formatting incorporated in the response: suitable CSS must be added to the document. Example CSS is available at www.cucume.com/resources/cucume-list.css.
Use http://eggfactory.cucume.com/ajax?<query string>
Typical response is as follows:
<DIV CLASS="cucume-list"> <DIV class="snoop" id="url"></DIV> <DIV> announcement <UL> <LI><A HREF="url">title</A> <LI><A HREF="url" CLASS="hot">title</A> <LI><A HREF="url" CLASS="sponsored">title</A> </UL> </DIV> </DIV>
The CSV format is an alternative to the XML format, in that it is a platform-independent content-only form. The client is responsible for all rendering and formatting.
Use http://eggfactory.cucume.com/csv?<query string>
Typical response is as follows:
<Snoop>,<Hot> ,<Paid> ,<URL>,<TITLE> url, , ,, ,false ,false ,url,title ,false ,true ,url,title ,true ,false ,url,title
The first line describes the field names, then subsequent lines indicate responses. A client must read and validate the field names: later versions of CucuMe may add further fields. Trailing spaces are not significant, and neither field names nor field values are case-sensitive: "true"="TRUE"
Requests should be sent to the CucuMe server each time a new webpage is loaded, only when at least one of the following is true:
Results should be cached: no more than one request should be sent in respect of any page (though see the Refresh user preference: section 5.3).
Some browsers offer a tabs facility (e.g. Firefox or MS IE7). In this case each tab should cache its own result set. Tab changes should not create spurious server requests. (Of course, changing to a tab which does not have a cached results set should generate a server request.)
Snoop is an important part of the CucuMe anti-cloaking measures. Generally, the CucuMe robots will download pages from a website for analysis, but it is possible for websites to detect our robots, and deliver different content to us than they do to everyone else. Consequently, when a browser downloads a page from a site which we suspect may be cloaking, we may ask the client for a copy of what the browser has received.
Snooping uses a minor addition to the standard HTTP protocol.
Under normal circumstances the client will open an outgoing socket to the CucuMe server, and send the request using the standard HTTP protocol as defined in section 4. The client should send the entire request in a single block, and the proper use of the Content-Length field is encouraged. After sending the message header and body, the client indicates its willingness to respond to a snoop request by leaving the socket's output stream open.
If the response contains a snoop signal, and the snoop permissions permit it (see section 6.1), the contents of the page identified by the signal (including all HTTP headers) are copied to the outgoing socket.
Note that, after sending a snoop request, the server will timeout and abandon the socket after about three minutes. However, once the client commences sending the snoop request, only very short periods of idle are permissible. Consequently the copy must happen after the complete text of the page has finished downloading (though any assets used by the page such as pictures, sounds, styles, applets, etc are not returned by the snoop, and need not have been downloaded).
Finally and in any case, the client closes its socket.
Be aware that, where the page being viewed lies at the end of a redirection chain, any page in the chain may be snooped. If a page containing a redirection is snooped, you have the option to transmit only the headers, and leave the body blank. You should check that the URL specified by the snoop request is genuinely the url the user is looking at, is one of the URL:s on the redirection chain, or is one of the URLs in the frame system.
In order to preserve confidentiality, certain information must not be transmitted in response to a snoop signal:
Please also see the snoop user preference settings at section 6.1.
There is a special Client ID which you can use to test the snoop functionality in a client, described in section 4.1.2. When you declare the test CID, and where the response format supports it, every server request will generate a snoop signal (section 4.2.3). Additionally, an egg will be generated which will echo back to you the response you made to the snoop signal. In this way, you can check that your response to the snoop signal is correct.
Every client must provide access to a set of options, which will be accessible through the standard add-in menu system or a clear control embedded in the CucuMe client's control surface. Options are persistent across invocations of the client, and must include at least those detailed below.
Options are per-user where a machine is designed to handle multiple login accounts, and per-machine otherwise. All settings must take the default values listed unless and until over-ruled by the user.
Options dialogs should provide a basic explanation of what each option means. See section 7.1 for detailed text.
The snoop settings are a privacy option, and define the behaviour when the client receives a snoop request. There are two variables:
Snoop Secure sites (https): Options [yes, tell me, ask me, no]: default ask me
Snoop Unsecure sites (http): Options [yes, tell me, ask me, no]: default ask me
For each variable, the settings mean
Note that the setting for unsecure sites should never be more restrictive than the settings for secure sites (that is, if secure sites are set to tell-me, unsecure sites must be tell-me or yes.). If a user action creates a configuration that violates this rule, the user action should be honoured and the other variable should be automatically adjusted to match.
The list size setting is used where the height of the CucuMe client's display is undefined (for example, a menu or a spoken output). It defines the maximum number of eggs that will be returned by the server.
List size: positive integer: default 10
Any integer greater than zero is acceptable, but very small values (less than 3) or very large numbers (which would give lists taller than the height of the screen) should be queried. Negative numbers, zero, or strings which don't represent positive integers should be rejected, and the text entry box returned to the last valid value.
This option defines the behaviour of the client when a webpage is reloaded.
Refresh on reload: boolean: default false
When true, reloading a page triggers the CucuMe client to request another eggs list for the page. When false, the client uses its previously cached list.
The display options contain a list of switches to enable and disable the various display and announcement modes offered by the client.
Naturally, only those modes offered by the client should be depicted here. Equally, all modes offered by the client should be depicted here, even if those modes have other controls (e.g. a CucuMe sidebar can be selected from the view..sidebar.. menu). Where a mode has multiple controls, all the controls should reflect the actual current state of the mode.
Options may include, for example:
Show sidebar: boolean: Show CucuMe window: boolean: Show On-page eggs: boolean: Show eggs in menu: boolean: Play sound when eggs arrive: boolean: Text size: option [v-small, small, normal, large, v-large] default: normal
At least one option should be on by default.
Switching off all the options should alert the user to the fact that the CucuMe client is now disabled. Additionally, both the play sound option and the text size option should be grayed.
Both the client's program code and the various resources which the code uses are subject to regular updates. The client should check for updates at regular intervals. These options control that process.
Check for updates every: Options [day, week, month, three months]
When updates are found: Options [install immediately, ask me, don't install]
Updates will be checked after the specified time period following the previous check, and only while a connection to the Internet exists (i.e. there should not be an automatic dial-up). It is acceptable to check only when the client is active.
If the second option is set to
There should also be a "Check now" button to find whether an update is available. If not, inform the user. If so, ask me. This button overrides the automatic settings.
The language should be set during installation. At any time subsequently, the language can be changed. Full details are given in section 7.
Once a language has been set, there should be an option to display the author(s) of the string tables which have been installed (see section 7.3.3). All the authors of every string table should be identified, in order of decreasing specificity: thus:
| fr-ca: | Author 1 Author 2 |
| fr-xx: | Author 1 Author 2 |
| en-xx: | Author 1 |
It is expected that the CucuMe system will be used in many different languages. In order to relieve programmers from the overhead of creating and managing all the translations, and in order to provide ongoing language support to legacy software, CucuMe is providing all the string tables as general assets.
The language assets are provided on-line and comprise two parts: the language index, and a series of local string tables. During initial installation, and while changing the Set Language user preference, the list of available languages should be taken from the language index (see section 7.2), and selecting a language should download the appropriate string table to the users machine.
In the language preferences control surface, ensure that the multiple-language
The language index resides at www.cucume.com/resources/locale/index.xml. It is a list of language names and references to the files containing the string tables themselves. Example:
Primarily, the client works alongside the
web browser, monitoring the user's browsing. Each time the user navigates to a
page, the client sends a message to the server, requesting some additional
information about the webpage being navigated-to. On receipt of the
information, the client prepares it and displays it to the user. The user's
view of the process is shown at right.<CucuMe-language-index>
<language>
<code>en-gb</code>
<name>English - UK</name>
<file>en-xx</file>
</language>
<language>
<code>en-us</code>
<name>English - US</name>
<file>en-xx</file>
</language> <language>
<code>fr-fr</code>
<name>Français - France</name>
<file>fr-xx</file>
</language>
</CucuMe-language-index>
Within each language:
Do not download the language index on every use of the client: the language index should be downloaded only (and every time) the user enters the Set Language control surface
String tables reside in unicode text files located at www.cucume.com/resources/locale/<filename>.txt. A fragment of the file en-xx.txt would typically be:
general section Yes: Yes No: No tellme: Tell Me askme: Ask me updates section updChkNow: Check for updates now updChkEvr: Check for updates every: updIntDay: Day updIntWk: Week updIntMnt: Month updIntQtr: Three months
For comparison, the file fr-xx.txt would contain:
section genérale Yes: Oui No: Non tellme: Dit-moi askme: Demande-moi
As can be seen, the table comprises a series of lines representing the string table. These lines are grouped into sections (for convenience: the section names have no meaning). Blank lines are ignored.
Each string table entry comprises
Do not download the string table on every use: the string tables should be checked according to the normal update schedule (see section 6.5)
The current set of supported strings will always be available in the file en-xx.txt. You can safely use any strings which are identified here. However, it is not guaranteed that all strings appearing in en-xx will appear in all the other language files. Thus, when building the local string table, you should derive each string thus:
Check for updates to the language files regularly: We will try to keep the language files synchronised.
Generally speaking, the strings presented in the string tables should be adequate for your needs. Where you need strings which are not in the string table, you must not add them to your code literally - if you do, your code will not internationalise. Instead, please contact us to create a new string table entry. You should identify:
We will always accommodate sensible requests.
Every string table may contain a credits section which identifies the author(s) of a file. All author credits (there may be more than one) have a string name of author
Note there is a user option to show authors at section 6.6.