How to Use eZ Publish Extensions: Google Analytics

eZ Publish extensions are packages containing functionality that extend or alter the features of an eZ Publish site. eZ Publish is designed with a “plug-in” architecture, so that the system can be customized without affecting the core installation. After installation, extensions are either automatically detected by convention or specified via settings.

Extensions can provide custom functionality using the existing standard system of templates, designs, template operators, classes, datatypes, modules, fetches, extended attribute filters, views, workflow events, shop account handlers, shipping handlers, tax handlers, output handlers, login handlers, cli scripts, cronjobs, notifications, search engines, libraries, SQL files, packages, settings, patches and more.

This article does not describe how to create an extension. Instead, it explains how to install and use extensions created by other eZ Community members – specifically Brookins Consulting’s BC Website Statistics extension. If you want to learn how to create extensions, you can analyze the source code of existing eZ Publish extensions and refer to the documentation and other eZ Publish educational resources (such as the eZ Publish Basics book). Alternatively, there is a network of global eZ Partners who are available to build extensions according to your specifications.

Where to find extensions

There are a number of sources for obtaining extensions to eZ Publish. These include supported partner certified solutions and community-supported projects, contributions, SVN respository and public SVN repository.

Installing an extension

This section describes how to install the BC Website Statistics extension on our eZ Tennis Club site. Most eZ Publish extensions are installed in a similar manner.

1. Download the extension's latest binary package file in the preferred format ( .tar.gz, tar.bz2 or .zip ).
2. Unpack the package into the extension/ directory in the eZ Publish installation. This should create a directory with the extension name bcwebsitestatistics. If not, rename the directory.
3. On Unix-like operating systems, set file ownership of the extension directory (bcwebsitestatistics) recursively to the owner and group of the webserver. For example, if the webserver owner and group are both named “apache”, type this command from the extension directory: chown -R apache:apache bcwebsitestatistics. Otherwise, set the access permissions to 750 (chmod 750 bcwebsitestatistics).

Activating an extension

Extensions can be activated globally (which will affect every site – including translated sites – running from the eZ Publish installation) or can be activated for one or more specific siteaccesses.

There are two ways to activate extensions:

• Use the Administration Interface.
• Manually edit the site configuration files for either specific siteaccesses or globally.

When you activate an extension through the Administration Interface, it will be activated for all siteaccesses.

When you manually enable an extension, you have greater control over the siteaccesses to which the extension applies. This gives you more granular control over the impact of the extension. As stated in the first article in this series, site settings follow an override order, where basic settings are overriden by siteaccess settings, which are overridden by global settings. Therefore, to enable the extension in only the “eng” siteaccess of the eZ Tennis Club site, we would edit settings/eng/site.ini.append.php and add an entry to the ActiveAccessExtensions[] array under the [ExtensionSettings] block:

[ExtensionSettings]
ActiveAccessExtensions[]
ActiveAccessExtensions[]=bcwebsitestatistics 
ActiveAccessExtensions[]=ezwebin

For the sake of this tutorial, we will activate the extension for all siteaccesses via the eZ Publish Administration Interface. To do so, click the Setup link on the top navigation bar. On the left menu, click the Extensions link. In the Available extensions window, mark the checkbox under the Activate column that corresponds to the bcwebsitestatistics extension. (Note that the extension name displayed in the Administration Interface corresponds to the directory name where the extension was installed.) Click the Apply changes button.

Configuring extension settings

1. Copy the configuration file extension/bcwebsitestatistics/settings/bcwebsitestatistics.ini.append.php into the eZ Publish settings/override/ directory.
2. Edit the bcwebsitestatistics.ini.append.php configuration file. Replace the value of the Urchin setting with the value provided by Google Analytics for your own website profile, as described earlier in this tutorial. As an example:

[BCWebsiteStatisticsSettings]
# Required Settings Change
Urchin=UA-2639251-2

# Default Settings
OrderSubmit=enabled 
PageSubmit=enabled 

# Optional Settings
# HostName=example.com 
HostName=disabled 
ShopName=eZPublishSite