LangSelect Smarty Plugin
========================

Name:     LangSelect
Type:     class, compiler, postfilter
Version:  1.1
Date:     14 May 2003
Author:   Brodie Thiesfield <bt@jellycan.com>
Author:   Alejandro Sarco <ale@sarco.com.ar>
Licence:  BSD (see licence.txt)

Description
-----------
This plugin adds internationalization to any Smarty-based PHP application.
You keep all of your localized strings in different files separate to the 
actual templates.  It can internationalize straight text or generate 
localized text for a form select element.

Features
--------
* generate localized text 
* generate option lists with the specific language text inserted
* option lists are completely selfcontained within the compiled
  template, no extra files are included.
* the selected item may be dynamic or static
* option tags are output in XHTML 1.1 valid format
* different languages may be used for each option with the
  'lang' and 'xml:lang' properties being added as appropriate
  to those tags.

Files
-----
readme.txt
compiler.lang.php               Compiler function
compiler.lang_options.php       Compiler function
postfilter.langselect.php       Post filter function
langselect.php                  Class file

    
Installation
------------
1. copy the following files into the smarty/libs/plugins directory:
    compiler.lang.php
    compiler.lang_options.php
    postfilter.langselect.php

2. copy the langselect.php file into any directory that you can
   include it from.
   
3. where you create your $smarty object, load the postfilter
   using: $smarty->load_filter( 'post', 'langselect' );


Usage
-----
The option lists are generated in xhtml compatible format, and may include items
which are in multiple languages via the 'lang' tag, although to have multiple
languages in the same (x)html you will probably need to use unicode or utf-8 
encoding for the page.

1. Create the language dependent files with the option lists as an associative
   array. The items will be listed in the page in the same order that they are 
   supplied in the array. The key of the array is the 'value' attribute, the 
   value is either an array of (display text, language code) or just 
   'display text'.

   You have two ways of supplying this array:

   (1) Same language as the default language on the page. No lang or xml:lang
       attributes are added to the <option> tags.
       
        $ls['TEXT_NAME'] = 'Straight localized text';
        
        // normal option list, all items are in the same language as the page
        $ls['NAME'] = array( 
            'value' => 'select text', 
            'value' => 'select text', 
            ... );

        // example:
        $ls['ANIMALS'] = array( 
            ''     => 'Select...', 
            'dog'  => 'Inu', 
            'cat'  => 'Neko', 
            'bird' => 'Tori' );
    
   (2) Specify the language for the individual strings. In this case the lang
       and xml:lang attributes are added to the <option> tags for the items which
       have provided a language code.
       
        $ls['TEXT_NAME'] = 'Straight localized text';

        // multiple language option list
        $ls['NAME'] = array( 
            'value' => array( 'select text', 'language code' ),
            'value' => array( 'select text', 'language code' ),
            ... );

        // example
        $ls['OPT_UI_LANGUAGES'] = array(
            'en' => array( 'English', 'en' ),
            'ja' => array( '“ú–{Œê',  'ja' ),
            );
    

2. Insert into your template lines the function call in the following manner:

    {lang TEXT_NAME}
    <select name="select_name">{lang_options ... }</select>

3a. Options to lang are the name of the data item entered in step 1 or 2, eg 'TEXT_NAME'.

3b. Options to lang_options (in place of the '...' above) are as follows:
    
    options=NAME
        Required
        NAME is the name of the data array entered in step 1 or 2, eg 'NAME' or 'ANIMALS'
        
    selected=ITEM
        Optional
        ITEM is the value of the item from the array to be selected. This can have
        the following format:
        
        selected=$smartyVar     Select an item using a smarty template variable
            The smarty variable will be looked up every time the template is 
            displayed and used to dynamically generate the list with the 
            appropriate option selected.
      
        selected='LITERAL'      Select an item using a literal value. 
            The value in single quotes is the value of the option which will be 
            marked as selected (the options will be generated as a static list).
    
        selected=langVar        Select an item using a language dependent literal.
            The language dependent variable will be looked up at the time the 
            template is compiled, and used to generate the list with the 
            appropriate option selected (the options will be generated as a 
            static list).

    filter=FUNCTION
        Optional
        FUNCTION is the name of a function which will be called to determine if
        a particular option item should be displayed in the list. It's signature
        should be: 
            function FilterFunc( $optValue [, ...] )
        It should examine the $optValue parameter which is the value attribute
        of the option, and return either true or false depending on if the 
        option should be included in the list or not. Extra parameters may be
        passed to the function via the 'filter_params' member detailed below.
        
        If the list is generated as a dynamic list, then it will be called once 
        for every possible option in the list every time the page is displayed. 
        If the list is a static list, then it will be called for every possible 
        option in the list only when the page is first compiled. 
        
    filter_params=OPTIONS
        Optional
        OPTIONS is a string which will be pasted at the end of the filter function
        call. It is delimited by the first space, so the filter parameters cannot
        contain a space. For instance:
        
            filter_params                       resulting call to function
            -------------                       --------------------------
            (no filter_params supplied)         filterFunc('value');
            filter_params='cat'                 filterFunc('value','cat');
            filter_params=$strAnimal            filterFunc('value',$strAnimal);
            filter_params="1,2",5               filterFunc('value',"1,2",5);
            
        NOTE: This will cause an error:
            filter_params="with space"          filterFunc('value',"with);
        

Examples
--------

PHP file calling smarty:

    function FilterCat( $optValue )
    {
        return ( $optValue == 'cat' );
    }
    
    function FilterParam( $optValue, $strAnimal )
    {
        return ( $optValue != $strAnimal );
    }
    
    function FilterParam2( $optValue, $strAnimal, $strAnimal2 )
    {
        return ( $optValue == $strAnimal ) || ( $optValue == $strAnimal2 );
    }
    
    $smarty->assign( 'current_animal', 'bird' );


Language file:

    <?php
    $ls['DOG'] = 'dog';
    $ls['ANIMALS'] = array( 'cat' => 'Neko', 'dog' => 'Inu', 'bird' => 'Tori' );
    ?>


Template:

    1: <select name="smarty"> {lang_options options=ANIMALS selected=$current_animal} </select>
    2: <select name="lang">   {lang_options options=ANIMALS selected=DOG}             </select>
    3: <select name="lit">    {lang_options options=ANIMALS selected='cat'}           </select>
    4: <select name="fn1">    {lang_options options=ANIMALS filter=FilterCat}           </select>
    5: <select name="fn2">    {lang_options options=ANIMALS filter=FilterParam filter_params='cat'}</select>
    6: <select name="fn3">    {lang_options options=ANIMALS filter=FilterParam2 filter_params='cat','bird'}</select>


It would result in (selected item with asterix):

    1: Neko, Inu, Tori*     (dynamic - selected item depends on value of $current_animal)
    2: Neko, Inu*, Tori     (static  - Inu is always selected)
    3: Neko*, Inu, Tori     (static  - Neko is always selected)
    4: Neko                 (static  - no default selected item)
    5: Inu, Tori            (static  - no default selected item)
    6: Neko, Tori           (static  - no default selected item)