symphony/content/content.ajaxeventdocumentation.php
<?php
/**
* @package content
*/
/**
* The AjaxEventDocumentation returns the documentation for a particular
* event by invoking all fields to return their documentation.
* Accepts three parameters, `section`, `filters` and `name`.
*/
class contentAjaxEventDocumentation extends TextPage
{
public function __construct()
{
parent::__construct();
$this->addHeaderToPage('Content-Type', 'text/html');
}
public function view()
{
$name = General::sanitize($_REQUEST['name']);
$section = General::sanitize($_REQUEST['section']);
$filters = self::processFilters($_REQUEST['filters']);
$rootelement = Lang::createHandle($name);
$doc_parts = array();
// Add Documentation (Success/Failure)
$this->addEntrySuccessDoc($doc_parts, $rootelement, $filters);
$this->addEntryFailureDoc($doc_parts, $rootelement, $filters);
// Filters
$this->addDefaultFiltersDoc($doc_parts, $rootelement, $filters);
// Frontend Markup
$this->addFrontendMarkupDoc($doc_parts, $rootelement, $section, $filters);
$this->addSendMailFilterDoc($doc_parts, $filters);
/**
* Allows adding documentation for new filters. A reference to the $documentation
* array is provided, along with selected filters
*
* @delegate AppendEventFilterDocumentation
* @param string $context
* '/blueprints/events/(edit|new|info)/'
* @param array $selected
* An array of all the selected filters for this Event
* @param array $documentation
* An array of all the documentation XMLElements, passed by reference
* @param string $rootelment
* The name of this event, as a handle.
*/
Symphony::ExtensionManager()->notifyMembers('AppendEventFilterDocumentation', '/blueprints/events/', array(
'selected' => $filters,
'documentation' => &$doc_parts,
'rootelement' => $rootelement
));
$documentation = join(PHP_EOL, array_map(function($part) {
return rtrim($part->generate(true, 4));
}, $doc_parts));
$documentation = str_replace('\'', '\\\'', $documentation);
$documentation = '<fieldset id="event-documentation" class="settings"><legend>' . __('Documentation') . '</legend>' . $documentation . '</fieldset>';
$this->_Result = $documentation;
}
/**
* Utilities
*/
public static function hasMultipleFilter($filters)
{
if (!is_array($filters)) {
return false;
}
return in_array('expect-multiple', $filters);
}
public static function hasSendEmailFilter($filters)
{
if (!is_array($filters)) {
return false;
}
return in_array('send-email', $filters);
}
public static function processFilters($filters)
{
$filter_names = array();
if (is_array($filters) && !empty($filters)) {
foreach ($filters as $filter) {
$filter_names[] = $filter['value'];
}
}
return $filter_names;
}
public static function processDocumentationCode($code)
{
return new XMLElement('pre', '<code>' . str_replace('<', '<', str_replace('&', '&', trim((is_object($code) ? $code->generate(true) : $code)))) . '</code>', array('class' => 'XML'));
}
public function addEntrySuccessDoc(array &$doc_parts, $rootelement, $filters)
{
$doc_parts[] = new XMLElement('h3', __('Success and Failure XML Examples'));
$doc_parts[] = new XMLElement('p', __('When saved successfully, the following XML will be returned:'));
if ($this->hasMultipleFilter($filters)) {
$code = new XMLElement($rootelement);
$entry = new XMLElement('entry', null, array('index' => '0', 'result' => 'success', 'type' => 'create | edit'));
$entry->appendChild(new XMLElement('message', __('Entry [created | edited] successfully.')));
$code->appendChild($entry);
} else {
$code = new XMLElement($rootelement, null, array('result' => 'success', 'type' => 'create | edit'));
$code->appendChild(new XMLElement('message', __('Entry [created | edited] successfully.')));
}
$doc_parts[] = self::processDocumentationCode($code);
}
public function addEntryFailureDoc(array &$doc_parts, $rootelement, $filters)
{
$doc_parts[] = new XMLElement('p', __('When an error occurs during saving, due to either missing or invalid fields, the following XML will be returned.'));
if ($this->hasMultipleFilter($filters)) {
$doc_parts[] = new XMLElement('p', __('Notice that it is possible to get mixtures of success and failure messages when using the ‘Allow Multiple’ option.'));
$code = new XMLElement($rootelement);
$entry = new XMLElement('entry', null, array('index' => '0', 'result' => 'error'));
$entry->appendChild(new XMLElement('message', __('Entry encountered errors when saving.')));
$entry->appendChild(new XMLElement('field-name', null, array('type' => 'invalid | missing')));
$code->appendChild($entry);
$entry = new XMLElement('entry', null, array('index' => '1', 'result' => 'success', 'type' => 'create | edit'));
$entry->appendChild(new XMLElement('message', __('Entry [created | edited] successfully.')));
$code->appendChild($entry);
} else {
$code = new XMLElement($rootelement, null, array('result' => 'error'));
$code->appendChild(new XMLElement('message', __('Entry encountered errors when saving.')));
$code->appendChild(new XMLElement('field-name', null, array('type' => 'invalid | missing')));
}
$code->setValue("\t...\n");
$doc_parts[] = self::processDocumentationCode($code);
}
public function addDefaultFiltersDoc(array &$doc_parts, $rootelement, $filters)
{
if (is_array($filters) && !empty($filters)) {
$doc_parts[] = new XMLElement('p', __('The following is an example of what is returned if any options return an error:'));
$code = new XMLElement($rootelement, null, array('result' => 'error'));
$code->appendChild(new XMLElement('message', __('Entry encountered errors when saving.')));
$code->appendChild(new XMLElement('filter', null, array('name' => 'admin-only', 'status' => 'failed')));
$code->appendChild(new XMLElement('filter', __('Recipient not found'), array('name' => 'send-email', 'status' => 'failed')));
$code->setValue("\t...\n");
$doc_parts[] = self::processDocumentationCode($code);
}
}
public function addFrontendMarkupDoc(array &$doc_parts, $rootelement, $section, $filters)
{
$multiple = $this->hasMultipleFilter($filters);
$doc_parts[] = new XMLElement('h3', __('Example Front-end Form Markup'));
$doc_parts[] = new XMLElement('p', __('This is an example of the form markup you can use on your frontend:'));
$container = new XMLElement('form', null, array('method' => 'post', 'action' => '{$current-url}/', 'enctype' => 'multipart/form-data'));
$container->appendChild(Widget::Input('MAX_FILE_SIZE', (string)min(ini_size_to_bytes(ini_get('upload_max_filesize')), Symphony::Configuration()->get('max_upload_size', 'admin')), 'hidden'));
if (is_numeric($section)) {
$section = (new SectionManager)->select()->section($section)->execute()->next();
if ($section) {
$section_fields = $section->fetchFields();
if (is_array($section_fields) && !empty($section_fields)) {
foreach ($section_fields as $f) {
if ($f->getExampleFormMarkup() instanceof XMLElement) {
$container->appendChild($f->getExampleFormMarkup());
}
}
}
}
}
$container->appendChild(Widget::Input('action['.$rootelement.']', __('Submit'), 'submit'));
$code = $container->generate(true);
$doc_parts[] = self::processDocumentationCode(($multiple ? str_replace('fields[', 'fields[0][', $code) : $code));
$doc_parts[] = new XMLElement('p', __('To edit an existing entry, include the entry ID value of the entry in the form. This is best as a hidden field like so:'));
$doc_parts[] = self::processDocumentationCode(Widget::Input('id' . ($multiple ? '[0]' : null), '23', 'hidden'));
$doc_parts[] = new XMLElement('p', __('To redirect to a different location upon a successful save, include the redirect location in the form. This is best as a hidden field like so, where the value is the URL to redirect to:'));
$doc_parts[] = self::processDocumentationCode(Widget::Input('redirect', URL.'/success/', 'hidden'));
}
public function addSendMailFilterDoc(array &$doc_parts, $filters)
{
if ($this->hasSendEmailFilter($filters)) {
$doc_parts[] = new XMLElement('h3', __('Send Notification Email'));
$doc_parts[] = new XMLElement('p',
__('Upon the event successfully saving the entry, this option takes input from the form and send an email to the desired recipient.')
. ' <strong>'
. __('It currently does not work with ‘Allow Multiple’')
. '</strong>. '
. __('The following are the recognised fields:')
);
$doc_parts[] = self::processDocumentationCode(
'send-email[sender-email] // '.__('Optional').PHP_EOL.
'send-email[sender-name] // '.__('Optional').PHP_EOL.
'send-email[reply-to-email] // '.__('Optional').PHP_EOL.
'send-email[reply-to-name] // '.__('Optional').PHP_EOL.
'send-email[subject]'.PHP_EOL.
'send-email[body]'.PHP_EOL.
'send-email[recipient] // '.__('list of comma-separated author usernames.'));
$doc_parts[] = new XMLElement('p', __('All of these fields can be set dynamically using the exact field name of another field in the form as shown below in the example form:'));
$doc_parts[] = self::processDocumentationCode('<form action="" method="post">
<fieldset>
<label>'.__('Name').' <input type="text" name="fields[author]" value="" /></label>
<label>'.__('Email').' <input type="text" name="fields[email]" value="" /></label>
<label>'.__('Message').' <textarea name="fields[message]" rows="5" cols="21"></textarea></label>
<input name="send-email[sender-email]" value="fields[email]" type="hidden" />
<input name="send-email[sender-name]" value="fields[author]" type="hidden" />
<input name="send-email[reply-to-email]" value="fields[email]" type="hidden" />
<input name="send-email[reply-to-name]" value="fields[author]" type="hidden" />
<input name="send-email[subject]" value="You are being contacted" type="hidden" />
<input name="send-email[body]" value="fields[message]" type="hidden" />
<input name="send-email[recipient]" value="fred" type="hidden" />
<input id="submit" type="submit" name="action[save-contact-form]" value="Send" />
</fieldset>
</form>'
);
}
}
}