Important note

This is tutorial is outdated, and needs radical updating (which we hope to do soon). Version 1.0.0 of ByAttribute ships with a Magento widget, making it much easier to add a ByAttribute listing to your Magento pages. Thanks to this, it is no longer mandatory to modify the XML layout: You can use ByAttribute if you are not a programmer. The information below is still relevant if you choose to modify the XML layout settings of ByAttribute. Flexibility is key.

Configuration settings

Within the Magento System Configuration there are some small settings that set the default behaviour of ByAttribute. Navigate in the Magento backend to System > Configuration > [scope] > Catalog > ByAttribute. The following options are available:

• Sidebar - Skip empty
• Sidebar - Show product count
• Overview - Title format

Note that all of these options can be overridden using XML layout coding.

Default settings

The XML layout of the module has a default configuration, but whether this configuration is actually showing something depends on your Magento setup. We recommend overriding the XML layout with the settings you like.

<default>
    <reference name="right">
        <block type="byattribute/options" name="right.byattribute.manufacturer">
            <action method="setAttributeValue"><string>manufacturer</string></action>
        </block>
    </reference>
</default>

By default, the ByAttribute extension is listing all values for the product attribute manufacturer within a block assigned to the right sidebar of your Magento theme. Each value is linking to an overview page (part of the ByAttribute extension) showing a listing of product with the product attribute set to the specific attribute value - for instance all products that have as manufacturer the value Canon. All these values can be changed by modifying the XML layout.

For instance, the attribute manufacturer can be changed to color. Also, if you add a specific category ID in your XML layout, the links will not point to the default ByAttribute overview pages, but to the Layered Navigation page of that category.

Links to ByAttribute overview pages

When you do not configure a category for the Yireo ByAttribute block (using XML layout coding), all attribute links in the sidebar block will point to the Advanced Search page.

http://MAGENTO/attribute/index/index/manufacturer/5/

Links to category pages (using Layered Navigation)

When you do configure a category, all attribute values of the ByAttribute sidebar block are linked to the product overview page of that category. For instance, if the category is furniture and the attribute manufacturer is 5, the link will look like this:

http://MAGENTO/furniture?manufacturer=5

For the products to be filtered by manufacturer, the category needs to be set as Anchored. This also means that the concept of Layered Navigation is applied to this category and all its subcategories.

The category could be either a Top Level category or one of its subcategories. It can not be a Root Category, as Magento does not allow product overviews of a Root Category.To change the category, you need to make changes to the XML layout of the ByAttribute extension - as explained below.

Introducing Magento theming

Magento theming involves a complex mix of PHP, HTML and XML. While styling is done through a skin (CSS, images), the HTML document is built up by using so called blocks. These blocks are first defined in XML, initialized through a PHP class and then generated using HTML and PHP.

Using the right technical terms here, the block is defined by a XML layout, then it is initialized through a Block class (PHP code) and generated by a PHTML template. The Yireo ByAttribute is flexible in its setup, but requires you to modify the XML layout to your needs.

Introducing the XML layout

The default XML layout of the Yireo ByAttribute module is located in the file app/design/frontend/default/default/layout/byattribute.xml. It contains the coding like the following:

<default>
    <reference name="left">
        <block type="byattribute/options" name="left.byattribute.options">
            <action method="setAttributeValue"><string>manufacturer</string></action>
        </block>
    </reference>
</default>

This structure adds the Yireo ByAttribute block to the existing block left. If on a certain page the block left is missing, the Yireo ByAttribute block is also missing. The XML also defines which attribute should be displayed: manufacturer.

Modifying the XML layout

You should never make changes to original Magento files (either core files or files from third party suppliers like Yireo). Instead, create your own theme following the guidelines of the Magento Designers Guide. You can copy the XML layout byattribute.xml to your own layout directory and make your changes there.

Changing the attribute name

To change the attribute name, modify the following line in the XML layout:

<action method="setAttributeValue"><string>manufacturer</string></action>

Replace with manufacturer with the attribute of your choice. There are certain rules for this attribute. The attribute must have multiple Options configured through the Magento Admin Panel: These are the values that are displayed inside the frontend block.

Furthermore, if you want the attribute links to point to the Advanced Search page, the attribute should have the value Use in advanced search set to Yes. If you want the attribute links to point to a category page, the attribute should have the value Use in Layered Navigation set to Filterable.

Configure a category

To point the attribute links to a category page, you need to configure the following line in the XML layout:

<action method="setCategoryId"><int>7</int></action>

The number refers to the ID of the category as displayed in the Magento Admin Panel. The category can not be a Root Category. We consider the configuration to be most useful if the category is a Top Level Category, not a subcategory - this way the category shows many different products.

The category needs to be an anchor - the category option Is Anchor should be set to Yes, which means that the Layered Navigation is applied to this category and all its children.

Configuring products

If you configure the module to use a specific category, the Yireo ByAttribute module will check whether the configured product attribute is in fact in use with any of the products.

For instance, let's assume you have configured the Yireo ByAttribute module to use the product attribute color and the category Furniture. When loading the block, the module will fetch all products contained in this Furniture category. But if none of the products, actually makes use of the attribute color, the block will be empty.

Modifying the product overview

When ByAttribute is being used to generate a product overview, the default title of that page will be formatted like Products of $ATTRIBUTE $VALUE. If the choosen attribute is manufacturer and the selected attribute value is Samsung, then the resulting page title will be:

Products of manufacturer Samsung

You can change this titlle again through XML code. Find the block of type byattribute/overview and add the following action to it to modify the title format:

<action method="setTitleFormat"><format>All $VALUE products</format></action>

Note that this format was changed from ByAttribute version 0.9.13. You can also set this format globally within the Magento System Configuration (under Catalog > ByAttribute).

Modifying the PHTML template

Besides the XML layout, the Yireo ByAttribute module also contains a PHTML template - a mix of PHP and HTML. You can change this PHTML to fit your own needs. The module by default adds a template file app/design/frontend/default/default/template/byattribute/options.phtml.

Do not make direct modifications to the original file. Instead, copy the file to your own theme or alternatively create a new PHTML template.

Multiple blocks

The XML layout code can be copied multiple times, with each time using different settings. This way you can list different blocks of attributes on different pages and different positions on the page.

For every block, you can also use a different template argument. By default, the template argument is missing (meaning that the default byattribute/options.phtml is being used):

<block type="byattribute/options" name="myidentifier">
...
</block>

You can however add a template argument, so the block uses a different PHTML template.

<block type="byattribute/options" name="myidentifier" 
       template="byattribute/options_custom.phtml">
...
</block>

We recommend to make use of the byattribute folder, and make sure the templates filename begins with options_. This avoids possible conflicts with future changes in either the Yireo ByAttribute module or other third party modules.

Note that we already have included an extra template options_select.phtml which implements the attribute values as a dropdown field.

Using ByAttribute on CMS pages

It is possible to add a ByAttribute block to CMS pages (or Static Blocks), but you are required to use the XML tags as explained above. Using the CMS tags ({{example}}) will not work. Also, make sure you use the name argument within the block tag (<block name="byattribute.mycmsblock">) without it the block will not be added by Magento.