Getting started with MageBridge - Yireo

Creating custom store connectors

While MageBridge uses the regular Joomla! plugin-systems to connect various third party applications to MageBridge, there is also a thing called "connectors" that allow you - as a developer - to change the inner-workings of MageBridge. In this tutorial you will learn more on how to create your own store connectors to connect to a specific Magento store (Store View or Store Group).

Note: For this tutorial you need to upgrade to at least MageBridge version 1.1 build 731.

Store connectors

Connectors are plugin-like things, but named "connectors" to avoid confusion. Connectors are used to connect some kind of Joomla! logic to MageBridge to do something else. It sounds very vague, but this is just because of the flexibility. One kind of connector is a "store connector" - here, some kind of Joomla! logic is used to choose a specific Magento store when loading the page.

The practical use of store connectors becomes more appearant when we explain how MageBridge uses these store connectors to integrate multi-lingual extensions like Joom!Fish or Nooku. Connectors are in general easy to write, so besides adding support for another multi-lingual extension, there are many other scenarios for which you could add your own store connector.

Why write your own connector?

You could write your own store connector to load a specific Magento store when logged in as a Super Administrator. You could load a specific Magento store when coming from a certain set of countries. You could also load a specific store depending on the time of year. There are many options available.

You can add store connectors by yourself and as long as you use an unique name, your connector will not be overwritten. We do not offer an installation-mechanism yet, but as you will learn in this tutorial, there are just a few manual steps to take to add your own connector to the MageBridge system.

How multilinguality works

These multilingual Joomla! extensions use a simple principle to determine the current language of a page - they set some kind of language-variable in the request (GET or POST) and read the variable in on the next page. Once the language is set, the extension makes sure the Joomla! system language is changed accordingly, and the translatable equivalent of the current content is loaded on the page.

Magento implements multiple languages in a different way - by assigning a language (locale) to a specific Store Group or Store View. While MageBridge limits you to using one Website per Joomla! install, you can use various Store Groups or Store Views inside one Joomla! install. Store connectors are used to determine the logic here.

A store connector (like the Joom!Fish or Nooku connector) has two main tasks: It offers HTML to configure the condition (languages in the case of Joom!Fish and Nooku) and it has a method to check whether that condition is occurring. Through the Joomla! Administrator each option (each language) is connected to a Store Group or a Store View - a combination of an option and a Magento store is referred to as a "condition".

When loading a page on the frontend, the connector will be asked if the configured condition is true - it will for instance check if the German language-code is set in the HTTP request. If true, the configured Magento store for that condition is loaded. If false, MageBridge continues to the next connector (if any) and otherwise loads the default store.

The connector file

Store connectors are placed in the Joomla! folder "components/com_magebridge/connectors/store". Each connector needs only one file and one database entry. By default, you will find in the folder the files "joomfish.php" and "nooku.php". These files serve as a good example.

Each file contains a class which follows the naming convention "MageBridgeConnector{STORE}{CONNECTOR}", where {STORE} stands for the type-connector (in this case "Store") and {CONNECTOR} stands for your own connector-name ("Foo"). The class must extend the connector parent-class as shown below:

class MageBridgeConnectorStoreFoo extends MageBridgeConnectorStore

Next, the class should contain the following methods:

• isEnabled(): This returns a boolean telling whether this connector can be used at all. For instance, the Nooku connector will check if the Nooku extension exists. If not, there's no point in using the Nooku connector. If this method returns false, the connector is grayed out within the MageBridge Connectors page in the Joomla! Administrator. The parent class checks if the connector is published or not, so you could just return true here.
• getFormField($value = null): This returns a chunk of HTML that will inserted in the backend when selecting the proper condition. The form-element can be anything (textarea, select, radio, modal box), just make sure its form-name is unique - we recommend using a "name" and "id" that starts with your own connector-name.
• getFormPost($post = array()): The chunk generated by the earlier getFormField() method should generate some kind of value in the POST request. The getFormPost() method checks the POST-values for the right value and returns that value. The result of this value is stored in the database table #__magebridge_stores as field condition. If your form-element generates some kind of POST-array, you need to convert that POST-array into a string.
• checkCondition($condition = null): This most important method receives the condition (stored in the database table #__magebridge_stores) as argument, and checks if this condition is true or not - it should return a boolean. For instance, the Joom!Fish plugin checks whether the given argument matches the REQUEST-variable "lang".

The connector database entry

To make your own connector-file usable in MageBridge, you need to add an entry in the database table #__magebridge_connectors. You can add a new entry with the following fields:

• id: Primary key with auto_increment value
• title: A friendly title for the connector
• name: A system name for the connector which needs to be unique
• type: The type-name which can currently be only "store"
• filename: The filename of the PHP-script in the "connectors/store" folder
• access: Unused at the moment
• ordering: To be configured from the Joomla! Administrator
• published: To be configured from the Joomla! Administrator
• iscore: We highly recommend to set this to 0 when creating your own connector
• checked_out: To be configured from the Joomla! Administrator
• checked_out_time: To be configured from the Joomla! Administrator
• params: A list of parameters if needed for your connector

Basic code sample

The following code serves as a good start for writing your own store connector:

// Always check for direct access
defined( '_JEXEC' ) or die();

class MageBridgeConnectorStoreFoo extends MageBridgeConnectorStore
{
    public function isEnabled()
    {
        return true;
    }

    public function getFormField($value = null)
    {
        $html = '<input type="text" name="foo_value" value="'.$value.'" />';
        return $html;
    }

    public function getFormPost($post = array())
    {
        return $post['foo_value'];
    }
    
    public function checkCondition($condition = null)
    {
        if($condition == 'TEST') {
            return true;
        }
        return false;
    }
}