= 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: [text, image, doc_file]
      page2_template: 
        name: "Page model 2"
        slots: [column1, date, products_ads]
      contact_template: 
        name: "Contact"
        slots: [text_contact, email]
    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