How to create a new widget

Can’t find a certain feature you want ? You think that feature should be included ? You just saw a cool new tool in an external library ? Then, you can easily create and contribute it !

Simply follow this procedure when creating a new widget. This won’t tell you exactly what to do, but how to do it.

1) Plan your widget

List the things your widget should do. Look for similar functionnalities in existing web-mapping application to work from.

2) Inform the developers

Use the Developers mailing list to let the developers know of your intentions.

3) Create a ticket

Create a new ticket in TRAC with complete details of the new features the widget should have.

4) Directory

Create a new directory for you widget (must be in lowercase). That same name will always be use thereafter so choose it wisely. You can also create a Sub-directories structure.

5) Copy required files

Copy all files from the Sample widget to your new widget directory. Change their name respecting the case, for example :

• sample.php -> yourwidget.php
• Sample.xslt -> YourWidget.xslt

You might have copied the hidded svn folder too. Simply remove it if you did.

6) .php file (mandatory)

Edit the php file. Here’s what you need to change :

class name:

Change the class name to your widget name (case sensitive)

class action:

Set the widget action. Possible values are :

• create
• read
• update
• delete

type:

Set the widget type, which is the name of the widget in lowercase. If you use the Sub-directories structure, use the complete name (with ‘_’).

See also

Action

7) .xslt file (mandatory)

Make the following changes in YourWidget.xslt

Namespace definition:  

Define the namespace of your widget. Example :

xmlns:yourwidget="http://opensafemap.org/yourwidget"

Apply the namespaces to templates:  

Set the namespace of your widget to all templates (functions) in this file. Example :

<xsl:template name="yourwidget:printWidgetSource">

Included JS and CSS (optional):  

In the printWidgetSource template, you define the external js/css files your widget includes. Change the

<xsl:text>...</xsl:text>

portion for each external script/link your widget needs. Example (script) :

<script>
  <xsl:attribute name="src" >
    <xsl:value-of select="$g_widgets_url"/>
    <xsl:text>/yourwidget/YourWidget.js</xsl:text>
  </xsl:attribute>
</script>

Example (link) :

<link rel="stylesheet" type="text/css" >
  <xsl:attribute name="href" >
    <xsl:value-of select="$g_widgets_url"/>
    <xsl:text>/yourwidget/YourWidget.css</xsl:text>
  </xsl:attribute>
</link>

8) Globals.xslt file (mandatory)

The global file is located in the [your_geoprisma_dir]/src/client/templates/inc directory.

Namespace definition:  

Add a namespace for your widget. Example :

xmlns:yourwidget="http://opensafemap.org/yourwidget"

Extension prefix:  

Add the extension prefix of your widget to the

extension-element-prefixes

printAllWidgetSources:  

Locate this template and the following lines to it :

<xsl:when test="$WidgetType='yourwidget'">
  <xsl:call-template name="yourwidget:printWidgetSource"/>
</xsl:when>

printAllWidgetExecutions:  

Locate this template add the following lines to it :

 <xsl:when test="$WidgetType='yourwidget'">
   <xsl:call-template name="yourwidget:printWidgetExecution">
     <xsl:with-param name="pWidgetName" select="$WidgetName" />
     <xsl:with-param name="pMapName" select="$pMapName" />
   </xsl:call-template>
</xsl:when>

9) .js file(s) (optional)

• Skip this task if your widget doesn’t require any .js file.
• The YourWidgetName.js file should be used for namespace definition only, but it is not mandatory to do so.
• Create as much MyWidgetClass.js as you need, one file per class. This is not mandatory too, it’s just a sugestion of doing so.
• All theses files must be included in your .xslt file, in the printWidgetSource template.

10) .css file (optional)

If your widget needs any specific styling, put it in the .css file, else simply remove it.

11) Create one or more samples (mandatory)

Create a new sample demonstrating the use of your widget. If your widget has many options, create a sample directory with many sub-directories of your widget with the use of those different options.

See also

How to make a new sample

12) Template.xslt file (mandatory)

Edit your sample’s Template (XSLT) .

13) Config (mandatory)

Edit your sample’s Config . Use the yoursample.xml file to do so.

14) .rst file (mandatory)

Document your widget.

See also

http://sphinx.pocoo.org/