Layout System

7.2.1 Basic Usage

When using the Harmoni Module and Action system, the output of an Action can either be printed directly to the output buffer via print statements; or as we will do now, the Action can return a layout.

:: Hello World! ::

Example


<?php    

// helloworld.act.php
// This action will just return a "Hello World!" text block
// that can later be themed.

// Create the Layout for our content to go in.
// TEXT_BLOCK_WIDGET is the class of ThemeWidget that 
// the theme should apply to this layout.
$myLayout =& new SingleContentLayout(TEXT_BLOCK_WIDGET);

// Create the Content to put in the Layout.
$myText =& new Content("Hello World!");

// Add the Content to the Layout.
$myLayout->addComponent($myText);

// Return the layout.
return $myLayout;

?>

As can be seen above, the Layout system is made up of Layouts, which can contain Layouts or other VisualComponents, and those other VisualComponents. The above example only uses a Content component, but later on we will also show the use of MenuItems and MenuHeadings.

Harmoni Layouts and Themes are closely related. The theme will expect the Layout to be able to specify the class and index of the ThemeWidget the layout should be themed with. In the HelloWorld example above, we told $myLayout that we wanted it to be themed by a TEXT_BLOCK_WIDGET with the default index of "1".

NOTE

The built-in Harmoni Layouts; SingleContentLayout, RowLayout, ColumnLayout, HorizontalMenuLayout, and VerticalMenuLayout all take the same constructor parameters of $themeWidgetType and $themeWidgetIndex. Other Layouts may take other parameters.

Layouts and other VisualComponents are added to a Layout via the addComponent() method. When adding a component horizontal and vertical alignments can be specified via optional parameters:

Example


$myLayout->addComponent($myText, TOP, LEFT);

7.2.2 Layouts and other VisualComponents

The Layout System was designed to be as flexible as possible to allow developers great control over how items are arranged on the page. To maintain flexibility, the three primary layouts are:

SingleContentLayout
RowLayout
ColumnLayout

By nesting rows, columns, and single blocks, virtually any graphical structure can be created. If those are not enough, you can implement your own layout classes which provide another arrangement paradigm (such as absolute positioning for instance).

In the next example, we will expand on our HelloWorld example to make an Action that will output three rows, the upper one of which is a heading. The center row will be two columns, the first containing "Hello World!" and the second containing an image of the world. The bottom Row will be some footer text:

This is what I say!

Hello World! <img src='world.gif'>

Copyright 2004, me.

NOTE

The table printed above is a general representation of the layout, not what the layout would necessarily produce.

Example


<?php    



// helloworld2.act.php

// This action will just return a layout with several

// rows and columns that can later be themed.





// Create the main Layout for everything to go in.

$myLayout =& new RowLayout(TEXT_BLOCK_WIDGET, 1);



    // Create the Layout to put the header in.

    $headerLayout =& new SingleContentLayout(HEADING_WIDGET, 1);

    

    // Add the header Layout to the main Layout.

    $myLayout->addComponent($headerLayout);

    

        // Add the text to the header.

        $headerLayout->addComponent(new Content("This is what I say!"));

    

    

    // Create our columns for the second row.

    // By default RowLayouts and Column Layouts use BLANK_WIDGETs

    // which have no theming applied to them.

    $centerColumns =& new ColumnLayout;

    

    // Add the columns Layout to the main Layout.

    $myLayout->addComponent($centerColumns);

    

        // Create the Layout to put the "Hello World" in.

        $helloWorldLayout =& new SingleContentLayout(TEXT_BLOCK_WIDGET, 2);    

        

        // Add the helloWorld Layout to the columns Layout.

        $centerColumns->addComponent($helloWorldLayout);

        

            // Add the text

            $helloWorldLayout->addComponent(new Content("Hello World!"));

        

        // Create the Layout to put the image in.

        $imageLayout =& new SingleContentLayout(BLANK_WIDGET);    

        

        // Add the helloWorld Layout to the columns Layout.

        $centerColumns->addComponent($imageLayout);

        

            // Add the text

            $imageLayout->addComponent(new Content("<img src='world.gif'>"));

    

    

    // Create the Layout to put the footer in.

    $footerLayout =& new SingleContentLayout(FOOTER_WIDGET, 1);

    

    // Add the footer Layout to the main Layout.

    $myLayout->addComponent($footerLayout);

    

        // Add the text to the footer.

        $footerLayout->addComponent(new Content("Copyright &copy; 2004, me."));

    



