wiki:WidgetWritingGuide

This page gives the basics regarding how to write your own widget

Naming and placing your widget

All widgets are .php scripts that reside in the widgets subdirectory of the plugin, they should be prefixed with tpw_ in order to be read.

Note that since v0.8.0 those sub-widgets are implemented as PHP classes with static functions, this is a change in order to allow multiple instances of different sub-widgets in the same page

the first few bytes of the file should contain a plugin header in the same format used in wordpress plugins - for example:

/*
Plugin Name: Default
Plugin URI: http://transposh.org/
Description: Default widget for transposh
Author: Team Transposh
Version: 1.0
Author URI: http://transposh.org/
License: GPL (http://www.gnu.org/licenses/gpl.txt)
*/

files should reside in a specific subdirectory of the widgets directory.

You can also place .css and .js files using the same name, those will be automatically included (and can be overriden, see below).

The class should extend the transposh_base_widget class like:

class tpw_default extends transposh_base_widget

Functions available

Currently there are a few functions one can implement

static function tp_widgets_do($args)

the most important one is the tp_widget_do($args) which actually renders the html that the widget creates the args include a list of language records which have the following properties:

Parameter Example value Description
langHebrewThe name of the language in English
langorigעבריתThe name of the language in the language itself
flagilThe name of the flag file provided for the language
isocodeheThe two letter ISO code for the language
urlhttp://transposh.org/heIncludes a url that the language should go to
activetrue/falseBoolean that is true if this language is the current one

Sample implementation: Create a select box

static function tp_widget_do($args) {
  echo '<span class="' . NO_TRANSLATE_CLASS . '">'; // wrapping in no_translate to avoid translation of this list

  echo '<select name="lang" id="lang" onchange="document.location.href=this.options[this.selectedIndex].value;">'; // this is a select box which posts on change
  foreach ($args as $langrecord) {
    $is_selected = $langrecord['active'] ? " selected=\"selected\"" : "";
    echo "<option value=\"{$langrecord['url']}\"{$is_selected}>{$langrecord['langorig']}</option>";
  }
  echo "</select><br/>";
  echo "</span>"; // the no_translate for the language list
}

static function tp_widget_js($file, $dir, $url)

There are three Parameters:

  • $file contains the file name in relation to the widgets sub directory
  • $dir contains the plugin directory
  • $url contains the plugin url

sample implementation: Include the default .js, but make sure jQuery is also loaded

static function tp_widget_js($file, $dir, $url) {
  wp_enqueue_script("transposh_widget", "$url/widgets/dropdown/tpw_image_dropdown.js", array('jquery'), TRANSPOSH_PLUGIN_VER);
}

static function tp_widget_css(file, $dir, $url)

sample implementation: Include a given .css

static function tp_widget_css($file, $dir, $url) {
  wp_enqueue_style("flags/tpw_flags", "$url/widgets/flags/tpw_flags.css", array(), TRANSPOSH_PLUGIN_VER);
}

Using global environment

The complete transposh plugin object can be used within the widget, just make sure to include the following line:

global $my_transposh_plugin;

Normally there would be reason to do that

Last modified 5 years ago Last modified on 12/02/11 22:15:08