# sfPropelSlotBehaviorPlugin plugin

## Overview

This plugin implements a behavior that permits to add slots to a propel object.

Slots are additional fields for a model. These fields linked to an object depends of his template.

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

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

## 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('id'       => 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.

By default, templates & slots section are under "sfPropelSlot" in your app.yml file.
But this can be setup into your code (to have slots for different model) and you can have different templates & slots description for different models.

example: 

    
      sfPropelSlot:
        templates:
          intro_template:
            name: "Intro page"
            slots: []
          home_template:
            name: "Homepage"
            slots: [text]
          page1_template: 
            name: "Page model 1"
            slots: [image, doc_file](text,)
          page2_template: 
            name: "Page model 2"
            slots: [date, products_ads](column1,)
          contact_template: 
            name: "Contact"
            slots: [email](text_contact,)
        slots:
          text:
            name: "Text"
            type: Text
            params : size=100x10
          column1:
            name: "Text - 1st column"
            type: Text
            help: Don't use "CTRL+V" keystroke but "paste" icons.
            params: rich=true tinymce_options=height:500,width:300
          date:
            name: "Publication date"
            type: Date
          products_ads:
            name: "Products"
            type: Double_list
            params: related_class=Products retrieve_method=doSelectPublished
          doc_file:
            name: "Documentation"
            type: File
            params: include_link=doc_pdf include_remove=true
            upload_dir: doc_pdf
            help: "Download a pdf file"
          email:
            name: "E-mail address"
            type: Input
            params: size=40
    

## 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
    

### 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() : get all slots object of the object
  * getSlot($slot_name) : get a slot object by name
  * getSlotValue($slot_name) : get a slot value by name
  * removeSlot(slot_name) : remove a slot by name
  * clearSlots() : remove all slots of the object
  * hasSlots()
  * hasSlot($slot_name)

## 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

  * add tinymce_options default option in config
  * 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-27-05 | 0.1.1 Alpha

  * sylvio: initial release