activeCollab blog

Anatomy of activeCollab Modules: Request

Ilija Studen — Thu, 03 Jul 2008 07:49:16 CDT

As we described in previous article, purpose of controllers is to load data and provide it to views based on request. Everything up to that point is handled by activeCollab - mapping URL with appropriate controller and action, loading resources, preparing request data etc. When all that is done $request property is set in controller and you can use it to access request details and data. Here is an example:

class SomeController extends ApplicationController {

  function some_action() {
    $user = Users::findById($this->request->get('user_id'));
    if(instance_of($user, 'User')) {
      $this->renderText('User found and loaded');
    } else {
      $this->renderText('User not found');
    }
  }

}

There are two methods that you will be using to access request variables:

get($variable_name) - returns a specific variable value that was provided to the script through URL
post($variable_name) - returns a specific variable value that was provided through POST method

Basically, there are two types of requests user can make:

Request specific data without it being modified (like - show me project or ticket details).
Submitted requests that ask system to modify specific data (edit comment, move discussion to trash, mark task as completed, delete project etc).

For request to be recognized as submitted it needs to be a POST request with variable "submitted" set to "submitted". There is a helper method that will check this for you with a single call - isSubmitted():

<form action="/something" method="post">
  <input type="text" name="input_value" />
  <input type="hidden" name="submitted" value="submitted" />
  <button type="submit">Submit</button>
</form>

Controller code:

class SomeController extends ApplicationController {

  function some_action() {
    if($this->request->isSubmitted()) {
      $this->renderText('Form is submitted. Value: ' . $this->request->post('input_value'));
    } else {
      $this->renderText('Form is not submitted');
    }
  }

}

Additionally, activeCollab recognizes following requests:

Request made through API. You can check whether request is made through API by calling isApiCall() function.
AJAX request. Use isAsyncCall() to check if request is AJAX call. These request are usually made to load data or execute an action, but return only specific page element instead of full page.

In the next article we'll see how activeCollab's clean URL-s map with specific controllers and actions and how request objects are populated with data. Stay tuned!

Anatomy of activeCollab Modules: Controllers

Ilija Studen — Mon, 30 Jun 2008 13:05:05 CDT

In the first article of Anatomy of activeCollab Modules series we explained what activeCollab modules are and which key blocks make a module. Now we'll talk more about one of the most important parts of any module - controllers.

Controllers are used to handle user request. Based on the request they decide how it will be handled, which data needs to be loaded and how it will be presented to the user. Every controller is made out of multiple actions. If action is not specified in the request default action will be used - index().

class MyController extends Controller {

  function index() {
    // Default action
  }

  function do_something() {
    // Additional action
  }

}

Most of the time you will use controller and views to render web pages with HTML output, but controllers can also be used to serve data in other formats (CSV, iCalendar etc) or provide an interface to your application to other applications by serving data in XML and JSON format.

Rendering content

All view interaction is done through $smarty instance available in every controller. You can assign values to the views by calling assign method:

$this->smarty->assign('variable_name', $variable_value);

or:

$this->smarty->assign(array(
  'first_variable' => $value1,
  'second_variable' => $value2,
));

If you don't provide an exit from the action by redirecting user or breaking execution with die() activeCollab will automatically resolve template path based on controller and action name and render it. For instance, if we have TestController and show() action in backend module view that will be automatically rendered will be located in:

activecollab/application/modules/backend/views/test/show.tpl

Notice how module, controller and view names are mapped with physical location of the template on the file system.

Views can also be rendered manually. Generated content can be directly forwarded to the browser or returned as a string:

$this->smarty->display($template_path); // directly to browser
$str = $this->smarty->fetch($template_path); // render to string

Redirecting

There are three important method used to redirect users to other pages:

redirectTo($route_name, $params = null, $options = null) - this function will assemble URL based on parameters provided and redirect user to it. It takes same parameters as assemble_url() function.
redirectToUrl($url) - Redirects user to a given URL.
redirectToReferer($alternative) - Redirects user to the referring page. If activeCollab fails to resolve referring page $alternative URL is used as a fallback.

Resources available in controllers

In every controller that inherits ApplicationController you have following variables you can use:

$smarty - Smarty instance that you can use to assign variables to templates, display or fetch them etc.
$request - Request object with all request details, including parameter values passed to the application through GET, POST and routing mechanism.
$application - Instance of activeCollab application with application related information and routines.
$authentication - Instance of AuthenticationProvider used to authenticate the user.
$logged_user - Instance of logged in user. If no user is logged in this value will be NULL.
$owner_company - Owner company instance.
$theme_name - Name of the theme used.

