	The Information Overlaid Toolkit: ; Referance Manual Edition 2.4, for Information Overlaid Version 2.4; 27th April 2004
Prev		Next

Chapter 12. Palette - The In-Browser Database

Palette is a library designed to allow you to construct interfaces which allow the user to sift through a large number of entries downloaded from a sever by selecting features of entries they are interested in. The mechanics of Palette are contained in the ii_palette.js library. A library ii_palette_results.js is also provided, this defines all of the functions ii_palette.js requires to format results. You can use this in your initial development and then replace it with functions which output results in the format you prefer.

The ``Housing Estate'' tutorial gives a good introduction to how Palette works.

`ii_palette.js`

palette_type_names = [name1, name2] ...: Names of the fields in each entry which should be treated as selectable fields (`types'). This will usually be set by a call to palette_start_entry_list.
palette_field_names = [name1, name2] ...: Names of the fields in each entry which should not be treated as selectable fields. This will usually be set by a call to palette_start_entry_list.
palette_marker_type = markertypeornumber: The type or image number for markers created for entries when palette_marker_index does not give a more specific one.
palette_marker_index[entrytype] = markertypeornumber: An array which gives a marker type or a number for each type of entry. If some entry's type is not assigned a value here, the value of palette_marker_type is used.
palette_painting_index[typefieldvalue] = [PAINTING DEFINITION]: If the value of any type field in an entry is given a value in this array, it should be a painting definition. All of the painting definitions relevant to an entry are combined and used for the marker for the entry. This allows colours in an image marker to be changed based on the types of the entry.
palette_marker_class = klass: Marker type used for all entry markers. Default is entry.
palette_main_type = name: For some purposes, for instance choosing a marker and sorting results, Palette needs to treat one type field as the most important one. This variable gives the position of that type in the call to palette_record_entry. The default is 3, ie the first type field.
palette_timeslot_type = N: If set, this parameter indicates that the indicated field is to be treated as the time of the entry.
palette_type_order[type] = N: If defined, this array should assign a number to each entry type. This will be used to sort the entries before displaying them. For more control you can define the palette_order_function callback.
palette_do_subheadings = trueorfalse: If true, the results list will be split up by type with subheadings.
palette_type_separator = sep: The character used to separate multiple values for one type field in an entry. The default is , (comma).
palette_load_window = window: The window or frame into which the entries will be loaded. Defaults to the window hidden.
palette_results_window = window: The window or frame into which the results list will be written. Defaults to the window results.
palette_labelling_field = N: The index of the field which will be used to label the markers, if labels are required.
palette_labelling_align = align: Alignment of labels, 0, 1 or 2.
palette_labelling_font = fontspec: Font for labels.
palette_labelling_dx = X palette_labelling_dy = Y: Offset in pixels of the labels from the normal position.
palette_set_selected(type, value, yesno): This is the basic function for setting the selection criteria. Note that if you use this the criteria can get out of step with the selectors the user is using. the palette_on_selected can be used to update the user interface if necessary, but in general the more specific functions below will be better.
palette_set_mode(field, mode): Set the mode used to interpret selectors for the given type field. The mode should be {{tok:AND,selection mode}}, {tok:OR,selection mode}} or {tok:IGNORE,selection mode}}.
palette_set_relevance(field, entrytype): Tells Palette that the given selectors should only be considered when looking at entries of type entrytype.
palette_set_all(form, field, yesorno): Looks at all the fields in form and any which are relevant to type field field will be turned on or off, as indicated by yesorno.
palette_update_from_form(form, update): Makes the selection criteria match the given form. If update is true the results list is regenerated.
palette_update_from_cb(checkbox, update): Set the relevant criterion from the given checkbox. Suitable for putting on the checkbox's onClick callback.
palette_update_from_sel(selector, update): Set the relevant criteria from the given selector. Suitable for putting on the selector's onChange callback.
palette_set_timeslot(timeslot, yesorno): Select the given timeslot.
palette_select_timeslot(timeslot): Select the given timeslot (and de-select others).
palette_toggle_timeslot(timeslot): Select or de-select the given timeslot.
palette_clear_entry_list(message): Remove all entries. If message is given it is displayed with palette_write_results_message.
palette_update_results_list(): Recreate the results list.
palette_start_entry_list([typefieldnames], [otherfieldnames], message): Called at the start of a loading list of results. The two lists of field names define the names for the fields in the following calls to palette_record_entry. The ones in typefieldnames will be available as selection criteria. Message, if given, is displayed with palette_write_results_message.
palette_record_entry(id, cx, cy, value1, value2, ...): Add an entry to the database. The values should correspond to the names in the call of palette_start_entry_list.
palette_end_entry_list(): indicates the end of the list of results. Causes the results list to be updated.
palette_highlight_entry(id): Highlight the indicated entry's marker.
palette_zoom_to_entry(id): In a mapping application, zoom to the most detailed map showing that entry.
palette_write_results_message(text): Displays a message in the results window.

Results Layout Functions

You must define the following functions to tell Palette how to display results.

palette_write_head(window): Writes the body tag for a page.
palette_write_foot(window): Writes the /body and any cleanup.
palette_write_results_top(window, num_entries, num_results, found_types): Called to write any text above the results list. The parameters are the window to write to, the total number of entries in the database, the number listed and the list of all types for which at least one entry is included.
palette_write_results_bottom(window, num_entries, num_results, found_types): Called to write any text below the results list. The parameters are as for palette_write_results_top.
palette_write_subheading(window, type): Called when a heading for a set of results. is needed.
palette_write_result(window, id, type, cx, cy, values): Called to write each result. The values parameter is an array giving values for each field in the entry.

Callbacks

The following callbacks can be defined to modify the behaviour of the system:

palette_on_selected(type, value, oldsetting, newsetting): Called each time a type/value combination is selected or de-selected.
order = palette_order_function(values1, values2): Return the order of the two sets of values. The result should be -1, 0 or 1, indicating the order the entries should be sorted into.

`ii_palette_results.js`

This library defines a simple set of result-output functions for Palette applications. By including this library you can put off writing your final set of functions while you get your application working.

palette_write_head(window): Writes the body tag for a page.
palette_write_foot(window): Writes the /body and any cleanup.
palette_write_results_top(window, num_entries, num_results, found_types): Called to write any text above the results list. The parameters are the window to write to, the total number of entries in the database, the number listed and the list of all types for which at least one entry is included.
palette_write_results_bottom(window, num_entries, num_results, found_types): Called to write any text below the results list. The parameters are as for palette_write_results_top.
palette_write_subheading(window, type): Called when a heading for a set of results. is needed.
palette_write_result(window, id, type, cx, cy, values): Called to write each result. The values parameter is an array giving values for each field in the entry.

Prev	Home	Next
The Search Library	Up	The Plotting Library