Zen Cart®/Bulletin Board Integration via Notifier Hooks

Version 1.5.1 by lat9 — Supports Zen Cart v1.5.1 to v1.5.4

Support Thread: http://www.zen-cart.com/showthread.php?204807-Zen-Cart-Bulletin-Board-Integration-Support-Thread

Version History:


What It Does

This plugin converts the Zen Cart bulletin-board integration (as of Zen Cart v1.5.1 via /includes/classes/class.phpbb.php) to a collection of notifier hooks, allowing other plugins to be written using observer-class scripts to integrate various bulletin boards into Zen Cart. It provides the framework into which a bulletin-board can be integrated — it provides no functionality other than the standardized interface. The idea came from this thread on the Zen Cart forums.

Starting with v1.2.0 of the interface, you can specify that the "Nick Name" field is optional during customer account registration by setting the value of your admin's Configuration->Minimum Values->Nick Name to 0. If that value is set to 0 and the customer does not specify a Nick Name during the registration process, then there is no further reference to a forum Nick Name within that customer's account information.

Note: The interface is designed to support one and only one installed bulletin-board interface for a given Zen Cart installation.

Some Zen Cart core files have been modified to make use of this framework, making it seamless for a bulletin-board to "plug into" Zen Cart. Specifically, Zen Cart page-related processing has been changed to enable the following bulletin-board integration:

Zen Cart Page
If a Bulletin-Board is Enabled …
account_edit
… and the customer's account has a non-blank Nick Name value, this page's processing makes sure that the Email Address specified by the customer is not associated with any other account in the enabled bulletin board. If the customer's account information is changed in their Zen Cart account, their email address is updated in their bulletin board account.
account_password
… and the customer's account has a non-blank Nick Name value, if the customer changes the Password associated with their Zen Cart account, the password is also changed in their bulletin board account.
create_account
… this page's processing depends on your admin's Configuration->Minimum Values->Nick Name setting and whether a Nick Name value is specified by the customer:
Minimum Values->Nick Name
Nick Name Specified?
Page Processing
N/A
Yes
Verifies that neither the Email Address nor Nick Name values specified are associated with any account in the bulletin board. If a Zen Cart customer account is successfully created, a bulletin board account is created with the same "Nick Name", "Email Address" and "Password". If the value for BB_EMAIL_WELCOME is defined, the store's "welcome email" includes that text. That definition is located in /includes/languages/english/extra_definitions/YOUR_TEMPLATE/bb_definitions.php.
> 0
No
Not allowed. An error message is issued and the customer must specify a non-blank Nick Name.
0
No
The page's processing completes as if the bulletin board linkage was not present.
create_account_success
… the customer has specified a non-blank Nick Name value and the value for BB_TEXT_ACCOUNT_CREATED is defined, the text from that definition is appended to the page's main-content. That definition is located in /includes/languages/english/extra_definitions/YOUR_TEMPLATE/bb_definitions.php.
password_forgotten
… and the customer's account has a non-blank Nick Name value, when the customer requests a new password the password identified in the email sent by Zen Cart processing becomes the new password for both their Zen Cart and bulletin board accounts.

Interface Specification

A new class — bb — is created and an instance of this class ($bb) is created during the Zen Cart start-up processing. Any bulletin-board observer class that desires to plug into this class must install itself at Breakpoint 54 using an autoload configuration file; for example, the sample code that allows phpBB® integration into Zen Cart via this interface installs itself via the following statements:

  $autoLoadConfig[54][] = array('autoType'=>'class',
                                'loadFile'=>'observers/class.phpbb_observer.php');
  $autoLoadConfig[54][] = array('autoType'=>'classInstantiate',
                                'className'=>'phpbb_observer',
                                'objectName'=>'phpbb_observer');

Note: It is the responsibility of the Zen Cart store owner to ensure that one and only one bulletin-board observer is installed on the interface at any one time, or the results are unpredictable. Starting with v1.1.0 of this interface, properly coded bulletin board observers can also enforce this restriction.

Function Definitions

This section identifies the functions provided by the bb class for use by Zen Cart page processing and the bulletin-board observer classes:

Function Name
Page Processing
BB Observer
Description
Version
 
 
Class constructor.
v1.0.0 and later
Returns the current interface version.
v1.0.0 and later
 
