#####################
How to write a widget
#####################

What is a widget?
=================

A widget represents a user interface element. Mostly this will be elements
added to the sidebar.

Structure of a widget
=====================

Each widget is represented by a folder inside the swfm document tree. This
folder has following structure:

* **swfm/widgets/WIDGET_NAME**
    * **plugin.js** - contains the code of the widget
    * **locale/** - folder that contains files with translated strings

First steps
===========

Here is a very simple example:

.. code-block:: javascript

	(function() {
	    //create a new widget
	   var exampleWidget = {
	        //initialize the widget
	        init: function() {
	            /*
	             * ... your code here ..
	             */
	        }
	    };
	    //register the new widget
	    SWFM.Widget.register('example', exampleWidget);
	})();


Naming conventions
==================

The name of the directory of the widget and the string (first parameter) in
*SWFM.Widget.register* have to be identical. This is also the name to
load the widget (see :ref:`example config <frontend-config-example>`).