Inheritance

activeCollab controllers rely a lot on inheritance. For instance, if you want to add a functionlity to a project (Events for example) best would be to inherit ProjectController. This way you'll have $active_project instance with loaded project available automatically, access permissions checked and interface prepared (tabs, bread crumbs etc):

class EventsController extends ProjectController {

  function index() {
    $this->renderText($this->active_project->getName());
  }

}

Common controller that are usually used as a foundation for additional functionality:

ApplicationController - Base controller used for any custom functionality. All activeCollab controllers inherit this controller and it's properties are available in all of them.
ProjectController - Used in situations where you need a project selected. Tickets or time tracking controllers extend this controller for example. You'll have additional $active_project property set with selected project loaded and access permissions checked.
PeopleController - Used as a foundation for all People section related pages.
AdminController - Used as a foundation for administration related functionality. Administration access permissions are checked.

Anatomy of activeCollab Modules

Ilija Studen — Wed, 11 Jun 2008 10:57:37 CDT

Modules are one of the most important new features introduced in activeCollab 1.0. The entire system was rewritten from the ground up to be modular and extensible. activeCollab modules are flexible enough to be used for simple features such as public submit, as well as for complex sections like people management or tickets.

Every activeCollab module is a mini MVC application, where MVC stands for Model View Controller. MVC is a code separation method that lets us have our code organized well and maintainable while keeping the flexibility we need.

Model defines business logic - objects we are working with and how they interact. It lets us define things like - discussions can have multiple posts; post can belong to only one discussion; when discussion is deleted all of its post are also deleted etc. Model is the only layer that has direct access to database, file system and web services.

View is layer used to prepare application data in format that client can understand. In our case, client is a web browser and the output format we is HTML. We use Smarty to power view layer in activeCollab. It offers great flexibility while keeping templates simple and familiar (in most cases Smarty tags looks a lot like regular HTML).

Final layer is controller. It is used to process user request, load data through model and offer output generated by view to the client (web browser). Basically, this layer knows that you requested project overview page, loads all the details we need for that page and makes sure that view prints proper content.

In future articles we’ll explore all these layers in more details so stay tuned.

activeCollab 1.1.2 - Available for Download

Ilija Studen — Tue, 10 Jun 2008 04:11:31 CDT

We are proud to announce that activeCollab 1.1.2 is available for download from View Licenses page of your activeCollab.com profile (as outlined on the image bellow).

This is a bug fix release with more than 30 fixes and enhancements. Full list of enhancements and fixed bugs is available in release notes.

Installation instructions haven't changed and are described in this document.

If you are upgrading please note that you will need to run upgrade script to keep your database up to date as described in upgrade instructions.

As always, if you have any questions or need any assistance you can reach us at support@a51dev.com. Thanks for choosing activeCollab!

New Service: Professional Installation and Upgrade

Ilija Studen — Sat, 07 Jun 2008 12:51:11 CDT

From Monday, June 9^th we will start offering installation and upgrade services. This services are for people who just want system up and running without the need to install or upgrade activeCollab by themselves. All we need are parameters for FTP and database connection and we'll handle everything else.

Here is what we offer:

Installation of new activeCollab setups on your server
Upgrade of any activeCollab 0.7.1 or newer installation to the latest version
Minimal downtime (usually just a couple of minutes for activeCollab 1.0 and later, may take a bit longer for 0.7.1 if you want to keep the same URL)

This service is available to anyone who has a valid activeCollab license from View Licenses page of their activeCollab.com profile:

In order to receive this service you’ll need to purchase credits from our online store. One credit is $49 and can be used for a single installation / upgrade intervention.

We are introducing this service to help our customers and save them time. We will continue to work to make upgrade and installation as easy as possible in the future but we know that many people don’t want to waste their time on software management and just want to have it handled by a professional.

Important: People who are installing / upgrading activeCollab by themselves get assistance in case of any problem as part of their yearly support plan. Only people who want everything handled by us are obliged to purchase Installation / Upgrade credits.

How Superawesome uses activeCollab

Ilija Studen — Thu, 05 Jun 2008 14:24:08 CDT

Guys at Superawesome just wrote an article where they explain how they are using activeCollab in their design agency. Here is my favorite quote:

