So some of you have seen the changes in the 0.9.7 manager, and how we’re using Smarty and AJAX connectors to isolate database processing and allow for multiple contexts. So I’m gonna explain a bit how the change affects things. Great tangible examples of this in action are the chunk/snippet management pages.
1) Forms are now processed through AJAX.
What does this mean to you? Well, that means you can get real-time, internationalized, server-side validation and processing without having to reload the page. For example, in the chunk update page, if you try to specify a blank name for the chunk, it throws back an error in red next to the name field and highlights that textbox red, all without a page reload. Pretty cool, huh?
How is this done? Well, it’s done via a Javascript class called FormHandler, which serializes the form, sends it to the corresponding connector, then waits for a response. If the response is either true or an integer (depending on what type of page - update or create - you’re on), it assumes that the process went successfully and continues on to whereever you specified in the ’new/continue/close’ part (I call those the STAY options).
If it, however, encounters anything else, it assumes it is a JSON error, which it then interprets and highlights the specified fields, displays a form-wide generic error message and and error messages specified for each field validated.
How do you do this? Well, in your processor, you simply do this:
// JSON Error processing
$error = new modJSONError($modx);
if ($_POST['name'] == '') $error->addField('name','Please specify a name.');
if ($error->hasError()) die($error->process('An error occurred. Please review your form.'));
modJSONError is a JSON error interpreter, which has 3 really important functions:
$error->addField($id,$error); - The $id parameter is the HTML id attribute for the input. The $error is the specific-to-that-field error message you’d like to send out. If you use this function, however, for whatever field you validate, you’ll need to add a
<span id="name_error" class="error"></span>
somewhere near the input to allow FormHandler to have something to put the error into (change ’name’ to whatever the id of the input field is).
$error->hasError() - This allows you to do multiple errors at one time. Simply addField as many times as you want, and then check to see if any fields have been triggered using this function. Then, you’d...
$error->process($errormsg); - The first parameter here is a general, form-wide error message that summarizes the errors. It is displayed in a HTML object with ID ’errormsg’ -
you must put this somewhere, preferably at the top of the form!! It can be a span, p, or div, but make sure to include it in your form HTML.
2) Actionbuttons are now generated through smarty plugins.
Simple enough? Instead of repeating lines and lines of HTML code all across the pages, all you need to do now is in your controller (the PHP file that loads the TPL "template" file) specify these lines:
// load Action buttons
$buttons = new modActionButtons($modx,array(
'type' => 'update',
'form_id' => 'update_chunk',
'new_params' => 'a=77',
'continue_params' => 'a=78&r=2',
'close_params' => 'a=76&r=2',
'cancel_id' => 76,
));
$buttons->add('save');
$buttons->add('duplicate','copy');
$buttons->add('delete');
$buttons->add('cancel');
$modx->smarty->assign('modActionButtons',$buttons);
- type - This is the type of form. ’create’,’update’,’delete’,’duplicate’, etc. Note that this is also the ’action’ variable passed to the AJAX PHP connector.
- form_id - The HTML ID attribute of the form.
- new_params - The URL GET parameters to pass if the user selects the ’add another’ option. Usually just the ’a’ variable.
- continue_params - The URL GET parameters to pass if the user selects the ’continue’ option. Usually just the ’a’ and ’r’ variables.
- close_params - The URL GET parameters to pass if the user selects the ’close’ option.
- cancel_id - The action ID (which is the manager page ID) that the page will redirect to if the user hits ’cancel’. Defaults to the home page.
$buttons->add($type,$image = ’’,$lang = ’’) is also important to note. If you need to specify a different image name for the button, do so here (as in the duplicate example). You can also specify a different $_lang string, if $_lang[$type] is incorrect.
This PHP code will setup the object to be passed into a Smarty plugin in your TPL file. For example, in chunk/update.tpl, we’ve replaced all the stuff in the subTitle div with:
<div class="subTitle">
{actionButtons data=$modActionButtons}
</div>
And the plugin automatically generates all the necessary valid XHTML via the modActionButtons class - including the javascript handler function that FormHandler.js and the new AJAX connectors use. In essence, this drastically limits the amount of code you have to write to get the nice functionality offered in the 0.9.7 manager.
Happy coding!
MODX Staff
This should make skinning and tweaking the manager much more simple and clean, which makes Ryan a happy camper. 
MODX Staff
And, great work on the commits ... 
