CartoWeb 3.4.0 RC1
Download Now!


CartoWeb
Advanced Geographical Information System for the Web

What is the ToolPicker

The ToolPicker is a mini javascript framework to display dynamically on screen several dhtml tools.

Some tools come pre-included:

  • ColorPicker

The ColorPicker allows the user to pick a color. He/she can either pick it from a gradient map, use RGB or HSL slider, input RGB or HSL values , input an hexadecial value or pick it from a preselected list of colors. The color value is then returned to the main page.

  • SymbolPicker

The SymbolPicker allows the user to pick a symbol in a predefined list of symbols. The symbols are generated off the .sym file on the serverside of CartoWeb. The symbol is then returned to the main page.

Installation

To use the ToolPicker in a project, simply enable it in your client.ini configuration file, by setting toolPickerOn = true.

The ToolPicker requires the corresponding script, css and template in the cartoclient.tpl file.

In the header :

<link rel="stylesheet" type="text/css" href="css/toolPicker.css" />

In the body, preferably at the end :

{include file="toolPicker.tpl"}

These inclusions should already be available in the default template (cvs).

ToolPicker usage

The main ToolPicker function accepts 3 parameters, 2 are mandatory, the last is optional.

toolPicker( string tool_id_list, string tool_input_list [, string tool_output_list])
  • tool_id_list

You can initialize one or more tools at once. The tool_id_list parameter is composed of one or more numerical values, separated by comma and enclosed by quotes (or simplequotes). Example: '2' or '1,4' or '3,2,1'

The order of the id influes on the order of the tool panels when displayed on screen.

  • tool_input_list and tool_output_list

The script needs an input value and will return an output value. The input value is retrieved from an html input element. In the same way the output value is returned to an html input element.

The script needs as many input element id as initialised tools. If two tools are initialised (parameter tool_id_list), tool_input_list must also contain two input id. Ids are separated by comma and enclosed by quotes (or simplequotes). Example: 'return_id_tool_4,return_id_tool_2'
The first input id corresponds to the first tool id in tool_id_list.

A different id can be specified if the element storing the output value must be different from the element storing the input value. The same rule applies to tool_input_list and tool_output_list.

See Exemples of usage

Each tool also have some particularities:

ColorPicker

When a color is selected, the script will set the css property background-color of a div in the template accordingly to the color picked. The id of the div is based on the output element id (if it specified, if not, the input element id is used), to which a _d is added.
Example, if the input element id is return_color_12, the id of the div used to display the color will be return_color_12_d.

SymbolPicker

When a symbol is selected, the script will set the css property background-image of a div in the template accordingly to the symbol picked. The id of the div is based on the output element id (if it specified, if not, the input element id is used), to which a _d is added.
Example, if the input element id is return_symbol_12, the id of the div used to display the symbol will be return_symbol_12_d.

The SymbolPicker is used with CartoWeb3 outline plugin usually, but it also can be used without the plugin.


With outline plugin

In CartoWeb3 server_conf/yourprojectname/outline.ini file defines a list of symbols to use. For each kind of symbols you want to use:

pointSymbols = "circle, square, star [, anyothersymbol, ... ]"

All these symbol names MUST BE defined in the .sym file in server_conf/yourprojectname/.

If you want to add language support for the symbol name, add the following parameter in server_conf/yourprojectname/outline.ini:

pointSymbols.labels = "symbolname1, symbolname2 [, anyothername, ... ]"

These names will be used to translate into the chosen language using the gettext functionnality. Add the corresponding translations in the server .po files.


Without outline plugin (standalone use)

If you do not use the outline plugin, you will need to set the following javascript variable somewhere in your page:

<script type="text/javascript">
  /*<![CDATA[*/
    var imgPath = 'path/to/symbol/images/';
    var symbolType = 'type/of/image/files/'; //jpeg, gif, png, whatever

    var symbolNamesArray = new Array("symbolfilename1","symbolfilename2" [,"othersymbolfilename", ...] );

    var symbolLabelArray = new Array("symbollabel1","symbollabel2" [,"othersymbollabel", ...] );
  /*]]>*/
</script>

symbolNamesArray contains the list of filename to use for your images. symbolLabelArray contains the list of label used on screen for the symbols.

Create your symbol images and put them in path/to/symbol/images/. You also need to create hilighted versions of your images, give them the same filename but add the suffix '_over'. Exemple: symbol_1.gif -> symbol_1_over.gif Put them in the same folder.

Exemples of usage

toolPicker('4','outline_point_symbol')
this will call the symbol picker (id 4), the input id is outline_point_symbol, and the output id will be outline_point_symbol too

toolPicker('1','outline_point_color', 'color_return')
this will call the color picker, the input id is outline_point_color, and the output id will be color_return

toolPicker('4,1','symbol_input,color_input', 'return_symbol,return_color')
this will call the symbol picker and the color picker, the input id is symbol_input for the first tool (here the symbol picker) and color_input for the second tool (color picker), and the output id will be return_symbol for the first tool and return_color for the second.

Create new tools

You can add new tools.

Add the new tool name in the toolArrayRef array at the begining of the script.

var toolArrayRef =  new Array( 'colorPicker', 
                                'hashArray',
                                'pencilArray',
                                'symbolArray',
                                'yourTool');

Create the following four functions, these functions can be empty.

function yourToolInit(inputValue) { ... };
function yourToolSetup() { ... };
function yourToolReturn() {
    ...
    return someValue;
};
function yourToolDisplay(targetElm) { ... };

The Init function is used to set the incoming values. It is always called when the ToolPicker starts. It receives the input value recovered from the main page. The Setup function can be used to do all the actions you want. The Return function is used to return a value to the main page. The Display function is used to display something in the main page. It receives the id of the target element to use (something_d).

Add the following four function definitions:

functionList["yourToolInit"]=yourToolInit;
functionList["yourToolSetup"]=yourToolSetup;
functionList["yourToolReturn"]=yourToolReturn;
functionList["yourToolDisplay"]=yourToolDisplay;

These are needed because of the dynamic function call inside the framework, which do not use the eval() function to increase performances.

The width of the tool area available on screen is 245 pixel. Height is variable.

CartoWeb Wiki: HowToUseTheToolPicker (last edited 2020-05-29 08:40:57 by OliverChristen)

© 2002-2006 CartoWeb by Camptocamp SA - Wiki powered by MoinMoin