activeCollab is the core of our operation. I can not imagine managing all our projects without it [...]. If you are in need of some help in this field – activeCollab is definitely the app for you, and once you start noticing the benefits you'll justify the price easily.

Full article with a lot of details about how they use specific features is available here: The way we work in activeCollab. Also don't forget to browse through their blog archives. Dragan is a pretty open guy and there is a lot to be learned just by reading how other people approach problems they are dealing with every day - communication, work with clients, etc.

If you want to share how you use activeCollab just let us know. We take every opportunity to learn more about our customers and how they are using activeCollab. It help us improve the tool and bring more value and useful features to you.

activeCollab 1.1.1 Available for Download

Ilija Studen — Thu, 29 May 2008 04:59:49 CDT

We are proud to announce immediate availability of activeCollab 1.1.1. This is a bug fix release that covers more than 10 issues reported for 1.1 version. Read more about enhancements and fixes in activeCollab 1.1.1 release notes.

Installation and upgrade instructions are available here and here.

If you are new to activeCollab 1.1 here are some highlighted features:

Project templates
Localization
Improved time tracking with global reports
Assignments filtering
Interface for mobile devices, iPhone included
New module that lets you submit tickets without the need of having an account in activeCollab, Twitter like group "chat",
ability to export projects as static website and much much more.

Check out activeCollab 1.1 release notes to see the full list of new features and improvements.

If you have any questions or need assistance you can reach us at support@a51dev.com or through community forums.

activeCollab 1.1 is here! Project templates, localization, iPhone support and much more!

Ilija Studen — Thu, 22 May 2008 07:20:45 CDT

We are proud to announce that activeCollab 1.1 is available for download. This is really big and important version. It brings a lot of new features and improvements, all of them based on feedback that we got from our customers:

Project templates
Localization
Improved time tracking with global reports
Assignments filtering
Interface for mobile devices, iPhone included
New module that lets you submit tickets without the need of having an account in activeCollab, Twitter like group "chat", ability to export projects as static website and much much more.

Here you can check release notes with all new and improved features listed. Installation instructions are available here, but if you are upgrading then don't forget to check out this document.

Of course, we are available at support@a51dev.com for all of your questions or in case that you need help with the installation or upgrade.

Working with files and presenting your work with Files module 1.1

Ilija Studen — Mon, 07 Apr 2008 13:49:29 CDT

Files module in activeCollab 1.0.6 lets you upload and download files, put them in categories, add new versions, post comments on files and more. Although it's pretty much enough on most occasions, we wanted to go even further with this module at activeCollab 1.1.

The first thing that you’ll notice within the updated Files module is the new and improved listing of files. Now you have icons displayed for all common file types. If you upload an image, then activeCollab will create a thumbnail and use it instead of icon so you can have a quick preview of the image right there in the list:

One of the common requests we used to receive is to also include the attachments from other project areas and show them in files list. We did so, and it looks great. Attachments have a little paper clip next to download button so they are easy to spot.

Another big improvement over the old Files module is the way files are uploaded. Upload files form in activeCollab 1.1 lets you upload more than one file at once:

You can select the milestone to put these files to, you can put them in categories and tag them. To make sure that people get notified about them being uploaded, just select desired users in Notify People field. After you set all details you want, just hit submit and let activeCollab handle all the details.

Each uploaded file has its own details page where you can check older and upload new file versions, you can discuss about it with your team and clients, subscribe to receive email notifications on any update and more:

These are the most important changes we made to Files module, but there are also many more smaller ones that will make everyday use of this module pretty much easier. We hope you will like the changes we made, and help us to finish activeCollab 1.1 as soon as possible by testing beta builds that we post regularly in our community forums.

Reminders, new feature in activeCollab 1.1

Ilija Studen — Thu, 03 Apr 2008 12:58:02 CDT

In activeCollab 1.1 we added an easy to use way to notify people: reminders. Reminders are easiest to explain with example. For instance, we have a ticket where you expect someone to do something, something like to upload a new activeCollab version to the server. For some reason, responsible person is not taking any action and you want to know why. We've all been in that type of situation before.

First you click on Send Reminder link:

In the popup window, select who you want to notify and insert optional comment:

When you hit the submit button, an email will be sent to the selected people, and next time they log in they will have this ticket reminder highlighted in “Things that require your attention” block at the Dashboard.

This feature will help you improve the communication with your team members or clients in only 3 clicks. We at A51 already find this simple tool extremely helpful and hope that you’ll like it as much as we do.

Reminders are coming to both Small Biz and Corporate version.