====== Advanced Plugin Tutorial ======
//Note: This is a work in progress and will be completed over the course of many weeks (or months if I can't find enough spare time).  This task is made more difficult by the current lack of reference guides.  Any and all help will be appreciated, as will be suggestions for improvement.  [[http://forums.fengoffice.com/index.php?action=profile;u=15058|Potion]] 17 December 2012//

//Acknowledgement: In this tutorial I will implement an invoicing system, and will use the business logic and table structure in [[http://www.simpleinvoices.org/|Simple Invoices]], with their permission.   [[http://forums.fengoffice.com/index.php?action=profile;u=15058|Potion]] 20 December 2012//

----
This tutorial will explore more advanced features for development of Feng Office plugins.  In addition to the basics covered in the [[plugins_documentation|Hello World Plugin Tutorial]], the topics covered will include:

  * Object types and managing a list of objects in a tab panel
  * Enabling your plugin's objects to be categorized using Feng Office dimensions
  * Adding a component in the Administration Tab to control your plugin's settings
  * Adding a report component in the Reporting Tab
  * Providing Install and Uninstall scripts for your plugin

====== Setting Up ======

We will employ an Agile development approach so that after each stage ([[http://en.wikipedia.org/wiki/Scrum_%28development%29|Scrum & Sprint]] ) we have a viable, usable system.

Initial setup:
  * Install a new instance of Feng Office
  * Install a new instance of Simple Invoices using the same database (and user and password) as the Feng Office installation.

Initially each application will run separately from the other, and the only integration at this point will be:
  * A shared database.
  * A new tab in Feng Office to hold the Simple Invoices view in an iframe.

Run both applications, each in its own browser tab, to make sure they both run.

====== Create the Basic Plugin ======
The first iteration in our agile development is to create a basic plugin that will run the Simple Invoice app in a Feng Office tab.
===== Filesystem Skeleton =====
**FENGOFFICE_ROOT**
  * **plugins**
    * **invoices**
      * **application**
        * **controllers**
          * InvoicesController.class.php
        * **views**
          * **invoices**
            * manage.php
      * **language**
        * **en_us**        // (add languages as required) //
          * lang.js
          * lang.php
      * info.php

 

===== File Contents =====

<code php InvoiceController.class.php>
<?php class InvoicesController extends ApplicationController {                
        var $plugin_name = "invoices"; //name of the plugin
 
        function __construct() {
                parent::__construct();
                prepare_company_website_controller($this, 'website');              
        }

        function manage() {
	/* for now, do nothing - the invoices app will load in the view */
        }
}?>
</code>

<code php manage.php>
<iframe src="http://mydomain.com/simpleinvoices" <? /* Link to Simple Invoices Doc Root */ ?>
        width="100%"
        height="500px"
        id="invoices"
        marginheight="0"
        frameborder="0" >
</iframe>
</code>

<code php info.php>
<?php return array(
    "name" => "invoices",
    "version" => "0.1",
    "author" => "My Name",
    "website" => "http://www.mydomain.com",
    "description" => "Simple Invoices Plugin for Feng Office",
    "tabs" => array (
                array(
			"id" => "invoices-panel",
                        "ordering" => 2,
                        "title" => "invoices tab",
                        "icon_cls" => "ico-invoices",
                        "refresh_on_context_change" => true,
                        "default_controller" => "invoices",
                        "default_action" => "manage" , 
                        "initial_controller" => "" ,
                        "initial_action" => "" ,
                        "type" => "plugin",
                        "object_type_id" => 0
                )
     )
);?>
</code>

<code js lang.js>
	locale = 'en_us';
	var langObj = {};
<?php $lang_array = include 'lang.php'; ?>
		
<?php foreach ($lang_array as $k => $v): ?>
	langObj["<?php echo $k ;?>"] = "<?php echo $v ;?>" ;	 
<?php endforeach ;?>
	addLangs(langObj);
</code>

<code php lang.php>
<?php return array(
	'invoices tab'=>'Invoices',
);
</code>

We'll use an icon for our tab from the default theme's sprites. Insert a line into the relevant CSS file, FENGOFFICE_ROOT/public/assets/themes/default/stylesheets/file/types.css

<code css>
.ico-invoices{
	background: transparent url(../../images/16x16/all_16_16_vertical.png) no-repeat scroll 0 -336px !important;
}
</code>

===== Activate Invoices Plugin =====

Ensure that the plugin manager is enabled by inserting the following line into FENGOFFICE_ROOT/config/config.php
<code php>
  define('PLUGIN_MANAGER', true);
</code>

In Feng Office, navigate to **Administration-->Plugins** where you can **Install** and then **Activate** the invoices plugin.  Now navigate to **Administration-->Tabs**, ensure that **invoices-panel** in enabled and hit **save changes**.

Our new tab **Invoices** should now appear.  Click on it and log into Simple Invoices.

//Remember that Simple Invoices is running as a separate application and therefore requires its own login.  As per our Agile objective, we now have a usable invoicing system.//
----
//Work In Progress.  To Be Continued...//