Create your own bricks

Architecture of a brick

The architecture is simple and straightforward:

You can put your own bricks into /website/views/areas downloaded bricks from the marketplace are located in /website/var/areas

On the right side you can see how a brick can be structed. Mandatory files are area.xml and view.php . Optional files are action.php, edit.php and icon.png.

If you put an icon.png (16x16 pixel) into the brick's folder, this icon is added automatically to the toolbar, there's no need to specify the icon in the area.xml again. 

The area.xml contains some meta-infos concerning the brick, and the view.php is a simple Zend_View - script where you can use all pimcore editables.

How to create a brick

First of all create the area.xml containing the meta-data- For example: 

<?xml version="1.0"?>
<zend-config xmlns:zf="http://framework.zend.com/xml/zend-config-xml/1.0/">
    <id>iframe</id>
    <name>Iframe</name>
    <description>Embed contents from other URL (websites) via iframe</description>
    <!-- the icon is optional, see above for details (this node is normally used to refer to an icon in the pimcore core icon-set) -->
    <icon>/pimcore/static/img/icon/html.png</icon>
    <version>1.0</version>
    <myCustomConfig>MyValue</myCustomConfig>
</zend-config>

The bold definitions are mandatory, but you can add your custom configuration for the brick as well. In the following example you can see how to access the configuration and your custom properties in the configuration (since 1.4.2). 

Then you have to create your view script called view.php .

Since pimcore 1.4.2 there is an info-objects which contains informations about the current brick. You can access this info-object in your view with $this->brick  , the object contains the configuration from above (Zend_Config) an some other metadata (described later). 

For example:

<?php if ($this->editmode) { ?>
    <!-- with <?php echo $this->brick->getPath(); ?> you get the path to the area out of the info-object -->
    <link rel="stylesheet" type="text/css" href="<?php echo $this->brick->getPath(); ?>/editmode.css" />
    <div>
        <h2>IFrame</h2>
        <div>
            URL: <?php echo $this->input("iframe_url"); ?>
        </div>
        <br />
        <b>Advanced Configuration</b>
        <div>
            Width: <?php echo $this->numeric("iframe_width"); ?>px (default: 100%)
        </div>
        <div>
            Height: <?php echo $this->numeric("iframe_height"); ?>px (default: 400px)
        </div>
        <div>
            Transparent: <?php echo $this->checkbox("iframe_transparent"); ?> (default: false)
        </div>
    </div>
<?php } else { ?>
    <?php if (!$this->input("iframe_url")->isEmpty()) { ?>
        <?php
            // defaults
            $transparent = "false";
            $width = "100%";
            $height = "400";
            
            if(!$this->numeric("iframe_width")->isEmpty()) {
                $width = (string) $this->numeric("iframe_width");
            }
            if(!$this->numeric("iframe_height")->isEmpty()) {
                $height = (string) $this->numeric("iframe_height");
            }
            if($this->checkbox("iframe_transparent")->isChecked()) {
                $transparent = "true";
            }
        ?>
        <iframe src="<?php echo $this->input("iframe_url"); ?>" width="<?php echo $width; ?>" height="<?php echo $height; ?>" allowtransparency="<?php echo $transparent; ?>" frameborder="0" ></iframe>
    <?php } ?>
<?php } ?>

Once the code is in place, the areablock will appear as an extension in the Extension Manager (Extras->Extensions->Manage Extensions). From there, you have to enable the areablock.

That's all. In this example we need no action.php because everything is managed with editables.

The info-object ($this->brick) since 1.4.2

As mentioned already above, the info-object contains useful informations about the current brick.

The info-object ist available as a common view variable ($this->brick) in your view scripts (edit.php and view.php). 

In the follwing table you can see all available methods in your views (both in edit.php and view.php):

For an example usage see the above example (referencing the stylesheet).

Configuration in Editmode (edit.php)

To allow users to add data to the brick you have to the file edit.php which can include HTML and editables. When this file is present an icon will appear for the user which can be clicked to display and edit the editable fields.

Warning: Using edit.php will disable all editables in view.php (they appear like in the frontend, but cannot be edited). You cannot have editables in both files. (this behavior is present in Pimcore 1.4.1)

Contents of edit.php:

Class: <?php echo $this->input('class'); ?>

Accessing the data in view.php

<?php
    $class = '';
    if(!$this->input('class')->isEmpty()) {
        $class = $this->input('class')->getData();
    }
?>

Actions for Bricks (action.php)

Sometimes a brick is more than just a view-script an contains some functionality which shouldn't be directly in the view. In this case you can use the action.php. 

The action.php doesn't contain a "real" ZF - compatible controller/action it is just a little helper to get some logic and code out of the view, but the behavior is like in a common ZF-controller. 

To use this feature simply create a new file called action.php in your brick directory, and insert the following code (and replace "MyBrickName" with the name of your brick): 

<?php

class Document_Tag_Area_MyBrickName extends Document_Tag_Area_Abstract {
    
    public function action () {


        $myVar = $this->_getParam("myParam");

        ...
        ...


        $this->view->myVar = $myVar;
    }
}

The method action(); is called automatically before rendering the view.php or edit.php, so this is the place where your code should go. Of course you can create your own methods in the class, but ensure that your class extends Document_Tag_Area_Abstract ;-)

Inside this class/object there are some general methods available (inherited from Document_Tag_Area_Abstract) which offers you some handy features like the info-object (as described above), the config and much more... to see it in detail check out the contents of Document_Tag_Area_Abstract, the methods are really self-describing .

For a detailed example please have a look into our examples below.

Enabling bricks

Self created bricks are extensions just like those downloaded from the repository. Before they can be used, they need to be enabled in the extension manager (Extras > Manage Extensions) 

Sharing bricks with the extension-manager

If you want to share your brick using the pimcore extension manager please ensure that the brick contains all necessary javascripts and stylesheets. They should be references directly in the view (HTML), so you can use the brick "out-of-the-box" after you have installed it via the extension downloader. 

Examples

You can download some examples of bricks here.

They also contain a full featured example with an action and so on (googletagcloud).