Docs For Class FormResponse

Description

This class collects all output that needs to be returned after an Form-Request to the client. It automatically determines if it needs to send back javascript after an Ajax-Request or just redirect to another page (on a normal request).

FormResponse is also responsible for keeping the client- and serverside in sync after an HTTP-Request by collecting javascript-commands (which mostly trigger subsequent update-calls by Ajax.) Use the output as a return-value for Ajax-based saving methods. Be sure to check if the call is acutally "ajaxy" by checking Director::is_ajax(). It is the developers responsibility to include this into his custom form-methods. Use the Request-Parameter 'htmlonly' to enforce a pure HTML-response from the client-side.

Example: A {@TableField} is in an incorrect state after being saved, as it still has rows marked as "new" which are already saved (and have an ID) in the database. By using AjaxSynchroniser we make sure that every instance is refreshed by Ajax and reflects the correct state.

Caution:

FormResponse assumes that prototype.js is included on the client-side. (We can't put it into Requirements because it has to be included BEFORE an AjaxSynchroniser is called).
Please DON'T escape literal parameters which are passed to FormResponse, they are escaped automatically.
Some functions assume a {LeftAndMain}-based environment (e.g. load_form())

deprecated: 2.3 Use markup or JSON to transfer state to the client, and react with javascript callbacks instead
todo: Force a specific execution order ($forceTop, $forceBottom)Ω
todo: Extension to return different formats, e.g. JSON or XML

Located in /sapphire/core/control/FormResponse.php (line 30)

Variable Summary

static $behaviour_apply_rules $behaviour_apply_rules

static $non_ajax_content $non_ajax_content

static $redirect_url $redirect_url

static $rules $rules

static $redirect_url $status_include_order

static $status_messages $status_messages

Method Summary

static void add ($scriptContent $scriptContent, [ $uniquenessID = null])

static void clear ()

static void error ([$message $message = ""])

static string get_javascript ()

static void get_page ($id $id, [ $form = 'Form_EditForm'], [ $uniquenessID = null])

static string get_redirect_url ()

static void load_form ( $content, [ $id = 'Form_EditForm'])

static string respond ()

static void set_node_title ($id $id, [$title $title = ""])

static void set_non_ajax_content ($content $content)

static void set_redirect_url ($url $url)

static void status_message ([$message $message = ""], [$status $status = null])

static void update_dom_id ($domID $domID, $domContent $domContent, [$reapplyBehaviour $reapplyBehaviour = true], [$replaceMethod $replaceMethod = 'replace'], [ $uniquenessID = null])

static void update_status ($status $status, [$form $form = "Form_EditForm"])

Variables

static $behaviour_apply_rules $behaviour_apply_rules = array() (line 42)

var: array Separated from $rules because we need to apply all behaviour at the very end of the evaluated script to make sure we include all possible Behaviour.register()-calls.
access: protected

static $non_ajax_content $non_ajax_content (line 47)

var: string
access: protected

static $redirect_url $redirect_url (line 59)

var: string
access: protected

static $rules $rules = array() (line 35)

var: array
access: protected

static $redirect_url $status_include_order = array('bad', 'good', 'unknown') (line 65)

var: string
access: protected

static $status_messages $status_messages = array() (line 54)

Status-messages are accumulated, and the "worst" is chosen

var: array
access: protected

Methods

static method add (line 115)

Add custom scripts.

Caution: Not escaped for backwards-compatibility.

todo: Should this content be escaped?

static void add ($scriptContent $scriptContent, [ $uniquenessID = null])

$scriptContent $scriptContent: string
$uniquenessID

static method clear (line 123)

static void clear ()

static method error (line 163)

Alias for status_message($messsage, 'bad')

static void error ([$message $message = ""])

$message $message: string

static method get_javascript (line 249)

return: Compiled string of javascript-function-calls (needs to be evaluated on the client-side!)
access: protected

static string get_javascript ()

static method get_page (line 130)

static void get_page ($id $id, [ $form = 'Form_EditForm'], [ $uniquenessID = null])

$id $id: int
$form
$uniquenessID

static method get_redirect_url (line 211)

static string get_redirect_url ()

static method load_form (line 97)

Caution: Works only for forms which inherit methods from LeftAndMain.js

static void load_form ( $content, [ $id = 'Form_EditForm'])

$content
$id

static method respond (line 73)

Get all content as a javascript-compatible string (only if there is an Ajax-Request present).

Falls back to {non_ajax_content}, {redirect_url} or Director::redirectBack() (in this order).

static string respond ()

static method set_node_title (line 186)

Set the title of a single page in the pagetree

static void set_node_title ($id $id, [$title $title = ""])

$id $id: int
$title $title: string

static method set_non_ajax_content (line 197)

Fallback-method to supply normal HTML-response when not being called by ajax.

static void set_non_ajax_content ($content $content)

$content $content: string HTML-content

static method set_redirect_url (line 204)

static void set_redirect_url ($url $url)

$url $url: string

static method status_message (line 148)

Sets the status-message (overlay-notification in the CMS).

You can call this method multiple times, it will default to the "worst" statusmessage.

static void status_message ([$message $message = ""], [$status $status = null])

$message $message: string
$status $status: string

static method update_dom_id (line 227)

Replace a given DOM-element with the given content.

It automatically prefills {$non_ajax_content} with the passed content (as a fallback).

todo: More fancy replacing with loading-wheel etc.

static void update_dom_id ($domID $domID, $domContent $domContent, [$reapplyBehaviour $reapplyBehaviour = true], [$replaceMethod $replaceMethod = 'replace'], [ $uniquenessID = null])

$domID $domID: string The DOM-ID of an HTML-element that should be replaced
$domContent $domContent: string The new HTML-content
$reapplyBehaviour $reapplyBehaviour: boolean Applies behaviour to the given domID after refreshing it
$replaceMethod $replaceMethod: string Method for replacing - either 'replace' (=outerHTML) or 'update' (=innerHTML) (Caution: "outerHTML" might cause problems on the client-side, e.g. on table-tags)
$uniquenessID

static method update_status (line 174)

Update the status (upper right corner) of the given Form

static void update_status ($status $status, [$form $form = "Form_EditForm"])

$status $status: string
$form $form: string