So, you’ve discovered the world of openGoo. It does a pretty good job overall but now you want to add some custom flavour! Where do you start? What are the options?

Firstly, I’d recommend running through the “Hello World” application tutorial (that can be found HERE ) as it gives you a quick overview of the control flow of openGoo. If you’re not familiar with MVC (Model-View-Controller) programming it’d be a good idea to take a few moments to read up on the principles of a MVC system, get the basic idea of what each component should be used for. I’ll be looking at the MVC of openGoo in a future blog post, for now we’re moving on to the Hooks.

If you’ve had previous experience with customization of a CRM / CMS / Web application you might be familiar with the concept of hooking / hooks. A hook is one of the easiest and fastest way to extend and application’s functionality in an upgrade safe way. And believe me, you want to keep your customizations as much upgrade safe as possible. Trying to figure out why a customization you did a year ago broke isn’t as fun the second time, it tens to ends in a complete rewrite of the initial customization. There’s nothing that frustrates me more than having to re-write code.

A hook is basically a place where you can “hook” in your custom code without having to change anything to the existing code. In fact, you don’t need to know how the rest of the package works to use a hook.

Using a hook in openGoo is as easy as 1, 2, 3.

1. Create a new php file in the ‘Application/Hooks’ directory, which will contain your custom code. Example: ‘opengoo_hooks.php’ , ‘myhooks.php’

2. Register your hook
   
   Hook::register(“opengoo”);
   
   The string used when registering the hook can be anything, as far as I can see its used as a key in the array where the hooks are stored. You could use this key to reference a specific hook later in your code, if needed. I’ll refer to this as the [hook_key] later. Also note it may be a good practice to name your php file “[hook_key]_hooks.php”.

3. Define the hook function.

function opengoo_render_upload_control($args, &$ret) {
if (upload_hook() == ‘opengoo’) {
$attributes = $args['attributes'];
echo file_field(‘file_file’, null, $attributes);
}
}

Note that the function name should be of the format ‘[hook_key]_[hook]‘.

In the above example [hook_key] = ‘opengoo’ and [hook] = ‘render_upload_control’.

Working example:

Lets say we want to customize one of the layouts on openGoo. For this example lets change the Login layout for illustration. Instead of overwriting the layout file in “Applications/Layout” we can simply define a hook to set the layout to be used to our new custom layout.

Default Layout of login dialog

First lets create our hook file. I created a file “example_hooks.php” in the ‘Application/Hooks’ folder.

<?php

/* Register your hook else it won’t fire! */
Hook::register(“example”);

/* Define hook functions */
function example_override_action_view($controller, &$ignored) {
/* Check which controller has fired the hook */
if ($controller->getControllerName() == ‘access’) {
/* Check that the action is ‘login’ */
if ($controller->getAction() == ‘login’) {
$controller->setLayout(‘example’);
}
}
}

?>

I’ve used the ‘override_action_view’ hook for this example. This hook gets fired by all the controllers. We want to change the layout of the login form so we need to set the new layout when the ‘login’ action of the ‘access’ controller is called. After we’ve tested that we’re at the right spot we can change the layout by calling the “setLayout” method of the controller.

You can use the getLayout method to see what layout is currently being used. In this example the original layout being used is ‘Application/Layouts/dialog.php’

Next step, we need to create our new layout ‘example’. Note you use the file name without extension to set the layout, openGoo automatically looks for the layout in the ‘Application/Layout’ folder. Create a copy of the dialog.php in ‘Application/Layouts’ and rename it to ‘example.php’. Open up ‘example.php’ and make some changes to the layout. I simply added an image below the dialog div and the word “example” to the H1 tags.

<img src=”<?php echo get_image_url(“jack.jpg”) ?>” height=”250px”>

I put the image of Jack, my trusty testing duck, in ‘public/assets/themes/default/images/jack.jpg’ the ‘get_image_url’ function fetches the image URL according to the selected theme.

Browse to the login dialog page and ‘Hello Jack!’. It’s that simple to add a duck to your openGoo login page.

Custom 'example' Layout

List of available hooks: ( for more detail take a look at ‘Application/Hooks/opengoo_hooks.php’ )

/*
* – render_page_actions: Called when drawing actions for an object’s view. Call add_page_action to add actions.
* – render_page_header: Called when drawing the page header.
* – render_getting_started: Add additional getting started help.
* – render_object_properties: Called when drawing properties for an object’s view. Echo the HTML to be drawn.
* – reminder_email: Called when an email reminder is being sent.
* – render_userbox_crumbs: Called when drawing the userbox (top-right of the page).
* – autoload_javascripts: Tells which javascripts should be load when the application starts.
* – autoload_stylesheets: Tells which CSSs should be loaded when the application starts.
* – render_administration_icons: Called when drawing administration panel.
* – object_definition: Allows to define extra columns for a system object.
* – render_object_description: Called when rendering the description that goes below the title in an object’s view.
* – permissions_sql: Called when generating the SQL permissions string for object listings.
* – can_access: Called before checking access permissions for an object.
* – object_edit_categories: Called when rendering categories for an object creation or edition interface.
* – object_validate: Executed before saving an object to validate object fields.
* – before_action: Called before executing an action to determine if the action will be called.
* – override_action_view: Called before generating an action’s view, so that you can change it.
*/

Fire your own hooks from your custom module:

To create and fire a hook from your own module, you simply call the static fire method of the Hook class.

Hook::fire($function, $argument, &$ret)

$function : String containing the name of the hook. Example ‘ render_page_actions’.

$argument : Arguments passed to the hook. For the built in hooks this is normally the current controller.

$ret : The value

Well that’s it for hooks in openGoo. This is meant as a starting point for customization, I’m sure there’s more to be added, any input is welcome. In the next blog I’ll be showing how to create a simple Bulletine Board type module.

OpenGoo is an open source web office developed by Feng Office and the OpenGoo community. It can be used for project management, including the scheduling of tasks and milestones, document storage, contact and calendar management, email receiving (POP3 or IMAP) and sending(SMTP) and runs on a PHP webserver with MySQL installed.

Continue reading