Feng Office Plugin Tutorial: Hello World

In this tutorial you will be able to create a basic plugin, that will provide you general understanding of how Feng Office Plugin System works and how to develop more complex extensions for this platform.

First of all, choose the plugin name - which we will call PLUGIN_NAME to make it generic -: in this case we will take the Email plugin as an example provided that anyone can access it: 'mail'.

Create a folder named 'PLUGIN_NAME' under FENGOFFICE_ROOT/plugins.

All the necessary resources and code for your plugin will be placed here: javascripts, css, images, php (templates, views, controllers, models).

The first file you need to create is the plugin metadata 'info.php'. Create this file under you plugin root folder 'plugins/PLUGIN_NAME/info.php' containing this php code:

<?php return array(
        "name" => "mail", //name of the plugin
	"version" => "1", //version of the plugin
	"author" => "Feng Office", //author
	"website" => "http://fengoffice.com", //website of the author
	"description" => "Email web client", //brief description of the plugin
	"dependences" => array('core_dimensions'), //if the plugin depends on another plugin to work correctly
	"order" => 1
);?>

This will provide information about the plugin version, description, order, dependences, category, author and other metadata necessary for third party plugin management.

If you want to create a new tab or associate it with a content object, you have to specify to the metadata file some extra configuration as shown below:

<?php return array(
       "name" => "mail",
	"version" => "2",
	"author" => "Feng Office",
	"website" => "http://fengoffice.com",
	"description" => "Email web client",
	"dependences" => array('core_dimensions'),// Array of plugin names (TODO check dependences)
	"order" => 1,
        "types" => array ( //association it with a content object
		array(
			"id" => 22, //id of the content object
			"name" => "mail", //content object name
			"handler_class" => "MailContents", //name of the handler class
			"table_name" => "mail_contents", //name of the table containing it
			"type" => "content_object", 
			"icon" => "mail", //icon of the content object
			
		)
	),
        "tabs" => array ( //tab creation
                array(
                        "id" => "mails-panel", //plugin id
                        "ordering" => 2, //order of the tab when shown among the rest, 0 being the first
                        "title" => "email tab", //lang that will be used to specify the tab name
                        "icon_cls" => "ico-mail", //icon that will have tab
                        "refresh_on_context_change" => true, 
                        "default_controller" => "mail", //name of the controller 
                        "default_action" => "init" , //first action it will do when loading 
                        "initial_controller" => "" , 
                        "initial_action" => "" ,
                        "type" => "plugin", //type
                        "object_type_id" => 22 //id of the content object if it is related to one
                )
        )
);?>        

This tells the installer that it will have to create a new tab in the system, specifying id, title and many other configuration options, but the most important ones are default_controller and default_action.

At this point we are assuming that you are familiarized with MVC concepts, if this is not your case we suggest you to read some other documentation about this design pattern. Create a folder 'application/controllers' under your plugin structure, and create the following class under this folder:

<?php class HelloworldController extends ApplicationController {                
        var $plugin_name = "helloworld";        
        function __construct() {
                parent::__construct();
                prepare_company_website_controller($this, 'website');
        }


        function say_hello() {
                $txt = "Hello World ! ! ! ! ";
                tpl_assign('message',$txt);
        }
}?>

In this case the controller loads the data, and assigns it to the view in a variable called 'message'. Note: We have not spoken about models yet, so the data is hard-coded in order to simplify the example.

Create a folder 'application/views/helloworld' under your plugin structure, and create the following template: 'say_hello.php'

<div class="hello-world">
        <h1><?php echo $message ?></h1>
        <p>Congratulations ! ! !</p> 
        <p>This is your first hello world application. <p>
</div>

Note: When invoking a cotroller action (or method talking in OOP), the system automatically loads the view named 'ACTION.php'.

Custom CSS and JS can be done in many ways:

INLINE (not recommended):

Each view can make use of <script> and <style> tags, but this does not follow the best practices of web development

Automatically load the css JS (recommended):

While loading a page, Feng Office will include the JS and css on its head section if you create those files following this convention: plugins/PLG_NAME/public/assets/javascript/PLG_NAME.js plugins/PLG_NAME/public/assets/css/PLG_NAME.css

At Runtime

In any place of your controller method add the following line: require_javascript('WhateverYorJsIsNamed.js', $this→plugin_name); Sometimes you want to include JS libraries only on some user actions, so this way is better if that is your case.

Look here for further information on how to install, activate or upgrade your plugin.