function panels_edit in Panels 8.3

Same name and namespace in other branches

1. 5.2 panels.module \panels_edit()
2. 6.3 panels.module \panels_edit()
3. 6.2 panels.module \panels_edit()
4. 7.3 panels.module \panels_edit()

Main API entry point to edit a panel display.

Sample implementations utiltizing the the complex $destination behavior can be found in panels_page_edit_content() and, in a separate contrib module, OG Blueprints (http://drupal.org/project/og_blueprints), og_blueprints_blueprint_edit().

Parameters

object $display instanceof panels_display \n: A fully loaded panels $display object, as returned from panels_load_display(). Merely passing a did is NOT sufficient. \n Note that 'fully loaded' means the $display must already be loaded with any contexts the caller wishes to have set for the display.

mixed $destination \n: The redirect destination that the user should be taken to on form submission or cancellation. With panels_edit, $destination has complex effects on the return values of panels_edit() once the form has been submitted. See the explanation of the return value below to understand the different types of values returned by panels_edit() at different stages of FAPI. Under most circumstances, simply passing in drupal_get_destination() is all that's necessary.

array $content_types \n: An associative array of allowed content types, typically as returned from panels_common_get_allowed_types(). Note that context partially governs available content types, so you will want to create any relevant contexts using panels_create_context() or panels_create_context_empty() to make sure all the appropriate content types are available.

Return value

Because the functions called by panels_edit() invoke the form API, this function returns different values depending on the stage of form submission we're at. In Drupal 5, the phase of form submission is indicated by the contents of $_POST['op']. Here's what you'll get at different stages: -# If !$_POST['op']: then we're on on the initial passthrough and the form is being rendered, so it's the $form itself that's being returned. Because negative margins, a common CSS technique, bork the display editor's ajax drag-and-drop, it's important that the $output be printed, not returned. Use this syntax in the caller function: \n print theme('page', panels_edit($display, $destination, $content_types), FALSE); \n -# If $_POST['op'] == t('Cancel'): form submission has been cancelled. If empty($destination) == FALSE, then there is no return value and the panels API takes care of redirecting to $destination. If empty($destination) == TRUE, then there's still no return value, but the caller function has to take care of form redirection. -# If $_POST['op'] == ('Save'): the form has been submitted successfully and has run through panels_edit_display_submit(). $output depends on the value of $destination:

• If empty($destination) == TRUE: $output contains the modified $display object, and no redirection will occur. This option is useful if the caller needs to perform additional operations on or with the modified $display before the page request is complete. Using hook_form_alter() to add an additional submit handler is typically the preferred method for something like this, but there are certain use cases where that is infeasible and $destination = NULL should be used instead. If this method is employed, the caller will need to handle form redirection. Note that having $_REQUEST['destination'] set, whether via drupal_get_destination() or some other method, will NOT interfere with this functionality; consequently, you can use drupal_get_destination() to safely store your desired redirect in the caller function, then simply use drupal_goto() once panels_edit() has done its business.
• If empty($destination) == FALSE: the form will redirect to the URL string given in $destination and NO value will be returned.

Related topics

File

./panels.module, line 336

panels.module

Code

function panels_edit($display, $destination = NULL, $content_types = NULL, $title = FALSE) {
  ctools_include('display-edit', 'panels');
  ctools_include('ajax');
  ctools_include('plugins', 'panels');
  return _panels_edit($display, $destination, $content_types, $title);
}