Sets the status to indicate that a bulletin board bb is active on the interface.
v1.1.0 and later
Identifies whether or not a bulletin board is active on the bb interface.
v1.0.0 and later
Returns the URL associated with the active bulletin board.
v1.0.0 and later
 
Sets the URL associated with the active bulletin board.
v1.0.0 and later
 
Returns an additional error message previously set by the active bulletin board.
v1.2.0 and later
 
Sets an additional error message to be displayed.
v1.2.0 and later
Returns the name of the active bulletin board.
v1.0.0 and later
 
Sets the name of the active bulletin board.
v1.0.0 and later
 
Creates a user account in the active bulletin board.
v1.0.0 and later
 
Checks to see that the specified nickname is not currently used.
v1.0.0 and later
 
Checks to see that the specified email address is not currently used.
v1.0.0 and later
 
Changes the password for the specified nickname.
v1.0.0 and later
 
Changes the email address for the specified nickname.
v1.0.0 and later

bb

bb — Class constructor for the bb class.

Description
void bb (void);

Invoked via a classInstantiate method in the /includes/auto_loaders/config.core.php file, this function subsequently issues a notifier to allow a single customized bulletin board to integrate with the Zen Cart processing.

Observer Class Interface
$this->notify('ZEN_BB_INSTANTIATE');

Requests the initialization of any bulletin-board observer.

For interface version v1.0.0 only, the observer must return bb:STATUS_OK if the operation completed successfully and communications with the external bulletin board have been established; any other value will be interpreted by this function as an error. If the bb class function return status value is bb:STATUS_OK upon return from the notification, subsequent calls to member function is_enabled will return true; otherwise, that function will return false. See Observer Class Programming for the method an observer uses to return a status code.

For all other interface versions, the observer must call the bb class member function set_enabled if the operation completed successfully and communications with the external bulletin board have been established. Subsequent calls to member function is_enabled will return true only if the set_enabled function has been previously called.

get_version

get_version — Returns the current interface version for the bb class.

Description
string get_version (void);
Return Values