// Return the layout.

return $myLayout;



?>

In addition to the Column and Row Layouts, the above example also showed the application of varying ThemeWidgets and indices to Layouts. More on this is explained in the Themes section.

Layouts don't necessarily have to allow arbitrary children. The HorizontalMenuLayout and the VerticalMenuLayout require that a MenuItem VisualComponents be added to them. An example of this is in the Advanced Usage section.

The Layouts and other VisualComponents that are included in Harmoni are:

Layouts:

SingleContentLayout
RowLayout
ColumnLayout
HorizontalMenuLayout
VerticalMenuLayout

Other VisualComponents:

Content
StandardMenuItem
HeaderMenuItem
LinkMenuItem

The included Layouts and other VisualComponents mentioned above should allow for the vast majority of layout needs. If other Layouts or VisualComponents are needed, just extend the LayoutInterface or the VisualComponentInterface.

7.2.3 Advanced Usage

The following example will build on the one in the previous section and add a Horizontal Menu to the new top row. As well, alignment properties have been included when adding some components:

Main Menu: Home Google

This is what I say!

Hello World! <img src='world.gif'>

Copyright 2004, me.

NOTE

The table printed above is a general representation of the layout, not what the layout would necessarily produce.

Example


<?php    



// helloworld2.act.php

// This action will just return a layout with several

// rows and columns that can later be themed.





// Create the main Layout for everything to go in.

$myLayout =& new RowLayout(TEXT_BLOCK_WIDGET, 1);



    // Create the Menu Layout.

    $menuLayout =& new HorizontalMenuLayout(MENU_WIDGET, 1);

    

    // Add the menu Layout to the main Layout.

    $myLayout->addComponent($menuLayout, MIDDLE, RIGHT);

    

        // Menu Items

        $menuLayout->addComponent(new HeaderMenuItem("Main Menu:"), MIDDLE, CENTER);

            // "TRUE" flag indicates that this item is selected.

        $menuLayout->addComponent(new LinkMenuItem("Home", "#", TRUE), MIDDLE, CENTER);

        $menuLayout->addComponent(new LinkMenuItem("Google", "http://www.google.com"), MIDDLE, CENTER);

        



    // Create the Layout to put the header in.

    $headerLayout =& new SingleContentLayout(HEADING_WIDGET, 1);

    

    // Add the header Layout to the main Layout.

    $myLayout->addComponent($headerLayout);

    

        // Add the text to the header.

        $headerLayout->addComponent(new Content("This is what I say!"), TOP, CENTER);

    

    

    // Create our columns for the second row.

    // By default RowLayouts and Column Layouts use BLANK_WIDGETs

    // which have no theming applied to them.

    $centerColumns =& new ColumnLayout;

    

    // Add the columns Layout to the main Layout.

    $myLayout->addComponent($centerColumns);

    

        // Create the Layout to put the "Hello World" in.

        $helloWorldLayout =& new SingleContentLayout(TEXT_BLOCK_WIDGET, 2);    

        

        // Add the helloWorld Layout to the columns Layout.

        $centerColumns->addComponent($helloWorldLayout, TOP);

        

            // Add the text

            $helloWorldLayout->addComponent(new Content("Hello World!"));

        

        // Create the Layout to put the image in.

        $imageLayout =& new SingleContentLayout(BLANK_WIDGET);    

        

        // Add the helloWorld Layout to the columns Layout.

        $centerColumns->addComponent($imageLayout, TOP);

        

            // Add the text

            $imageLayout->addComponent(new Content("<img src='world.gif'>"));

    

    

    // Create the Layout to put the footer in.

    $footerLayout =& new SingleContentLayout(FOOTER_WIDGET, 1);

    

    // Add the footer Layout to the main Layout.

    $myLayout->addComponent($footerLayout);

    

        // Add the text to the footer.

        $footerLayout->addComponent(new Content("Copyright 2004, me."), MIDDLE, CENTER);

    



// Return the layout.

return $myLayout;



?>