OpenStreetBrowser/Plugins

This is a proposal for a system of plugins. A Plugin has a unique name. A plugin has a directory (namend after the plugin) with a couple of files. This files define the plugin, there can be several php and js files, as well as images and css files.

Example (a plugin called 'testplugin'):

testplugin/
testplugin/conf.php       -- basic configuration of the plugin like dependencies to other plugins
testplugin/code.php       -- the main code of the application - server side
testplugin/code.js        -- the main code of the application - browser side
testplugin/style.css      -- styles
testplugin/icon.png       -- an icon for toolbox/context menu/options
testplugin/lang_en.php    -- definition of ('en' for English) language strings

If a plugin doesn't have server/browser side code or no additional styles, the files don't need to be created. Only the file conf.php is mandatory. You have to enable plugins by adding them to the $plugins-variable in main conf.php.

In the code all global identifiers like functions, variables, classes, language strings, or styles should be called testplugin_something. Language Strings can be called 'testplugin:something', if no translation is found everything before ":" (including ":") will be omitted.

There's a vast library of available functions, classes and variables. Here's some documentation:

Configuration

There's a configuration for every plugin. It can contain specific variables, but also contains some strings with defines the plugin. These variables will be exported to JavaScript.

• $testplugin_active = true - set this to false to disable this plugin and all plugins which depend on this plugin. Plugins which are not listed in the global $plugins-var, but are depended on will be loaded automatically (but can be disabled with the active-var.
• $testplugin_depend = array("otherplugin"); - Defines that the plugin needs other plugins. They will be included before this plugin.
• $testplugin_tags = new tags(array("name"=>"Test Plugin", "author"=>"John Doe")); - Some tags which other plugins might need

API for plugins

Variables

map	Variable (JS)	The map
This is an OpenLayers map object. You can use it to interact with the slippy map.
current_user	Variable (JS/PHP)	To interact with the current user
Variable of type 'user'. $current_user->user_name - The identifier of the user $current_user->tags resp. $current_user.tags - offer the tags of the user.

Classes

tags	Class (JS/PHP)	A general tags object, for categories, osm objects or the user.
A tags object. Allows to query or change a tags object. set(k, v) - set the k to the following value get(k) - returns the value of a key get_lang(k[, lang]) - returns the value of a key in the specified language or the key itself (e.g. get_lang('name', 'de') returns either the value of key 'name:de' or 'name'. If lang is an array, returns the first matching language (set a key called 'lang' to the object to specify its main language). If no lang is specified the language of the data language of the current user is used. data() - returns all tags as an associative array parse(text) - parses tags into a string like "[ref] - [name];[name]". parse_lang(text[, lang]) - As parse, but with available translations.

Functions

lang(id[, count][, param1[, param2, ...]])	Function (JS/PHP)	Returns the specified language string
Returns the specified language string. id: Id as defined in the language file. If the id is not found in the language-definition, the id itself will be returned, but stripped of text before ':'. E.g. 'tag:name' => 'name'. There's a special syntax for 'tag:key=value', only 'value' will be returned. count: If available either a singular or plural string is returned. Just pass an integer value as count. Default: singular. paramX: Some strings allow additional parameters (like in printf). They can be passed as additional values
dom_create_append(parent, type[, root])	Function (JS/PHP)	Append an element of type 'type' to parent
E.g. div=dom_create_append(parent_node, 'div');
dom_create_append_text(parent, text[, root])	Function (JS/PHP)	Append a text node with text 'text' to parent
E.g. dom_create_append(parent_node, "Comment");
dom_clean(parent)	Removes all children of parent

Hooks

On certain actions in the code hooks will be called. You can register for a hook, then a provided function will be called with specified parameters. The first parameter will be passed per reference and can therefore be changed.

Functions:

• register_hook(hook, function) - Register for a hook. The function will be called when the event occurs.
• call_hook(hook, refvar, [var1, [var2, ...]]) - Fire a hook. The first variable will be passed per reference and can therefore be changed by the hooks. Other variables can be supplied as well.

Common Hooks:

• init (JS/PHP) - As soon as all code is loaded, init will be called. The API hooks will be called first.

Geo Object

(JS) Every geometric object (e.g. OSM-Object, a Marker, a Route, ...) should be a class extending the "geo object" class. Every geo object has to define the following properties:

• .id - an arbitrary string, identifying this object (e.g. way_1234, marker_123)
• .type - type of object (e.g. "osm", "marker", "route")

the following properties are optional, but if you need it, you should keep to the standard:

• .tags - A tags instance

the following functions should be provided:

• .name() - Returning the name of the object in data_lang
• .geo() - a function returning an array of OpenLayers features
• .geo_center() - a function returning an array of OpenLayers features

Example:

function test_object() {
  this.inheritFrom=geo_object;
  this.inheritFrom();

  // info
  this.info=function(chapters) {
    chapters.push({
      head: lang("test:title"),
      weight: -1,
      content: "foobar"
    });
  }

  // constructor
  this.id="test_1234";
  this.type="test_object";
}

function test_init() {
  var test=new test_object();
  new info(test);
}

register_hook("init", test_init);