Introduction

This is the sixth in our series of articles on constructing plugins/extensions specifically for Simple:Press. Here are links to the prior articles:

• Hello World!
• Adding Settings
• Adding A Component Menu Item
• Using POST OPTIONS
• Authorizations and Permission Sets

In this article we will engage in an extensive discussion of one of the more important CLASSes in Simple:Press - the NEW POST Class. This class is the base object that handles creating new posts and topics.

About The NEW POST Class

The NEW POST class is the recommended medium for creating a new topic or post in Simple:Press. It ensures that all the proper permission and data validation is performed, that the database is correctly updated and that any or all necessary indexing is carried out. Through the use of standard WordPress hooks, it also ensures that any active plugins that may affect a new topic or post are correctly actioned.

The php code for the new post class can be found at: /sp-api/sp-api-class-spcpost.php

The class itself is used by the core code called from /sp-api/forum/library/sp-post.php

It is also used by the following premium plugins:

• Admin Bar
• Blog Linking
• Post By Email
• Post Multiple

For most uses, the action and filter hooks described at the bottom of this article should be sufficient. But for the sake of completeness we will start from a high-level and drill down into the gory details.

High Level Overview

Essentially the class builds an array named $newpost which is filled with the necessary data as the different steps in the process are carried out. This array is available to all action and filter hooks. Note that some of the main elements are filled prior to any of the class methods being called (this will be detailed later in this document.) Also note that public methods can only be invoked in a pre-set order – creating the necessary data and saving it requires these steps.

Finally, each public method will set an abort property to true if there is a failure at any stage and this must be checked for in the calling program code.

Public Methods

validateHuman($postVars)

This method is only used in the actual forum UI as it checks the new topic/post forms and any captcha available in an attempt to ensure that the call is being made by an actual user. It is listed here for the sake of completeness.

validatePermission()

The first of the three main methods, this checks all permissions of the user making the call for a new topic or post to ensure they are allowed to do so.

validateData()

This next stage validates the data which by this time should all be compiled into the array.

saveData()

The final stage updates the database with the new topic and/or post plus updates any indexing required. It also performs any post-save tasks  such as, for example, email notifications etc.

show()

This method is for debugging and will display the object data to the screen if possible. This should, of course, never be used in production code.

The spcPost Data Object

The following list describes the data object that is built during the new post call. These properties, where applicable, should all be filled prior to the call to the validatePermission() method.

• action - Must be set to either the term ‘topic’ or ‘post’ depending on what needs to be created. A ‘topic’ action will, of course, also save the initial post data.
• call - This is a user-defined item that can be set to uniquely describe the calling process which can be useful if the process needs to be identified within plugins. The core call uses the term ‘post’. Other uses of the class should use its own term.
• abort - This property will be set to true if a problem is encountered ad should be tested for at the end of each method call.
• message - An explanatory message that can be used to display the reason for the abort or – at the end – the success or failure of the save.
• userid - The ID of the user creating the topic or post
• admin - Set to a 1 (true) if the user is a forum admin
• moderator - Set to a 1 (true) if the user is a forum moderator. This should also be set to 1 if an admin
• member - Set to a 1 (true) if the user is a forum registered member/user
• guest - Set to a 1 (true) if the user is a non-registered guest poster.
• newpost - The data array that will hold all the data to be used in the final save operation and described in the next section.

The $newpost Data Array

The following list describes the $newpost array that is created using the post class. Items marked with an asterisk (*) are those that the calling code needs to provide. The remainder are filled by the class code itself.

