NAME

Krang::CGI::ElementEditor - element editor CGI base class

SYNOPSIS

  http://krang/instance_name/element_editor

DESCRIPTION

Element editor CGI for Krang. This module is a super-class upon which element editing CGIs (story and category editors) may be built. It supplies some full run-modes as well as some helper functions which the child classes will use to implement their run-modes.

INTERFACE

Provided Run Modes

This module implements the following run modes:

• save_and_add
  
This mode calls the underlying _save() method of child classes and then goes to the add run-mode described below.

This mode saves the current data to the session and passes control to Krang::ElementEditor::add to add a new element. Child classes must implement the underlying _save() method.

• add
  
Called when the user clicks the ``Add Element'' button in the element editor. Returns to the 'edit' mode when complete.
• delete_children
  
Called to delete sub-elements. Returns to the 'edit' mode when complete without modifying 'path'.
• reorder
  
Called to reorder sub-elements. Returns to the 'edit' mode when complete without modifying 'path'.
• delete_element
  
Called to delete an element. This should called when the user clicks the delete button, except on the root screen where delete refers to the containing object.
• find_story_link
  
Called to find a story to link to a Krang::ElementClass::StoryLink (or subclass) element. Requires a path to the element and will set $element->data() to the chosen story. When finished, returns to the edit mode.
• find_media_link
  
Called to find a media to link to a Krang::ElementClass::MediaLink (or subclass) element. Requires a path to the element and will set $element->data() to the chosen media. When finished, returns to the edit mode.
• save_and_find_media_link
  
This mode is called with a 'jump_to' parameter set. It must save, substitute the 'jump_to' value for 'path' in query and return to the find_media_link mode.

This mode saves the current element data to the session and goes to the find_media_link mode. Classes inheriting these methods, including Krang::CGI::Story, Krang::CGI::Media and Krang::CGI::Category, are supposed to implement the underlying _save() method.

• save_and_find_story_link
  
This mode is called with a 'jump_to' parameter set. It must save, substitute the 'jump_to' value for 'path' in query and return to the find_story_link mode.

This mode saves the current element data to the session and goes to the find_story_link mode. Classes inheriting these methods, including Krang::CGI::Story, Krang::CGI::Media and Krang::CGI::Category, are supposed to implement the underlying _save() method.

• filter_element_data
  
This Ajaxy runmode may be called behind the scenes by WYSIWYG widgets to clean pasted-in HTML on the server. It dispatches to an equally named method of the element's class and returns what it gets back from there.

Provided Methods

The following methods are available to perform interface tasks involving elements. These should be called from within the child class' run-modes.

• $self->element_edit(template => $template, element => $element)
  
Called to fill in template parameters for the element editor (ElementEditor/edit.tmpl). Both the template and element are required parameters. When it returns the template will contain all necessary parameters to display the element editor.

This method will show the bulk edit interface if the CGI param 'bulk_edit' is set.

The bulk edit screen's standard edit area is a big textarea field. This is triggered by setting an elementclasse's 'bulk_edit' property to the legacy value '1' or better to 'textarea'. See <Krang::BulkEdit::Textarea>.

Another possibility is to use the Xinha editor for bulk editing. Set the elementclass's 'bulk_edit' property to 'xinha' if you wish this behavior. See Krang::BulkEdit::Xinha

• $self->element_view(template => $template, element => $element)
  
Called to fill in template parameters for the element viewer (element_editor_view.tmpl). Both the template and element are required parameters. When it returns the template will contain all necessary parameters to display the element viewer.
• $ok = $self->element_save(element => $element)
  
Called to save element data to the element passed to the method. Will return a boolean value indicating whether or not the save was successful. If the save was not successful then messages will have been registered with Krang::Message to explain the problem to the user.

Required Runmodes

You must implement the following run-modes in any child class:

• edit
  
The edit run mode is called after a number of the run-modes available complete their work.
• save_and_jump
  
This mode is called with a 'jump_to' parameter set. It must save, substitute the 'jump_to' value for 'path' in query and return to edit.
• save_and_go_up
  
This mode should save, hack off the last part of path (s!/.*$!!) and return to edit.

Required Methods

Your sub-class must define the following helper methods:

• _get_element
  
Must return the element currently being edited from the session.
• _get_script_name
  
Must return the name of the .pl script in htdocs directory which uses this module. This allows the action attribute for forms to be filled in.
• _save
  
This method must save the query to the underlying object.