Karma's Nucleus DevBlog

Time to highlight another one of the new things in Nucleus v3.2: the new FormExtra and ValidateForm events. I was documenting them in the Plugin API documentation earlier today, so they are fresh in my memory.

Basic idea

The base idea behind these new events is that a plugin needs to be able to add extra fields to comment, membermail or account activation forms. One of the plugins already exploiting these events is the Captcha plugin, which uses FormExtra to insert a captcha image, and the ValidateForm event to verify if the challenge was answered correctly.

Implementation

Nucleus keeps the templates for all of the forms that can be inserted into skins in the /nucleus/forms/ directory. For example, the template for a comment form as displayed to not logged in members, is in commentform-notloggedin.template. A membermail form for a logged in user is built using membermail-loggedin.template. These templates are handled by SKIN.php, which starts parsing them from the doForm method.

Let's take a look at the commentform-loggedin template:

<a id="nucleus_cf"></a>
<form method="post" action="#nucleus_cf">
  <div class="commentform">
    <%errordiv%>

    <input type="hidden" name="action" value="addcomment" />
    <input type="hidden" name="url" value="<%formdata(destinationurl)%>" />
    <input type="hidden" name="itemid" value="<%itemid%>" />
    <label for="nucleus_cf_body"><%text(_COMMENTFORM_COMMENT)%></label>:
    <br />
    <textarea name="body" class="formfield" cols="40" rows="10" id="nucleus_cf_body"><%formdata(body)%></textarea>
    <br />
    <%text(_COMMENTFORM_YOUARE)%> <%formdata(membername)%>
    <small>(<a href="?action=logout"><%text(_LOGOUT)%></a>)</small>
    <br />
    <input type="submit" value="<%text(_COMMENTFORM_SUBMIT)%>" class="formbutton" />
    <%callback(FormExtra,commentform-loggedin)%>
  </div>
</form>

Notice the <%callback(FormExtra,commentform-loggedin)%> in there? It causes the FormExtra event to fire, with $data['type'] set to commentform-loggedin.

While I'm at it, let me describe the other special variables in form templates as well:

• <%text(_COMMENTFORM_SUBMIT)%>: Inserts a language file constant
• <%formdata(membername)%>: Inserts some data. If you want to see an example of where the formdata is filled out, take a look at the parse_commentform method in SKIN.php, for example.
• <%errordiv%>: Error message. See the Comment forms and errors article I wrote earlier.

Back to the FormExtra event now. Six types of forms currently generate the event: commentform-loggedin, commentform-notloggedin, membermail-loggedin, membermail-notloggedin, activation and additemform. The activation form is kind of special, since it is part of the admin area and has no template. Also, note that the additemform corresponds to the <additemform> and not to the regular Add Item page in the admin area (see the AddItemFormExtras event for that one)

The other end: ValidateForm

On the other end of the chain is the ValidateForm, which can be used to verify the field that were added during FormExtra. If can also be used to simply verify the normal fields. For example: a spam plugin might check if the message looks like spam and provide an error message back to the user (in case the user is legitimate, he can edit his comment and try again, rather than having to start all over again).

When the event fires, the data that is sent along contains a type entry again. This time, it can only take three values: comment, membermail and activation. There's no additem: these go through the regular Add Item process and the PreAddItem event.

Next to a validation type, a reference to an error variable is passed. If the plugin considers the form data to be invalid, it should fill this variable with a non-empty error string, which will then be presented to the user as if the error was generated by Nucleus itself.