CHANGES:
NEWS
DOWNLOAD:
SmartyMenu-1.1.tar.gz
DEMO:
Menu Demo
NAME:
SmartyMenu: a class/plugin for generating dropdown menus
within the Smarty template environment.
AUTHOR:
Monte Ohrt (monte [AT] ohrt [DOT] com)
VERSION:
1.1
DATE:
October 18th, 2005
WEBSITE:
http://www.phpinsider.com/php/code/SmartyMenu/
DOWNLOAD:
http://www.phpinsider.com/php/code/SmartyMenu/SmartyMenu-current.tar.gz
ANONYMOUS CVS: (leave password empty)
cvs -d :pserver:anonymous@cvs.phpinsider.com:/export/CVS login
cvs -d :pserver:anonymous@cvs.phpinsider.com:/export/CVS checkout SmartyMenu
SYNOPSIS:
index.php
---------
session_start();
require('Smarty.class.php');
require('SmartyMenu.class.php');
$smarty =& new Smarty;
// attempt to load the menu from the session
if(($menu = (SmartyMenu::loadMenu('mymenu'))) === false) {
// initialize your menu
SmartyMenu::initMenu($menu);
// first menu item
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Yahoo');
SmartyMenu::setItemLink($item, 'http://www.yahoo.com/');
SmartyMenu::addMenuItem($menu, $item);
// second menu item
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Google');
SmartyMenu::setItemLink($item, 'http://www.google.com/');
SmartyMenu::addMenuItem($menu, $item);
// third menu item
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Netscape');
SmartyMenu::setItemLink($item, 'http://www.netscape.com/');
SmartyMenu::addMenuItem($menu, $item);
// save the menu into the session
SmartyMenu::saveMenu('mymenu', $menu);
}
$smarty->assign('menu', $menu);
$smarty->display('index.tpl');
index.tpl
---------
<html>
<head>
{menu_init css="/css/menu.css"}
</head>
<body>
Menu Test
<p>
{menu data=$menu}
</p>
</body>
</html>
DESCRIPTION:
What is SmartyMenu?
SmartyMenu is a dropdown menu generator class. Its design goals are to
leverage the Smarty templating environment and make dropdown menu
generation as easy and flexible as possible.
BACKGROUND:
Dropdown menus are one of the most saught after and difficult to perform
tasks when it comes to web application programming. It is a tedious, time
consuming task. SmartyMenu simplifies this effort by abstracting the menu
generation process. You basically provide the menu items and a stylesheet,
and SmartyMenu does the rest!
You assign an array of menu items to your template, then SmartyMenu
generates an unordered list from the menu array, then applies a stylesheet
that generates the menus.
Be aware that although SmartyMenu aids in the dropdown generation, it is
still not for the faint of heart. SmartyMenu creates dropdowns based on
pure CSS code with a small javascript footprint for browsers that don't
handle CSS correctly. That doesn't mean it will work perfectly on every
browser, it may take some crafty stylesheet and javascript tweaks to get
things looking right, but for the most part SmartyMenu does a good job with
CSS compliant browsers. SmartyMenu has been known to work with latest
incarnations of Mozilla, Opera and Safari, and works fairly reliably on IE
with some javascript help. (Which versions of which will be left as an
exercise to the reader.)
SmartyMenus are based on the SuckerFish dropdown implementation by Patrick
Griffiths and Dan Webb. Please visit their website at
http://www.htmldog.com/articles/suckerfish/dropdowns/ for more information.
If you want to use new styles outside of the ones that ship with SmartyMenu
or you want to take a stab at getting it to work on your Amiga :) then plan
on getting your hands dirty in CSS code. DO NOT expect the author (me) to
fix your problems, I have limited CSS experience and don't want to support
every little nuance that arrives. Please post your problems and findings to
the Smarty forum so everyone can help and benefit.
FEATURES:
All aspects of menu generation are controlled through stylesheets. Include
the appropriate .css file within {menu_init} to get the menu you want, or
alter one of the existing .css files to your own taste.
REQUIREMENTS:
SmartyMenu requires the Smarty template environment. If you want persistent
menus across invocations via saveMenu() and loadMenu(), you must call
session_start() in your PHP script prior to using SmartyMenu.
INSTALLATION:
It is assumed that you are familiar with the Smarty templating
installation and setup, so I will not explain Smarty template
directories and such. Please refer to the Smarty documentation for
that information.
To install SmartyMenu:
* Copy the 'SmartyMenu.class.php' file to a place within your
php_include path (or use absolute pathnames when including.)
* Copy all of the plugins to your Smarty plugin directory. (located
in the plugins/ directory of the distribution.)
* Copy the stylesheet files to a place under your web server DOCUMENT_ROOT,
such as under DOCUMENT_ROOT/css/
EXAMPLE:
Please see the SYNOPSIS above for a full working example.
CREATING THE MENU ARRAY
-----------------------
There are a couple of ways to build the menu array that SmartyMenu will use
to build a menu out of. One method is to build the array manually.
For example, here is a single-level menu array with two items:
$menu = array(
array(
'text' => 'Yahoo',
'link' => 'http://www.yahoo.com',
'class' => 'topnav'
),
array(
'text' => 'Google',
'link' => 'http://www.google.com',
'class' => 'topnav'
),
);
Here is an example with a submenu:
$menu = array(
array(
'text' => 'Yahoo',
'link' => 'http://www.yahoo.com',
'class' => 'topnav'
),
array(
'text' => 'Google',
'link' => 'http://www.google.com',
'class' => 'topnav'
'submenu' => array(
array(
'text' => 'Google Groups',
'link' => 'http://groups.google.com/',
'class' => 'subnav'
),
array(
'text' => 'Google News',
'link' => 'http://news.google.com/',
'class' => 'subnav'
)
)
),
)
Creating the menu array manually can be time consuming and error prone. An
alternate way to build the menu array is programatically with the tools
available from SmartyMenu. Here is how you would build the above menu array
with SmartyMenu:
// we create our bottom-level submenus and work our way up.
// first we create the submenu
SmartyMenu::initMenu($google_menu);
// create the first submenu item
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Google Groups');
SmartyMenu::setItemLink($item, 'http://groups.google.com/');
SmartyMenu::setItemClass($item, 'subnav');
// attach the item to the menu
SmartyMenu::addMenuItem($google_menu, $item);
// repeat process for each item
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Google News');
SmartyMenu::setItemLink($item, 'http://news.google.com/');
SmartyMenu::setItemClass($item, 'subnav');
SmartyMenu::addMenuItem($google_menu, $item);
Now we create the top-level menu
SmartyMenu::initMenu($menu);
// create and add items
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Yahoo');
SmartyMenu::setItemLink($item, 'http://www.yahoo.com/');
SmartyMenu::setItemClass($item, 'topnav');
SmartyMenu::addMenuItem($menu, $item);
SmartyMenu::initItem($item);
SmartyMenu::setItemText($item, 'Google');
SmartyMenu::setItemLink($item, 'http://www.google.com/');
SmartyMenu::setItemClass($item, 'topnav');
// this one has a submenu
SmartyMenu::setItemSubmenu($item, $google_menu);
SmartyMenu::addMenuItem($menu, $item);
// our $menu array is now ready!
Once you have your menu array ready, you assign it to the template.
$smarty->assign('menu', $menu);
TEMPLATE FUNCTIONS
------------------
menu_init
---------
examples:
{menu_init}
{menu_init css="/css/menu.css"}
{menu_init} should be placed inside the <head></head> tags of your web
page. This supplies the page with the javascript and stylesheet file link.
If you do not supply a stylesheet, it is assumed that these styles are
supplied elsewhere on the page, either from another stylesheet link or
inline between <style></style> tags.
menu
----
examples:
{menu data=$menu}
The {menu} tag produces the unordered list of menu elements. Place this
where you want your menu on the web page. The data parameter is required, it
is the array of menu items that was assigned to the template.
PUBLIC METHODS:
function initMenu(&$menu,)
--------------------------
examples:
SmartyMenu::initMenu($menu);
initMenu() initializes a variable as a menu. Do this first before adding
items to your menu.
function initItem(&$item)
-------------------------
examples:
SmartyMenu::initItem($menu);
initItem() initializes a variable as a menu item. Do this first before adding
informtation to your item.
function setItemText($item,$text)
---------------------------------
examples:
SmartyMenu::setItemText($item,'Yahoo');
setItemText() sets the text value of your menu item. This is the text that
shows up in the menu dropdown.
function setItemLink($item,$link)
---------------------------------
examples:
SmartyMenu::setItemLink($item,'http://www.yahoo.com');
setItemLink() sets the link (URL) value of your menu item. This is the link
that the user it taken when clicking on the text.
function setItemClass($item,$class)
-----------------------------------
examples:
SmartyMenu::setItemClass($item,'topnav');
setItemClass() applies a CSS class to the item for further presentation
control from the CSS file.
function setItemSubmenu($item,$submenu)
---------------------------------------
examples:
SmartyMenu::setItemSubmenu($item,$submenu);
setItemSubmenu() adds a submenu to the item. When a user hovers the mouse
over the link (or however the css is setup to behave), the submenu will
appear. The $submenu variable must be a fully populated menu itself, so you
must initialize a menu and add menu items to it before it can be attached
as a submenu.
function saveMenu($name, $menu)
-------------------------------
examples:
SmartyMenu::saveMenu('mymenu', $menu);
saveMenu() saves the menu to the PHP session so it can be loaded on the next
script invocation. This saves the overhead of building the menu every time.
function loadMenu($name)
------------------------
examples:
if(($menu = SmartyMenu::loadMenu('mymenu')) === false) { /* build menu */ }
loadMenu() loads the menu from the PHP session. If no menu is available,
this function returns false.
function resetMenu($name)
------------------------
examples:
SmartyMenu::resetMenu('mymenu');
resetMenu() resets the menu currently saved in the PHP session.
CREDITS:
Thanks to the people who have submitted bug reports, suggestions, etc.
boots (from forums)
Anyone I missed, let me know!
COPYRIGHT:
Copyright(c) 2004-2005 New Digital Group, Inc. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
License for more details.
OTHER PROJECTS:
View Monte's other projects