Short course about ZOO (JBZoo) component API

10.0/10 rating (1 votes)

If you don’t know how to use PHP, this article is definitely not for you, you can stop reading here.

A big plus will be if you understand OOP, know the difference between a view and a controller, let alone can distinguish an Abstract Factory from a Bridge and an Adapter.

Inner API of ZOO and JBZoo (hereafter simply Framework) is pretty rich so it’s not possible to explain everything at once. In this article we’ll briefly overview main features of the Framework but 90% of the material will be as homework that should not be very hard. So, let’s start with easy things.

What are helpers?

In ZOO (and in programming in general) there is such concept as helpers.

They are various useful functions grouped together by implication that form small classes. Helpers are not to be confused with libraries which are usually something external, not closely integrated with the system in general.

There are helpers for various purposes, starting from system global (for example, to control paths in the system) to peripheral (for avatars in comments).

It is important to understand the difference between a class and a helper.

A helper has lazy initialization and is created automatically. This means that until you address to a helper for the first time, a file will not be included and an instance will not be created. Usually, only one instance of a helper is created. Actually, this is a “multiton” OOP pattern.

There is one more important characteristic - a helper should not keep a state. It should always be considered as a set of tools and not as a specific website entity (entities have models, for example). Otherwise you should reconsider the logic of your extension.

Where helpers are located?

You can find the in these locations. Different folders are used only to group helpers. So

System helpers - /administrator/components/com_zoo/framework/helpers/

Main ZOO helpers - /administrator/components/com_zoo/helpers/

JBZoo helpers (they all have “jb” prefix) - /media/zoo/applications/jbuniversal/framework/helpers/

Reloaded standard helpers - /media/zoo/applications/jbuniversal/framework/helpers-std/

How to work with helpers?

In order to work with helpers, ZOO has App class. This is a specific access point to various framework functionality. You can access it using two methods:

// In any code (even Joomla), an argument is always the same and indicates global ZOO namespace
$app = App::getInstance('zoo');
// The code is executed in a context of any framework entity
$app = $this->app;

Important notice. The above code does not copy an object but receives a link to it. That is, if you change it in one part of the program, it will affect other parts as well.

After calling a singleton App we receive a helper class by the name of the file and call its method.

Like this, for example:

/*
   item method will be called from /administrator/components/com_zoo/helpers/route.php
   This way you can get a link to an item by having necessary instance
*/
$itemUrl = $this->app->route->item($item);
echo '<a href='.$itemUrl.'>Link to the page</a>';

Useful examples with helpers.

How to get an item or a category object from the database by its ID:

$item = $this->app->table->item->get(42);
$category = $this->app->table->category->get(42);    

Resizing an arbitrary image with caching:

// built-in function for image resizing (only full (absolute) paths)
$thumbFullpath = $this->app->zoo->resizeImage($OriginalFullpath, $width, $height);

// JBZoo wrapper that can work with relative paths but will return an object
$thumbInfo = $this->app->jbimage->resize($OriginalPath, $width, $height);

// the result
$thumbInfo->orig // full path to the original file
$thumbInfo->origUrl // full path to the original file for a website (a link)
$thumbInfo->path // full path to the thumbnail
$thumbInfo->rel // relative path to the thumbnail
$thumbInfo->url // full path to the thumbnail for a website (a link)
$thumbInfo->height; $thumbInfo->width // height and width of the thumbnail

Working with paths

Our framework has such concept as virtual paths of the file system.

The point is that several different real paths can be assigned to the same key at the same time. After that you can address this key and a helper will automatically browse through all real paths and find a file. This feature is very handy but can be hard to understand at first. We’ll try to explain it using an example.

Let’s assume that we want to know the full path to the helper for the jbcart shopping cart.

We write this code:

// a colon separates a key (virtual path name) and a relative path to a file
$helperPath = $this->app->path->path('helper:jbcart.php');
dump($helperPath); // full path to the jbcarp.php file

So, what exactly happened?

Paths to API keysThe system automatically registers several real paths to the key - “helper”.

PathHelper will look for a “jbcart.php” file within these paths backward.

It will return the full path to this file when it finds it.

A list of names for the helper

Thus, you can accomplish different tasks: shorten long paths, check if a file exists, reload existing paths and replace some system files with lazy initialization.

You can see a list of all existing names for the helper on this screenshot.

Working with the static

JBAssets helper is needed to quickly connect different static, scripts and their dependences.

For example, during fancybox activation, jQuery will be loaded automatically.

// enabling various libraries
$this->app->jbassets->jQuery();
$this->app->jbassets->jQueryUI();
$this->app->jbassets->fancybox();
$this->app->jbassets->tablesorter();
$this->app->jbassets->chosen();
$this->app->jbassets->datepicker();
// etc. full list of methods is in the helper

// adding global PHP variable to the HTML document
$this->app->jbassets->addVar($varName, $value);

// adding static file. virtual path is used (from the path helper)
$this->app->jbassets->js('<path to the JS file>');
$this->app->jbassets->js('<path to the CSS file>');

Helpers for creating SEF-links.

Example:

// how to get link to an item by its ID
$item = $this->app->table->item->get(42);
$url = $this->app->route->item($item);

// how to get a link by category ID
$category = $this->app->table->category->get(42);
$url = $this->app->route->category($category);

// main page of an application
$url = $this->app->route->frontpage($application_id);

Special JBZoo pages, for example, cart page:

$basketUrl = $this->app->jbrouter->basket($menuItemid, $appId);

Working with the system cache

ZOO based cache:

// creating caching object and passing path for storing
$cache = $this->app->cache->create($this->app->path->path('cache:') . '/file_name', true, 86400);

// checking rights (not required)
if (!$cache->check()) {
    $this->app->system->application->enqueueMessage('Cache not writable!', 'notice');
}

// checking cache actuality
$cacheСheck = ($cache) ? $cache->check() : false;
if ($cacheСheck) {
    $data = $cache->get('Key of the variable');
}

if (empty($data)) {
    // complex calculations
    $data = 2 + 3;
    
    // storing in the cache
    $cache->set('Key of the variable', $data);
    $cache->save();
}

JBZoo based cache (in essence, simplified wrapper around ZOO cache):

$key = 'A variable responsible for a uniqueness of cache value';  // cache key
$group  = 'cache_group_folder';

// checking actuality
if (!($result = $this->app->jbcache->get($key, $group))) {

    // complex calculations
    $result = 2 + 2 * 2;

    // storing the result
    $this->app->jbcache->set($key, $result, $group);
}

Working with REQUEST data

$request = $this->app->jbrequest;

// get the data from external variable (stripped from HTML and spaces on the sides);
// second argument eliminates unnecessary checks in the code
$var = $request->get('varName', 'defaultData');

// find out if the current request is made using AJAX or no
if ($request->isAjax()) { … }

// Is it a POST request?
if ($request->isPost()) { … }

// Is option variable euals com_zoo? (releases us from simplest checks in the code)
if ($request->is('option', 'com_zoo')) { … }

There are dozens of helpers in a framework. If we’ll talk about each one, small book will be in the result.

API, Helpers

Still gotta questions, who can help me?

Visit our special JBZoo tech support forum which is specifically meant for JBZoo so the priority of the response and its promptness are much better there than in any other place. With inactive account with a “Plus” sign in a tariff plan you can ask for support in one of these sections or use any of our contacts.