# sfPropelSlotBehaviorPlugin plugin

## Overview

This plugin implements a behavior that permits to manage template and slots for different models.

Slots are additional data linked to an object depends of his template.

The plugin include an interface to edit, save & retrieve the value from slots.
It also include tools to load templates & slots configuration.

Slots can be define for different models (like page, product, mailing, ...)
Slots can be multilingual.

## Installation

  * Install the plugin
  
        
          symfony plugin-install http://plugins.symfony-project.com/sfPropelSlotBehaviorPlugin
        

  * Add new "template" fields to model(s) of your schema.yml

  * Enable Propel behavior support in `propel.ini`:

        
          propel.builder.AddBehaviors = true
        
  
    If you have to enable the behavior support, rebuild your model:

        
          symfony propel-build-model
        

  * Enable the behavior for one of your Propel model:

        
        [php]
        <?php
          // lib/model/Page.php
          class Page
          {
          }
    
          $columns_map = array('pk'       => PagePeer::ID,
                               'template' => PagePeer::TEMPLATE);
     
          sfPropelBehavior::add('Page', array('sfPropelSlotBehavior' => array('columns' => $columns_map)));
        

  The *column map* is used by the behavior to know which columns hold information it needs :
  
    * pk : Model column holding primary key (default : id)
    * template : Model column holding template name (default : template)

## Usage

### Configuration

Configuration permits to define templates and slots for different models.

First, each models must be listed in "sfPropelSlot" section.
Each model have its own templates and slots configuration, then you must specify the section where each model slots & templates are setup.
Optionnaly you can define a default model.

For each model configuration:
  * You can define default slot options by slot type
  * you have to list available templates for the model, each template must have a title and optionally slots
  * you must define all slots used by templates, each slots must have a title and a type and optionally options and parameters

example: 

    
      sfPropelSlot:
        default_model: Page
        models:
          Page: myCMS
          
      myCMS:
        default_slot_options:
          RichText:
            params: tinymce_options=height:250,width:600,language:"en",theme:"advanced",theme_advanced_disable:"flash,image,paste",plugins:"contextmenu,paste",theme_advanced_buttons1_add:"hr",theme_advanced_buttons3:"cut,copy,pastetext,pasteword,separator,formatselect,fontsizeselect,forecolor"
          File:
            params: include_remove=true
        templates:
          intro_template:
            title: "Intro page"
            slots: []
          home_template:
            title: "Homepage"
            slots: [text]
          page1_template: 
            title: "Page model 1"
            slots: [image, doc_file](text,)
          page2_template: 
            title: "Page model 2"
            slots: [date, products_ads](column1,)
          contact_template: 
            title: "Contact"
            slots: [email](text_contact,)
        slots:
          text:
            title: "Text"
            type: Text
            i18n: true
            params : size=100x10
          column1:
            title: "Text - 1st column"
            type: Text
            help: Don't use "CTRL+V" keystroke but "paste" icons.
          date:
            title: "Publication date"
            type: Date
          products_ads:
            title: "Products"
            type: Double_list
            params: related_class=Products retrieve_method=doSelectPublished
          doc_file:
            title: "Documentation"
            type: File
            upload_dir: doc_pdf
            help: "Download a pdf file"
          email:
            title: "E-mail address"
            type: Input
            params: size=40
    

### Extends admin generator

See example located in data directory of the plugin.

## Slot types options and params

### Input : basic input field

Options and params are the same than object_input_tag

### Text : textarea field

Options and params are the same than object_textarea_tag

### RichText : rich textarea field

Options and parameters are the same than object_textarea_tag
"rich" option is true by default and there is some default tinymce_options
Parameters :
  * rich (default : true)
  * tinymce_options (default : )

### Select : selectbox

2 way to use it :
  * With a related class like object_select_tag, you have to define "related_class" option and maybe "peer_method" and "text_method"
  * With a related class & method to retrieve available options : you have to define "related_class" AND "options_method" options

### Checkbox : checkbox

Options and params  are the same than object_checkbox_tag
Options :
  * default_value (optionnal)

### File : file upload

Options and params  are the same than object_admin_input_file_tag : 
    
      params: include_link=my_directory include_remove=true
      upload_dir: my_directory
    

include_link is equal to upload_dir by default

### Date : date field

Options and params are the same than object_input_date_tag

### DoubleList

Options:
  * related_class (required)
  * retrieve_method (default : doSelect)
  * size (default : doSelect)
  * unassociated_label (default : "Unassociated")
  * associated_label (default : "Associated")

## Public API

The behavior implement the following methods:

  * getSlots() : return all slots object used by object
  * getSlot($slot_name) : return a slot object by name from the object
  * getSlotValue($slot_name) : get a slot value by name from the object
  * removeSlot(slot_name) : remove a slot by name from the object
  * clearSlots() : remove all slots of the object
  * hasSlots()
  * hasSlot($slot_name)
  * getTemplate : return object's template
  * getTemplateOptions : return options of template used by object
  * getTemplateSlots : return options for each slots of the template used by object
  * setTemplate($template_name) : set the template of the object  

## Development

This plugin will probably used for next versions of sfDynamicCMS Plugin.
If you want to help and improve it, please contact Sylvain Papet (my firstname @ com-ocean.com).

I encourage every one to contribute to this plugin or even lead it.

## Todo

  * doSelectWithSlots method (which use a single query to retrieve objects and populate slots)
  * improve existing slot interface
  * add new slot widgets
  * add admin generator extension or sfAdvancedAdminGeneratorPlugin extension/integration
  * improve and document i18n (multilingual) slots management 

## Changelog

### 2008-28-05 | 0.1.2 Alpha

  * sylvio: refactor a lot of things
  * sylvio: improve configuration
  * sylvio: fix major bugs

### 2008-27-05 | 0.1.1 Alpha

  * sylvio: initial release