root/plugins/sfPropelSlotBehaviorPlugin/README

= 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 can be listed in "sfPropelSlot" section, it is not compulsory but it will simplify plugin use.
When using this plugin with sfDynamicCMS Plugin, you don't need to configure plugin.

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

=== Object behavior methods ===

The behavior implement the following methods:

 * getSlots() : return all slots object used by object
 * initSlots($slot_name, $culture, $values, $culture) : initialize object's slot (retrieve or create them)
 * initSlot($slot_name, $culture, $value, $culture) : initialize a slot (retrieve or create it)
 * getSlot($slot_name, $culture) : return a slot object by name from the object
 * getSlotValue($slot_name, $culture) : return a slot value by name from the object
 * setSlot(slot_name, $type, $name, $value, $culture) : add or set a slot  
 * 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 slots and their options for each slots of the template used by object
 * setTemplate($template_name) : set the template of the object  
 * updateSlotsFromRequest($request, $cultures) : update object's slots from request

=== sfPropelSlot Tools ===

 * getTemplates() : return templates (name => title) of a model
 * getTemplateOptions($template_name) : return options of a template
 * getTemplateSlots(template_name) : return slots and their options of a template
 * getSlots() : return all slots defined for a model
 * getSlotOptions($slot_name) : return options of a slot

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

== Changelog ==

=== 2008-11-18 | 0.1.12 Alpha ===

 * sylvio: bugfix (i18n_slots)
 * sylvio: plugin tested with Symfony 1.1 & Symfony 1.2, it might be compatible
 
=== 2008-11-12 | 0.1.11 Alpha ===

 * sylvio: bugfix (sfSlotFile)
 
=== 2008-10-29 | 0.1.10 Alpha ===

 * sylvio: minor refactor & bug fixes (ticket #3822)

=== 2008-10-28 | 0.1.9 Alpha ===

 * sylvio: refactor & bug fixes (regression)

=== 2008-10-22 | 0.1.8 Alpha ===

 * sylvio: refactor & bug fixes

=== 2008-10-17 | 0.1.7 Alpha ===

 * sylvio: some improvement & new features (sfSelect)

=== 2008-06-30 | 0.1.6 Alpha ===

 * sylvio: fix some bugs (sfSlotDate and others)

=== 2008-06-13 | 0.1.5 Alpha ===

 * sylvio: fix some bugs

=== 2008-06-06 | 0.1.4 Alpha ===

 * sylvio: fix some bugs
 * sylvio: sfPropelSlot configuration section is optionnal (you can specify configuration section in your code)
 * sylvio: make plugin compatible with new sfDynamicCMS version to come (0.3.0) 

=== 2008-05-28 | 0.1.3 Alpha ===

 * sylvio: add updateSlotsFromRequest method
 * sylvio: update and improve admin generator usage example

=== 2008-05-28 | 0.1.2 Alpha ===

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

=== 2008-05-27 | 0.1.1 Alpha ===

 * sylvio: initial release