============================
 Build Your Locale Driver
============================
Creating a custom locale driver involves a few steps that should feel like a relatively easy task for a PHP programmer.  Basically, your new driver needs to implement the only abstract class defined in the ``Locale.php`` file, that is ``org_geoprisma_locale_Locale`` and its abstract public function ``getTranslation(args)``.  Once defined, you then set GeoPrisma to use your new driver.

See the ``GetTextLocale`` driver for an example.

1. Create a new PHP class which extends ``org_geoprisma_locale_Locale``

   .. code-block:: php
    
    <?php

    class your_custom_locale_driver extends org_geoprisma_locale_Locale
    {
       ....
    }
    
    ?>

2. Implement the ``com_borealis_foundation_util_Singleton`` abstract function in the constructor of your new class.      

   .. code-block:: php
    
    <?php

    class your_custom_locale_driver extends org_geoprisma_locale_Locale
    {
        private static $s_objInstance = null;

        private function __construct()
        {
           $this->setLanguage($this->getDefaultLanguage());
        }

        public static function getInstance()
        {

             if (is_null(self::$s_objInstance))
            {
            self::$s_objInstance = new your_custom_locale_driver_GetTextLocale();
            }
            return self::$s_objInstance;

        }

    }
    
    ?>

3. Implement the ``getTranslation`` function in your class.  This function receives two parameters : ``Message String`` and ``Domain Name``.  Your function opens whatever you decide it should open (database connection, XML file, .properties file, etc.) and returns the translated string matched.  For a driver that would use for example an XML file which would list message strings and translations without domains,  the ``getTranslation`` function implementation could care only about the ``Message String`` parameter and forget the second one.

   .. code-block:: php
    
    <?php

    class your_custom_locale_driver extends org_geoprisma_locale_Locale
    {
        public function getTranslation($pstrMsg, $pstrDomainName)
        {
            ....
               return matchedString;
            
        }
    }
    
    ?>

4. Set Geoprisma to use your driver [#ACLSetter]_



   .. code-block:: php
    
    <?php

    org_geoprisma_SettingImpl::setLocaleClass('your_custom_locale_driver');
    
    ?>

   P.S: Your driver class needs to be loaded before, or loaded in an autoload function like com_borealis_Autoload.php   
    
   .. code-block:: php
    
    <?php

    require 'your_custom_locale_driver.php'
    
    ?>

.. [#ACLSetter] The default locale driver used is defined in the ``Setting.php`` file.  It defaults to ``org_geoprisma_locale_GetTextLocale``.  The implementation resides in the ``SettingImpl.php`` class.  That class defines getters and setters, amongst which the setter for the locale driver : ``setLocaleClass``.  This is usually done in the ``common.php`` file.