verb_register_tag()

Usage

verb_register_tag($name, $options)

$name - Name for the tag you are registering. You do not need to including the leading v:. For example, to create the tag <v:calendar_widget>, you would specify a value of calendar_widget here. Note that you can redefine built-in Verb tags if you so choose!
$options - PHP associative array containing the following components:
- handler - PHP function that will be run to render the tag. You may optionally omit if you are defining a callback.
- callback - if set, this specifies that this tag will render a form and submit data back to the server. The value that goes here is the name of the PHP function that you have defined that should be run when data is posted to the server. If your handler returns true or you do not specify a handler, this tag will automatically render as a <form> tag that posts back in such a way that this callback will be invoked on receipt of the POST.
- html - if your tag returns a standard HTML tag, specify that tag here and all options that are valid for that tag will be considered valid for your tag.
- params - array of the attributes that are accepted for your tag. Or, set this to collection to accept all the parameters that are normally accepted by <v:collection>.
- required - array specifying which parameters are required.

Returns

Returns true.

How to define your functions

Handler Functions

Handler functions are called with 4 parameters, which by convention are named as follows:

$a - associative array of the attributes provided to the tag.
$tag - an associative array which describes the tag. Includes the following members:
- attrs - same as $a
- index - unique ID of this rendering instance of this tag. If this tag is called within a collection tag, each time the tag is rendered will have a different index
- innerhtml - HTML code inside this tag
- tags - array of tags nested inside this tag
$context - the current VerbQL context. Should be used in any calls to verb() or verb_find() that you make.
$callback - array that you can use to save data that will be made available to your callback function.

Use the verb_render_tags() function to render inner tags.

The return value of this handler function will be used as the rendered contents of your tag.

Callback functions

Callback functions are called with a single parameter – $tag. It is the same as above, but also contains an entry called callback that contains the values stored in $callback in the handler function. The handler function is always run on callbacks, before the callback tag is invoked.

Generally, you will call verb_redirect() in your callbacks to direct the visitor somewhere. A common convention is to return verb_redirect($tag['attrs']['redirect']); at the end of your callback. If you return any other value, it will be sent to the browser.

Sample Usage

Here are a few different sample tags.

Basic Example: TodaysDate

This will create a tag <v:todays_date> that renders today's date.

<?php
verb_register_tag('todays_date', array(
  'handler' => 'todays_date'
));
function todays_date($a, $tag, $context, &$callback) {
  return strftime("%B %d, %Y");
}
?>

Example HTML file:

Today's date is: <v:todays_date />.

Basic Example: StripeRow

This will render table rows with alternating CSS classes to achieve a “striped background” effect.

<?php
verb_register_tag('tr_striped', array(
  'handler' => 'tr_striped'
));
function tr_striped($a, $tag, $context, &$callback) {
  global $stripe;
  $class = (($stripe % 2) ? 'bg1' : 'bg2');
  $stripe++;
  return "<tr class='$class'>" . verb_render_tags($tag, $context) . "</tr>";
}
?>

Example HTML file:

<table>
  <tr class='bg2'><td>1</td></tr>
  <tr class='bg1'><td>2</td></tr>
  <tr class='bg2'><td>3</td></tr>
  <tr class='bg1'><td>4</td></tr>
  <tr class='bg2'><td>5</td></tr>
</table>

Of course, you can now use <v:tr_striped> inside <v:collection> tags, which is where it would truly be valuable.

Intermediate Example: IfCurrentDomain

This will render code only if the current domain name matches a specified domain name. This is useful if you have multiple domain names leading into your site.

<?php
verb_register_tag('if_current_domain', array(
  'handler' => 'if_current_domain',
  'params' => array("domain"), 
  'required' => array("domain")
));
    
function if_current_domain($a, $tag, $context, &$callback) {
  $does_domain_match = ($_SERVER['HTTP_HOST'] == $a['domain']);
  // passing a third parameter into verb_render_tags() tells Verb to 
  // only render it the third parameter is true.  Otherwise, 
  // render the contents of <v:else>
  return verb_render_tags($tag, $context, $does_domain_match);
}
?>

Now in your HTML files, you can use:

<v:if_current_domain domain="acmewidgets.com">
  Welcome to ACME Widgets, Inc.
  <v:else>You are at one of our other domains.</v:else>
</v:if_current_domain>

Server-side processing: BetterFormmail

This will create a replacement for the <v:formmail> tag.

<?php
verb_register_tag('better_formmail', array(
  'callback' => 'better_formmail_callback',  
  'html' => 'form', 
  'params' => array("redirect","to"), 
  'required' => array("to")
));
 
function better_formmail_callback($tag) {
  $mail = "Hey you!  Someone submitted a form at " . strftime("%B %d, %Y at %H:%M") . ":\n\n";
  foreach ($_POST as $k => $v) {
    $mail .= $k . " - " . $v . "\n";
  }  
  mail($tag['attrs']['to'], "BetterFormmail", $mail, "From: BetterFormmail <me@email.com>");
  if ($tag['attrs']['redirect']) return verb_redirect($tag['attrs']['redirect']);
  return verb_redirect($_SERVER['PHP_SELF']);
}
?>