.. _how-to-make-a-new-sample-label:

============================
 How to make a new sample
============================

Step 1 - Create a new directory
--------------------------------
Create a new directory in the trunk/samples directory with your sample name

Step 2 - Make your sample
--------------------------
The following files need to be created in your sample directory : 

* index.php
* proxy.php
* common.php
* config.xml
* template.xslt
* other

Step 3 - sample.php
---------------------

To display your sample in the GeoPrisma samples list you need to create a file named sample.php in your sample directory.

In this file add one php class with name *sample_* + yoursample - **The class name needs to be unique for all sample**

Add this method

:getCat: Returns your sample category

    .. image:: img/howto/cat.bmp

:getText: Returns your sample name

    .. image:: img/howto/text.bmp

:getUrl: Returns your sample start link, relative to the samples directory

    .. image:: img/howto/url.bmp

:getIcon: Returns your sample image (116 x 90), relative to the samples directory

    .. image:: img/howto/icon.bmp

:getDesc: Returns your sample description

    .. image:: img/howto/desc.bmp

:getStatus: Returns your sample status, acceptable values are :

    * null
    * 'modified' 
    * 'experimental'
    * 'new'
    * 'updated'
    
    .. image:: img/howto/status.bmp
    
:getXML: Your sample config file, relatif to the trunk (null is your sample have no config)

    .. image:: img/howto/xml.bmp

:getXSLT: Your sample template file, relatif to the trunk (null is your sample have no template)

    .. image:: img/howto/xslt.bmp

:getDoc: Your sample documentation, relatif to the trunk in sphink build doc (null is your sample have no doc)

    .. image:: img/howto/doc.bmp
    




sample.php sample

.. code-block:: php
    
    <?php

    class sample_yoursample
    {
         // Category for your sample
         static public function getCat()
         {
            return 'Your sample widget cat';
         }
         
         // Name of your sample
         static public function getText()
         {
            return 'Your sample name';
         }
         
         // Url to start your sample, relative to the samples directory
         static public function getUrl()
         {
            return '/yoursample/index.php';
         }    
        
         // Icon that represents your sample, relative to the samples directory
         static public function getIcon()
         {
            return '/yoursample/sample.gif';
         }
         
         // Short description of your sample
         static public function getDesc()
         {
            return "Your sample widget desc";
         }
         
         // Status of your sample (null | 'modified' | 'experimental' | 'new' | 'updated')
         static public function getStatus()
         {
            return 'new';
         }
         
         // Your sample config file, relative to trunk
         static public function getXML()
         {
            return "/samples/yoursample/config.xml";
         }
         
         // Your sample template file, relative to trunk
         static public function getXSLT()
         {
            return "/samples/yoursample/template.xslt";
         }
         
         // Your sample documentation, relative to trunk
         static public function getDoc()
         {
            return "/dist/build/html/samples/list/yoursample.html";
         }
    }

    ?>        


Step 4 - Documentation .rst
----------------------------
You can build documentation for your sample using `Sphinx <http://sphinx.pocoo.org/>`_ `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ markup language

You only need to create a file with the name yoursample.rst - **File names need to be unique in all samples rst file**

yoursample.rst sample

.. code-block:: rst
    
    ============================
     Your sample
    ============================

    Documentation on your sample ...