Returns a string containing the current interface version for the bb class, one of:

  • BB_VERSION_MAJOR.BB_VERSION_MINOR — The initial release of the interface.
  • 1.1.0 — The version in which the instantiation interface was changed to ensure that one and only one bulletin board observer is successfully installed.
  • set_enabled

    set_enabled — Sets the indication that a bulletin board is active on the bb interface. This function was added for interface version "1.1.0".

    Description
    void set_enabled (void);

    is_enabled

    is_enabled — Identifies whether or not a bulletin board is active on the bb interface.

    Description
    bool is_enabled (void);
    Return Values

    Returns true if a bulletin board's observer class has been successfully instantiated, false otherwise.

    get_bb_url

    get_bb_url — Returns the URL for the bulletin board that is active on the bb interface.

    Description
    string get_bb_url (void);

    The value returned should be used in conjunction with function zen_href_link to create a full URL to the active bulletin board.

    Return Values

    Returns a strong containing the value previously set by an active bulletin board's observer class via call to member function set_bb_url. If no observer class has set the value, returns FILENAME_PAGE_NOT_FOUND.

    set_bb_url

    set_bb_url — Sets the URL for the bulletin board that is active on the bb interface.

    Description
    void set_bb_url (string);

    Used by a bulletin board observer to set the URL to be used for a Zen Cart script to link to the bulletin board. The value is returned by subsequent call to member function get_bb_url. The value should only be set by the observer if the class instantiation was successful.

    get_bb_message

    get_bb_message — Returns an error message previously set by the bulletin board that is active on the bb interface, v1.2.0+

    Description
    string get_bb_message (void);

    If the value returned by call to either check_nick_not_used or check_email_not_used is not bb::STATUS_OK, the bulletin board observer (v1.2.0 and later) might have set an additional message to be displayed to the customer. The value returned, if not '', should be displayed as an error to the customer.

    Return Values

    Returns a strong containing the value previously set by an active bulletin board's observer class via call to member function set_bb_message. If no observer class has set the value, returns ''.

    set_bb_message

    set_bb_message — Sets an error message returned by the bulletin board that is active on the bb interface, v1.2.0+

    Description
    void set_bb_message (string);

    Used by a bulletin board observer to set an additional error message to be displayed by the Zen Cart script to provide additional information to the customer in response to either check_nick_not_used or check_email_not_used request. The value is returned by subsequent call to member function get_bb_message. For example, a bulletin board observer might limit a Nick Name value's maximum length and return an error message indicating as such.

    get_bb_name

    get_bb_name — Returns the "common name" for the bulletin board that is active on the bb interface.

    Description
    string get_bb_name (void);

    The value returned can be used by Zen Cart page processing to identify the "name" of the active bulletin board. For example, the value returned when the phpBB® observer is installed is 'phpBB'.

    Return Values

    Returns a strong containing the value previously set by an active bulletin board's observer class via call to member function set_bb_name. If no observer class has set the value, returns ''.

    set_bb_name

    set_bb_name — Sets the "common name" for the bulletin board that is active on the bb interface.

    Description
    void set_bb_name (string);

    Used by a bulletin board observer to set the "common name" to be used to identify the bulletin board. The value is returned by subsequent call to member function get_bb_name. The value should only be set by the observer if the class instantiation was successful.

    create_account

    create_account — Creates an account with the bulletin board that is active on the bb interface.

    Description
    bb_return create_account (string $nickname, string $password, string $email_address);

    Used by Zen Cart page processing to create an account in the active bulletin board.

    Return Values

    Returns the bb class constant bb::STATUS_OK if either the active bulletin board account was successfully created or if there is no active bulletin board. Any other value indicates that an error occurred during the processing.

    Observer Class Interface
    $this->notify('ZEN_BB_CREATE_ACCOUNT', array('nick' => $nick, 'pwd' => $password, 'email' => $email_address));

    Submits the nickname, unencoded password and email address to be used to create an account in the active bulletin board. The observer must return bb:STATUS_OK if the operation completed successfully; any other value should be interpreted by the Zen Cart caller as an error. See Observer Class Programming for the method an observer uses to return a status code.

    check_nick_not_used

    check_nick_not_used — Verifies that a nickname is not currently used by the bulletin board that is active on the bb interface.

    Description
    bb_return check_nick_not_used (string $nickname);

    Used by Zen Cart page processing to determine if the specified nickname is unused by the active bulletin board.

    Return Values

    Returns the bb class constant bb::STATUS_OK if either the specified nickname is not used by the active bulletin board or if there is no active bulletin board. Any other value indicates that the nickname is either currently being used or failed an additional requirement check. For v1.2.0 and later, if the value returned is not bb::STATUS_OK the observer might have set an additional error message to be displayed to the customer; see get_bb_message for more information.

    Observer Class Interface
    $this->notify('ZEN_BB_CHECK_NICK_NOT_USED', array('nick' => $nick));

    Submits a nickname to see if it is being used in the active bulletin board. The observer must return bb:STATUS_OK if the operation completed successfully, the nickname is not in use and is valid for the bulletin board; any other value return implies that the nickname is not valid. See Observer Class Programming for the method an observer uses to return a status code.

    check_email_not_used

    check_email_not_used — Verifies that an email address is not currently in use by the bulletin board that is active on the bb interface.

    Description
    bb_return check_email_not_used (string $email_address [, string $nick='']);

    Used by Zen Cart page processing to determine if the specified email address is not in use by the active bulletin board. If the optional second parameter ($nick) is specified and non-null, successful return identifies that the email address is not used for any account other than one with a nickname of $nick; otherwise, successful return of the function identifies that the email address is not used for any account.

    Return Values

    Returns the bb class constant bb::STATUS_OK if either the specified email address is not in use by the active bulletin board or if there is no active bulletin board. Any other value indicates that the email address is currently being used or failed an additional requirement check. For v1.2.0 and later, if the value returned is not bb::STATUS_OK the observer might have set an additional error message to be displayed to the customer; see get_bb_message for more information.

    Observer Class Interface
    $this->notify('ZEN_BB_CHECK_EMAIL_NOT_USED', array('email' => $email_address, 'nick' => $nick));

    Submits an email address to see if it is being used in the active bulletin board. The observer must return bb:STATUS_OK if the operation completed successfully and the email address is not in use; any other value return implies that the email address is either in use or is not valid for the active bulletin board. See Observer Class Programming for the method an observer uses to return a status code.

    change_password

    change_password — Requests that an account password be changed in the bulletin board that is active on the bb interface.

    Description
    bb_return change_password (string $nick , string $password);

    Used by Zen Cart page processing to request a password change for the account associated with the nickname specified. The $password input is the unencoded new password.

    Return Values

    Returns the bb class constant bb::STATUS_OK if either the password change was successful or if there is no active bulletin board.

    Observer Class Interface
    $this->notify('ZEN_BB_CHANGE_PASSWORD', array('nick' => $nick, 'pwd' => $newpassword));

    Submits a nickname for which the account password is to be changed in the active bulletin board. The observer must return bb:STATUS_OK if the operation completed successfully and the password change was successful. See Observer Class Programming for the method an observer uses to return a status code.

    change_email

    change_email — Requests that an account email address be changed in the bulletin board that is active on the bb interface.

    Description
    bb_return change_email (string $nick , string $email_address);

    Used by Zen Cart page processing to request an email address change for the account associated with the nickname specified.

    Return Values

    Returns the bb class constant bb::STATUS_OK if either the email address change was successful or if there is no active bulletin board.

    Observer Class Interface
    $this->notify('ZEN_BB_CHANGE_EMAIL', array('nick' => $nick, 'email' => $email_address));

    Submits a nickname for which the account email address is to be changed in the active bulletin board. The observer must return bb:STATUS_OK if the operation completed successfully and the email address change was successful. See Observer Class Programming for the method an observer uses to return a status code.

    Observer Class Programming

    The bb class observer interface requires that the observer's class be instantiated at Breakpoint 54 during the Zen Cart auto-load process. This breakpoint is after the bb class file has been loaded, but prior to the bb class being instantiated — it is during the class instantiation that bb issues the class-instantiation notifier … it only happens once per Zen Cart page!

    The class provides the parameters required for each notifier "call" through an associative array that is subsequently passed to the observer's update function via the $paramArray input. On return, a properly operating observer will set the bb class's return_status variable to reflect the completion status of the "call", either bb::STATUS_OK or bb::STATUS_ERROR. If the observer returns bb::STATUS_ERROR, an additional variable error_status can be set to identify further error information.


    Installation

    There are core-file overwrites in this plugin; you should always backup your databases and files prior to making any changes.

    1. Determine the version of your base Zen Cart installation
      1. For Zen Cart v1.5.1, copy the file /zc151/includes/auto_loaders/config.core.php to /includes/auto_loaders/overrides/config.core.php
      2. For Zen Cart v1.5.2, copy the file /zc152/includes/auto_loaders/config.core.php to /includes/auto_loaders/overrides/config.core.php
      3. For Zen Cart v1.5.3, copy the file /zc153/includes/auto_loaders/config.core.php to /includes/auto_loaders/overrides/config.core.php
      4. For Zen Cart v1.5.4, copy the file /zc154/includes/auto_loaders/config.core.php to /includes/auto_loaders/overrides/config.core.php
    2. Rename the three (3) YOUR_TEMPLATE directories to match your custom template's name:
      1. /includes/modules/sideboxes/YOUR_TEMPLATE
      2. /includes/modules/YOUR_TEMPLATE
      3. /includes/templates/YOUR_TEMPLATE
    3. Copy the remaining plugin files to your Zen Cart installation:
      1. /includes/classes/class.bb.php
      2. /includes/languages/english/extra_definitions/YOUR_TEMPLATE/bb_definitions.php
      3. /includes/modules/pages/account_edit/header_php.php
      4. /includes/modules/pages/account_password/header_php.php
      5. /includes/modules/pages/create_account_success/header_php_bb.php
      6. /includes/modules/pages/password_forgotten/header_php.php
      7. /includes/modules/sideboxes/YOUR_TEMPLATE/information.php
      8. /includes/modules/YOUR_TEMPLATE/create_account.php
      9. /includes/templates/YOUR_TEMPLATE/templates/tpl_account_edit_default.php
      10. /includes/templates/YOUR_TEMPLATE/templates/tpl_create_account_success_default.php
      11. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_create_account.php
      12. /includes/templates/YOUR_TEMPLATE/templates/tpl_site_map_default.php

    Un-install

    Replace core files that were previously overwritten and then delete the new files that were previously copied.