[ic] Tips and tricks -- override of UI menus

[Mike Heins]

Area:     UI
Category: General
Item:     Customization

The Interchange UI probably is useful for most people in its standard
form. Of course, that is not always true. The benefits of open source
allow you to edit the pages and files in lib/UI (location of all UI-related
stuff) and get the presentation and functionality you need.

This is far from perfect.  One of the problems with editing the
distribution UI pages in lib/UI to get menu effects is that when you
update Interchange, you must manage your changes.

Another problem is that the changes you make to the UI for one customer
may not pertain to all of them, and you may have to run multiple copies.

What a mess. Fortunately, you don't need to do it.

You can override any of the menu presentations on a catalog-by-catalog
basis, without editing any of the distribution pages!

First a bit about the UI setup. It uses a few features of Interchange
that are not widely discussed.

1. TemplateDir. This Interchange directive -- active both in
interchange.cfg and catalog.cfg -- allows you to provide a directory with
pages that will pertain when a page is not found. In other words, when
a page in the directory "admin" is asked for and not found, Interchange
then looks in any TemplateDir settings. If you look in lib/UI/ui.cfg,
included when you specify the UI in interchange.cfg, you will see:

    # instruct Interchange to use this directory as alternative
    # for searching Interchange pages
    TemplateDir lib/UI/pages

So if you wanted, you could override the whole page set by copying it
to your own directory. This is probably still not what you want; it is
easiest just to override certain pages by making a pages/admin directory
and copying the pages in question there.

Try this out yourself by doing:

 mkdir CATALOG_DIR/pages/admin
 cp IC_DIR/lib/UI/pages/admin/index.html CATALOG_DIR/pages/admin

   where:
   CAT_DIR = path to your catalog directory (i.e. /home/user/catalogs/construct)
   IC_DIR  = path to interchange root (i.e. /usr/local/interchange)

Then edit the file CAT_DIR/pages/admin/index.html to put in something of
your own. Reload the Interchange menu, and you should see your changes.
Follow any active links, and you will see that they work, even though
you have no corresponding page in your pages/admin/ directory.

In fact, you can even provide each logged-in admin user with their
own custom menu page by providing a pages/admin/user/USERNAME directory
with an index.html.

2. @_VARIABLE_@. This notation specifies a fall-back variable, i.e. a 
variable which should check the catalog Variable space first, then
if the variable is not defined there, use the global interchange.cfg
definition.

For example, every admin page has a common footer specified in the
variable UI_STD_FOOTER. Suppose one of your customers doesn't want all
the information and links we provide at the bottom. Take all that out
by defining in catalog.cfg:

Variable UI_STD_FOOTER <<EOV
[if !scratch ui_no_title]
                </td>
        </tr>
</table>
[/if]
</body>
</html>

EOV

"Apply Changes" and you should now not see the normal footer HTML
*for that catalog only*.

You can do the same thing for UI_STD_HEAD and each of the menu source
variables, giving a completely different look and feel to the catalog UI
for each customer (or just your installation).  Of course we would like
you to give us a small bit of credit in this process by providing a link
as we do in our menus, but of course with the GPL you aren't required
even to do that. 8-)

Examine the source to the UI in lib/UI and you will see plenty of @_VAR_@
and __VAR__ settings you can override.

3. The Preferences variables. There are a number of settings in the Knar
area that pertain to UI display. For example, check out the settings in
the Preferences area "Item Display". You can determine which fields will
be edited in the item editor with UI_ITEM_FIELDS; where the logical grouping
lines will be in UI_ITEM_BREAK; the number of entries on the item select page
with UI_SZ_LIST_ITEM; and the number of entries on each merchandising select
page with UI_SZ_LIST_MERCH.

-----------------------

This technique is used throughout the UI, but it is not yet perfect.
Please report any problems with, or make enhancement suggestions about,
custom templating to:

	http://developer.akopia.com/bugs/

Best,
Mike
-- 
Akopia, Inc., 131 Willow Lane, Floor 2, Oxford, OH  45056
phone +1.513.523.7621 fax 7501 <heins@akopia.com>

Friends don't let friends use Outlook. -- Bob Blaylock