• action - Default set to the same value as the spcPost property of the same name. This makes it visible for use in plugins or third-party code.
• error - Default set to null. Currently unused by core but available to plugins if needed.
• db - Default set to 0 (false). Will be set to true if there is a save failure the same as the spcPost property abort. This makes it visible for use in plugins or third-party code.
• submsg - Used internally to build final message text if needed.
• emailprefix - Used internally by the email notification sub-system
• userid * - Must be set to the posters users ID
• forumid * - Must be set to the id of the forum containing the new topic or post
• forumslug * - Must be set to the forum slug
• forumname - Set internally to the forum name
• groupname - Set internally to the forum group name
• topicid - Set internally to the db topic_id following a successful save
• topicname * - Must be set to the desired topic name
• topicslug * - Must be set if the action is ‘post’. Set internally if action is ‘topic’.
• topicpinned * - Default set to 0 (false). Set to 1 (true) if pinned is required.
• topicstatus * - Default set to 0 (false). Set to 1 (true) if topic lock is required.
• postid - Set internally to the db post_id following a successful save
• postcontent * - The textual content of the post being made
• postdate - Set internally to the current date/time
• guestname * - The name of the guest poster is required
• guestemail * - The email address of the guest poster if guestname is defined
• poststatus - Default set to 0 (false). Set to 1 (true) if post requires moderation
• postpinned * - Default set to 0 (false). Set to 1 (true) if pinned is required.
• postindex - Set internally to the index number (sequence) of the new post.
• posterip - Set internally to the IP address of the poster
• postername * - Must be set to the posters display name
• posteremail * - Must be set to the posters email address
• source * - Defaults to 0 (zero) but can optionally be used to identify how the post was made as this data is saved to the db. So a plugin could use a unique number. Note that the Post by Email plugin sets this to a 1 (one).
• started_by - Set internally in the new topic record to the user ID of the poster
• postcontent_unescaped - The post content prior to sanitizing. This is only realistically used by core in case of a save failure when it is used to repopulate the editor window.

Filter and Action Hooks

Assuming a class instantiation of $p = new spcPost the following standard WP style hooks are available for use by plugins and other third party code.

ValidatePermission()

sph_post_permissions_validation

$this->newpost = 
apply_filters('sph_post_permissions_validation', $this->newpost);

This filter hook is available at the very end of the success of the permission validation method. At this point the $newpost array can be additionally manipulated.

validateData()

sph_post_data_validation

$this->newpost = 
apply_filters('sph_post_data_validation', $this->newpost);

This filter hook is available at the end of of the success of the data validation method. At that point the $newpost array can be additionally manipulated.

sph_pre_post_create

do_action('sph_pre_post_create', $this->newpost);

This action hook follows the above filter hook allowing for extra data or events to be triggered at this stage of the proceedings.

sph_new_forum_post

$this->newpost = 
apply_filters('sph_new_forum_post', $this->newpost);

This filter hook follows the above action hook should it be needed.

saveData()

sph_new_post_pre_save

do_action_ref_array('sph_new_post_pre_save', array(&$this));

This action hook is available at the very start of the save process. NOTE: this makes the entire class object available for modification before saving and should be used with care. Especially note the passing by reference.

sph_new_topic_pre_data_saved

$this->newpost = 
apply_filters('sph_new_topic_pre_data_saved', $this->newpost);

A pre-save filter hook available if the ‘action’ is set to ‘topic’.

sph_new_topic_data

$query = 
apply_filters('sph_new_topic_data', $query, $this->newpost);

A filter hook to enable manipulating the INSERT $query for the topic record save. This hook would typically be used by a plugin that has added new DB fields to add the name and data to the $query→fields and $query→properties.

sph_new_topic_data_saved

$this→newpost =
apply_filters('sph_new_topic_data_saved', $this->newpost);

A filter hook called immediately following a successful save of the topic record.

sph_new_post_pre_data_saved

$this->newpost = 
apply_filters('sph_new_post_pre_data_saved', $this->newpost);

A pre-save filter hook available if the ‘action’ is set to ‘post’.

sph_new_post_data

$query = apply_filters('sph_new_post_data', $query, $this->newpost);

A filter hook to enable manipulating the INSERT $query for the post record save. This hook would typically be used by a plugin that has added new DB fields to add the name and data to the $query→fields and $query→properties.

sph_new_post_data_saved

$this->newpost = 
apply_filters('sph_new_post_data_saved', $this->newpost);

A filter hook called immediately following a successful save of the post record.

sph_post_message

$this->newpost['submsg'] = 
apply_filters('sph_post_message', $this->newpost['submsg'], $this->newpost);

A filter hook that allows a plugin to add or change the success message that is returned.

sph_post_new_completed

do_action_ref_array('sph_post_new_completed', array(&$this));

This action hook is available at the very end of the save process. NOTE: this makes the entire class object available for modification before saving and should be used with care. Especially note the passing by reference.

sph_new_post, sph_post_create

do_action('sph_new_post', $this->newpost);
do_action('sph_post_create', $this->newpost);

Two final action hooks at the very end of the whole process – just in case!