/**
* Add documentation for the filter to the event page.
*
* @param array $context
* @return array
**/
public function addFilterDocumentationToEvent($context)
{
// Check whether something should be done at all.
if (!in_array('formvalidation', $context['selected'])) {
return;
}
// Add documentation text to the context.
$context['documentation'][] = new XMLElement('h3', 'Form Validation');
$context['documentation'][] = new XMLElement('p', 'This extension adds the possibility for real form validation to Symphony.');
$context['documentation'][] = new XMLElement('p', 'The form validation is done by Benjamin Keen\'s \'PHP Validation\' script (http://www.benjaminkeen.com/software/php_validation/).');
$context['documentation'][] = new XMLElement('p', 'See the README.txt file shipped with the extension for installation details.');
$context['documentation'][] = new XMLElement('p', 'Upon error the filter returns an XML structure like the following:');
$code = <<<EOT
<filter type="formvalidation" status="failed">
\t<errors>
\t\t<error>The field 'Name' is required.</error>
\t\t<error>The field 'Address' is required.</error>
\t\t<error>Please enter a valid email address.</error>
\t</errors>
</filter>
EOT;
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'To enable the form validation in your form and choose the proper record containing the validation rules, add the following to your form (assuming that the record has the id 1):');
$code = <<<EOT
<input type="hidden" name="formvalidation[formname]" value="1" />
EOT;
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
public function appendEventFilterDocumentation($context)
{
if (is_array($context['selected']) && in_array('canofspam', $context['selected'])) {
$context['documentation'][] = new XMLElement('h3', 'Can Of Spam Filter');
$context['documentation'][] = new XMLElement('p', 'To use the Can Of Spam filter, add the Can Of Spam event to your page and the following field to your form:');
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode('<input name="canofspam" value="{$canofspam}" type="hidden" />');
}
}
public function addFilterDocumentationToEvent($context)
{
if (!in_array('recaptcha', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'reCAPTCHA Verification');
$context['documentation'][] = new XMLElement('p', 'Each entry will be passed to the <a href="http://recaptcha.net/whyrecaptcha.html">reCAPTCHA filtering service</a> before saving. Should the challenge words not match, Symphony will terminate execution of the Event, thus preventing the entry from being saved. You will receive notification in the Event XML. <strong>Note: Be sure to set your reCAPTCHA public and private API keys in the <a href="' . URL . '/symphony/system/preferences/">Symphony Preferences</a>.</strong>');
$context['documentation'][] = new XMLElement('p', 'The following is an example of the XML returned form this filter:');
$code = '<filter type="recaptcha" status="passed" />
<filter type="recaptcha" status="failed">Challenge words entered were invalid.</filter>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
public function addFilterDocumentationToEvent($context)
{
if (!in_array('no-editing', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'Prevent Editing');
$context['documentation'][] = new XMLElement('p', 'Prevents users from supplying an entry ID to edit entries like so:');
$code = '<input name="id" type="hidden" value="23" />';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'The following is an example of the XML returned form this filter:');
$code = '<filter name="no-editing" status="passed" />
<filter name="no-editing" status="failed">You are not allowed to edit entries.</filter>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
public function appendDocumentation($context)
{
if (!in_array('interspire', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'Interspire Email Marketer Filter');
$context['documentation'][] = new XMLElement('p', '
To use the Interspire Email Marketer filter, add the following field to your form:
');
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode('
<input name="interspire[list]" value="$interspire-list-id" type="hidden" />
<input name="interspire[field][Email]" value="$field-email-address" type="hidden" />
<input name="interspire[field][$interspire-custom-field-id]" value="Value for field Custom..." type="hidden" />
');
}
public function addFilterDocumentationToEvent($context)
{
if (is_array($context['selected']) && !in_array('akismet', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'Akismet Spam Filtering');
$context['documentation'][] = new XMLElement('p', 'Each entry will be passed to the <a href="http://akismet.com/">Akismet Spam filtering service</a> before saving. Should it be deemed as spam, Symphony will terminate execution of the Event, thus preventing the entry from being saved. You will receive notification in the Event XML. <strong>Note: Be sure to set your Akismet API key in the <a href="' . URL . '/symphony/system/preferences/">Symphony Preferences</a>.</strong>');
$context['documentation'][] = new XMLElement('p', 'The following is an example of the XML returned form this filter:');
$code = '<filter type="akismet" status="passed" />
<filter type="akismet" status="failed">Author, Email and URL field mappings are required.</filter>
<filter type="akismet" status="failed">Data was identified as spam.</filter>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'In order to provide Akismet with a correct set of data, it is required that you provide field mappings of Author, Email and URL. The value of these mappings directly point to values in the <code>fields</code> array of <code>POST</code> data. To specify a literal value, enclose the hidden fields <code>value</code> attribute in single quotes. In the following example, <code>author</code>, <code>website</code> and <code>email</code> would correspond to <code>fields[author]</code>, <code>fields[website]</code> and <code>literal@email.com</code> respectively:');
$code = '<input name="akismet[author]" value="author" type="hidden" />
<input name="akismet[email]" value="\'literal@email.com\'" type="hidden" />
<input name="akismet[url]" value="website" type="hidden" />
';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
public function add_filter_documentation_to_event($context)
{
if (!in_array('dynamic-event-redirect', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'Dynamic Event Redirect');
$context['documentation'][] = new XMLElement('h4', 'URL Parameters');
$context['documentation'][] = new XMLElement('p', 'To use URL parameters in your redirect output, you need to add a hidden input field to your form with the name <code>der-url-params</code> and set its value as a <code>/</code> seperated list of parameters you wish to include. Like so:');
$code = '
<input type="text" name="category" value="books-and-magazines"/>
<input type="text" name="book-id" value="1234"/>
<input type="hidden" name="der-url-params" value="category/book-id"/>
<input type="hidden" name="redirect" value="http://amazon.com/"/>
';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'The example above would result in the following URL: <code>http://amazon.com/books-and-magazines/1234/</code>. If a parameter isn’t set in the POST data its key (i.e., <code>category</code> in the example above) will be used in its place.');
$context['documentation'][] = new XMLElement('h4', 'GET Parameters');
$context['documentation'][] = new XMLElement('p', 'You can use GET parameters with or without URL parameters. The usage is pretty much the same: add a hidden input field to your form that has the name <code>der-params</code> and set its value to a comma separated list of parameters you wish to include. Like so:');
$code = '
<input type="text" name="category" value="books-and-magazines"/>
<input type="text" name="book-id" value="1234"/>
<input type="hidden" name="der-get-params" value="category,book-id"/>
<input type="hidden" name="redirect" value="http://amazon.com/"/>
';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'The would result in the user being redirected to: <code>http://amazon.com/?category=books-and-magazines&book-id=1234</code>.');
$context['documentation'][] = new XMLElement('h4', 'Things to note');
$context['documentation'][] = new XMLElement('ul', '
<li>You’ll need to specify a redirect URL, else the filter won’t do anything.</li>
<li>Entry fields have priority over normal POST data. That is, data from the <code>fields[]</code> array will be used in place of identically named indexes from the POST data.</li>
<li>When using as a filter, you can pass on the ID of the entry you’re creating by adding <code>id</code> to your list of params.</li>
<li>You can also output values directly by using key:value pairs in the <code>der-params</code> value.</li>
<li>Does not work with events with ‘Allow multiple’ filters, requires some changes to the core.</li>
<li><p>If you’re using Rowan’s <a href="http://overture21.com/forum/comments.php?DiscussionID=795">Clean URL Params</a> extension you can set the output to use clean syntax by adding the following to your form:</p>
<pre><code><input name="der-format" type="1" /></code></pre></li>');
}
public function add_filter_documentation_to_event($context)
{
if (!in_array('paypal-payments', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'PayPal Payments: Reroute to PayPal');
$context['documentation'][] = new XMLElement('p', 'You can pass data to PayPal’s server by mapping fields to most of the variables/fields listed in <a href="https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_html_Appx_websitestandard_htmlvariables">Website Payments Standard documentation</a>. The example below shows how you would map <code>amount</code>, <code>first-name</code>/<code>last-name</code> and <code>description</code> to their PayPal equivalents:');
$code = '<input name="fields[amount]" type="text" />
<input name="fields[first-name]" type="text" />
<input name="fields[last-name]" type="text" />
<textarea name="fields[description]"></textarea>
<input name="paypal-payments[cmd]" value="_xclick" type="hidden" />
<input name="paypal-payments[notify_url]" value="{$root}/paypal/" type="hidden" />
<input name="paypal-payments[amount]" value="amount" type="hidden" />
<input name="paypal-payments[name]" value="first-name,last-name" type="hidden" />
<input name="paypal-payments[item_name]" value="description" type="hidden" />
';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'Note that the <code>id</code> of the newly created entry will be automatically passed to PayPal as the <code>invoice</code>. Multiple fields can be mapped by separating them with commas, they will be joined with a space. All field mappings are optional.');
}
public function add_filter_documentation_to_event($context)
{
if (in_array('cachelite-entry', $context['selected']) || in_array('cachelite-section', $context['selected'])) {
$context['documentation'][] = new XMLElement('h3', __('CacheLite: Expiring the cache'));
}
if (in_array('cachelite-entry', $context['selected'])) {
$context['documentation'][] = new XMLElement('h4', __('Expire cache for pages showing this entry'));
$context['documentation'][] = new XMLElement('p', __('When editing existing entries (one or many, supports the <em>Allow Multiple</em> option) any pages showing this entry will be flushed. Add the following in your form to trigger this filter:'));
$code = '<input type="hidden" name="cachelite[flush-entry]" value="yes"/>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
if (in_array('cachelite-section', $context['selected'])) {
$context['documentation'][] = new XMLElement('h4', __('Expire cache for pages showing content from this section'));
$context['documentation'][] = new XMLElement('p', __('This will flush the cache of pages using any entries from this event’s section. Since you may want to only run it when creating new entries, this will only run if you pass a specific field in your HTML:'));
$code = '<input type="hidden" name="cachelite[flush-section]" value="yes"/>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
if (in_array('cachelite-url', $context['selected'])) {
$context['documentation'][] = new XMLElement('h4', __('Expire cache for the passed URL'));
$context['documentation'][] = new XMLElement('p', __('This will expire the cache of the URL at the value you pass it. For example'));
$code = '<input type="hidden" name="cachelite[flush-url]" value="/article/123/"/>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', __('Will flush the cache for <code>http://domain.tld/article/123/</code>. If no value is passed it will flush the cache of the current page (i.e., the value of <code>action=""</code> in you form):'));
$code = '<input type="hidden" name="cachelite[flush-url]"/>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
return;
}
public function appendEventFilterDocumentation($context)
{
if (!in_array('lock-entry', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', 'Database Entry Leasing');
$context['documentation'][] = new XMLElement('p', '<b>This event will only work on events being edited. So events with the following:</b>');
$code = '<input name="id" type="hidden" value="23" />';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'To handle leasing, javascript MUST be used. An example of how to deal with leases follows:');
$code = <<<CODE
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="{$root}/extensions/pessimistic_db_locking/assets/locking.js"></script>
<script type="text/javascript">
\t<xsl:comment>
\t\tjQuery(document).ready(function() {
\t\t\t
\t\t\t/* init takes 3 parameters
\t\t\t\t\tthe path to your symphony site (http://example.com)
\t\t\t\t\tthe id of the entry being edited
\t\t\t\t\tthe id of the author */
\t\t\tLocking.init('<xsl:value-of select="{$root}"/>', '<xsl:value-of select="'1130'"/>','<xsl:value-of select="events/login-info/@id"/>' );
\t\t\tLocking.setupLock(respond);
\t\t\tfunction respond(response) {
\t\t\t\tswitch(response) {
\t\t\t\tcase '"expired-lifetime"':
\t\t\t\t\t/* offer the user an option to renew the lease incase they're not idle
\t\t\t\t\t \t\tit can be renewed by doing the following:
\t\t\t\t\t\t\tLocking.forceRenewCallback(function response(data) {})
\t\t\t\t\t \twhere data is one of the following cases in this example */
\t\t\t\t\tbreak
\t\t\t\tcase '"expired"':
\t\t\t\t\t/* this will occur after the "expired-lifetime" case, when no lock exists,
\t\t\t\t\t\t\tso chances are they're still idle */
\t\t\t\t\talert('no lock exists for this entry');
\t\t\t\t\tbreak
\t\t\t\tcase '"true"':
\t\t\t\t\t/* renewLockCallback takes 2 parameters
\t\t\t\t\t\t\t\thow often to renew the lease
\t\t\t\t\t\t\t\tthe callback to be used (in this example, it is 'respond') */
\t\t\t\t\tLocking.renewLockCallback('<xsl:value-of select="events/lock-entry/renew_every"/>', respond);
\t\t\t\t\t// we're just renewing here
\t\t\t\t\tbreak
\t\t\t\tdefault:
\t\t\t\t\t// if someone else owns the lease, do something. in this example, I disable all the form controls
\t\t\t\t\tLocking.disableForm();
\t\t\t\t\talert('currently owned by ' + response);
\t\t\t\t}
\t\t\t}
\t\t});
\t</xsl:comment>
</script>
CODE;
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
$context['documentation'][] = new XMLElement('p', 'If a user tries to save an entry with this event attached, one of the following might result:');
$code = '<filter name="lock-entry" status="passed" />
<filter name="lock-entry" status="failed">This lease is currently owned by "some authors name".</filter>';
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode($code);
}
public function cbAppendEventFilterDocumentation(array $context = array())
{
if (!@in_array('smtp-email-library-send-email-filter', $context['selected'])) {
return;
}
$context['documentation'][] = new XMLElement('h3', __('Send Email via Direct SMTP Connection'));
$context['documentation'][] = new XMLElement('p', __('The send email filter, upon the event successfully saving the entry, takes input from the form and send an email to the desired recipient. <b>This filter currently does not work with the "Allow Multiple" option.</b> The following are the recognised fields:'));
$context['documentation'][] = contentBlueprintsEvents::processDocumentationCode('send-email[sender-email] // ' . __('Optional') . self::CRLF . 'send-email[sender-name] // ' . __('Optional') . self::CRLF . 'send-email[subject] // ' . __('Optional') . self::CRLF . 'send-email[body]' . self::CRLF . 'send-email[recipient] // ' . __('comma separated list of author usernames.'));
$context['documentation'][] = 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:'));
$context['documentation'][] = contentBlueprintsEvents::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[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>');
}
