Introduction

This help document was written for both the technical and non-technical reader. Some jargon and techy references are unavoidably necessary when trying to explain the purpose and use of this plugin. This help information will make more sense to you if you have a basic understanding or some familiarization with the following topics:

• Differences between WordPress pages and categories.
• Some exposure to cascading style sheets, specifically the purpose and use of css classes and styling unnumbered lists.
• Web site navigation techniques using unnumbered lists.
• The SideBar Modules Plugin for WordPress
• The SideBar Widgets Plugin for WordPress

Background

Web site navigation links on your WordPress blog are typically constructed using HTML unnumbered lists (UL and LI tags) and styled by your theme's cascading style sheet. The WordPress software provides theme designers with a few basic functions that collect, format and display specific types of lists in your blog. For example, a list containing your pages that is displayed as a horizontal menu or a list of categories vertically displayed in your sidebar.

Page lists and category lists are just two of the common list types that WordPress themes generally provide. WordPress supplied lists however, are confined to providing only one type of object in a sorted list - all categories or all pages. This is not an unreasonable expectation given the design of the software. If you want or need something different then you can always modify your theme. For some, that isn't a problem but other's may be more inclined to just look for a different theme.

About This Plugin

The WordPress Navigation List Plugin (NAVT) is a tool designed to provide you with complete control over the contents of your navigation links. The plugin gives you the ability to create navigation lists and arrange the items within the list in any order required.

• One or more lists can be created from any combination of pages, categories, links and dividers.
• Items within a list can be arranged in any arbitrary order.
• List item names can be changed without affecting the database.
• Navigation lists are theme 'independent' and reusable.
• Any number of external links and dividers can be added to a navigation group

For the programmer, the plugin provides a single interface function similar to the WordPress function wp_list_pages. The interface routine returns a HTML formatted Un-numbered list containing the category and/or page items configured within a user defined list called a Navigation Group.

For the non-programmer, the plugin comes with a convenient companion sidebar module and companion WordPress widget that can be incorporated into your widgetized theme (more information on this is provided below).

The plugin provides a colorized "drag 'n drop" interface minimizing the need to use your keyboard. Navigation lists can be created and edited using your mouse and a few keystrokes. Using this plugin with the companion sidebar module or sidebar widget provides you with the ability to reorder and change your navigation lists on your web site without changing one line of code in your theme. It also means that you can change themes and retain your site navigation.

Getting Started

Once you have created your WordPress (static) pages and article categories, they will initially appear in the default Navigation Group entitled unassigned on the left side of this page. The name of the navigation group appears as the title of a column. Contained within the column are individual boxes that represent the defined categories, pages or links.

WordPress pages can be distinguished from categories, links, external links and dividers by noting the type of icon that appears before the name of each item.

• Pages are indicated with the
  
  page icon,
• Categories are indicated with the
  
  tag icon,
• The home/blog link is indicated with the
  
  home icon,
• The Login/administration link is indicated with the
  
  admin icon,
• External links are indicated with the
  
  link icon,
• Dividers are indicated with the
  
  tab icon

NAVT will mark any items you have indicated as 'private' by placing a red hand over the icon. For example, private pages are indicated with a Icon. All navigation items can be made private by clicking the item's 'private' checkbox (more later). A private navigation item is not shown to web site visitors who are not logged into your web blog. This makes it possible to hide certain pages, categories or links from the general public. Private items will appear once the user has logged in.

The name of the item corresponds to the name used when the item was created. For example, page items are known by their page titles; category items are known by their category names. All pages and categories are displayed at the same level (flat). There is no hierarchal representation of sub-pages or sub-categories within a navigation group. (yet...)

Navigation Groups

A Navigation Group is a collection of list items composed of an arbitrary mix of pages, categories, external links, list dividers and the Home and Login/Admin links provided. Each navigation group must have a unique alphanumeric name at least two letters in length. The navigation group name is the identifier used by the PHP function call (or by the sidebar module) to retrieve the list. Constructing a meaningful name will be useful later.

To create a navigation group, enter the group name in the Group Name text field on the right side of the page and click the New button. A new (empty) group will appear on the page with the group name at the top of the column.

Adding Menu Items

Pages and/or categories can be then added to the new group by simply dragging the page, category or link item from the unassigned group and dropping it onto the new group in the area below the navigation group's option menu. The background color of the page or category box will change to the group color when the item hovers over the group and triggers the drop zone.

Pages, category and link items may be dragged and dropped between any number of navigation groups and may be moved within the group into any order desired. To move an item, place the mouse over the item's icon; the mouse pointer will change to the move cursor. Press the left mouse button to capture the item and hold the mouse button down while dragging it to its destination.

List Item Order

List item order is determined by the relative position of the page, category, link or divider box within a single navigation group. The item at the top of the group will be the first item displayed in the group and so on. To remove an item from a group, simply move the item back to the unassigned column.

Renaming Menu Groups

A Navigation Group may be renamed or removed by selecting the appropriate menu option at the top of the navigation group box. If a navigation group is removed, the items that were assigned to the group will be returned to the unassigned group. Divider items are not moved they are deleted. Accidental group deletion is prevented by requiring you to confirm the deletion.

Moving Navigation Groups

Entire navigation groups may also be reordered on the screen by dragging and dropping them into the desired location on the page. To move a navigation group, place the mouse over the name of the group; the mouse pointer will change to the move cursor. Hold the left mouse button down and drag the group to a location on the page. Navigation groups generally move easier from right to left. Navigation group order only affects the visual layout of this page and doesn't effect the layout your site.

Note: The unassigned navigation group can not be moved, renamed, deleted or displayed on a web page.

Menu Items

This plugin refers to the name of a menu item as the menu alias. An alias can be changed to something other than the page title or the category name. The menu alias is the title that appears in the menu tab or list in the final page output. This is very useful if the name of the page or category is longer than the space you have available in the sidebar or at the top of a page. Changing the alias does not change the original page title or category assignment in the database; it changes only the name shown in the menu.

Changing the Menu Alias

The alias name is changed by clicking the item name. A box will appear allowing you to enter a new alias. (Blue arrow in the diagram) Clicking the Cancel button will close the rename box. The rename box also contains the name as it appears in the database so you always know the actual page or category the menu alias refers to.

Menu Item Options

Menu items that contain category names have additional options that can be used to configure how they are presented on the page. (Red arrow area in the diagram) The option Show in category list is used to include or exclude the category when the list of article categories is displayed by your theme. These are the categories usually displayed by the WordPress PHP function call: wp_categories (WP 2.1+).

Turning off the feature excludes the category and any subcategories from the category list. This feature is off by default. The assumption is that if the category is featured as part of your top level horizontal menu, it may be confusing to have the category also appear in a sidebar category list. If you'd like the category to appear in both places then select the checkbox.

When selected, the option Append post count will append the total number of posts that appear within the named category to the category name. The plugin does not apply this feature to every category; you decide which of your categories to apply this feature to.

By default, categories that do not contain posts are not displayed in the navigation list. To change this behavior, select the Show if empty option in the categories option box

The post count can be styled independently from the category list item. More information about styling your navigation list is provided below.

Home and Login/Site Admin Links

Two additional items are provided by the plugin; these are the Home and Login links usually found on most sites. The Home link is the URL to your site and the Login link has the equivalent behavior of the WordPress site admin/registration link. The admin/login link is commonly found under the Meta heading in most sidebars.

The link name displayed in your navigation menu will appear as:

• Site Admin - User is logged in
• Login (or menu item alias name) - User is not logged in or is not allowed to register

As with all menu items, the menu alias can be changed for the Home menu item to Blog or some other preferred word.

External Links and Dividers

Links to external web sites, the use of the mailto: protocol or other url strings can be added to a navigation group by selecting the navigation group menu and clicking Add External Link. The information you enter as the menu alias will be displayed in the tab for the navigation item and will also appear in the navigation list as the item title. Any number of external links can be added to a navigation group. These items are not necessarily confined to just referencing urls outside of your web site. You could, for example, define a URL to one of your posts, archives or an on-site photo gallery.

One or more navigation list dividers can also be added to a navigation group by selecting Add Divider from the navigation group menu. A divider can be used to logically group related navigation items. This was designed primarily for vertical lists. Normally, a vertical list of links appears as a single contiguous block. Adding a divider somewhere in the list would allow you to break the list to visually group related items.

There are three types of dividers to choose from:

• An empty/blank list item that can be styled with top/bottom margins to create distance between groups.
• A plain-text divider which will add the plain text you enter into the list as a subheading using an H3 HTML tag.
• A horizontal rule divider which will insert the HTML horizontal rule tag into the list.

External links and dividers may be deleted from a navigation group by clicking the Delete this item that is located inside the menu item's option box.

Changes/Additions

Additions and modifications do not take effect until you click the apply button located on the right side of the page. All of your edits and changes occur on the client side of the conenction and only become known to the server side after clicking the Apply button. This plugin does not employ the use of any transparent client/server conversations (i.e. AJAX). Changes are also visually indicated by thick stripe (change bars) appearing to the left of the changed item. The visual indications are provided to remind you to save (apply) your changes.

Applying your changes will affect some of the page visuals. For example, empty navigation groups (groups that do not have items) will be removed, the color of the each remaining group may change as the page is rebuilt; all change bars will be removed upon completion of the update. All applied changes are immediately reflected on your web site.

Manage Pages and Manage Categories

The plugin will automatically adjust the contents of your navigation groups if you remove pages or categories using the Manage/Pages or Manage/Categories WordPress admin pages. In addition, newly created pages or categories can be immediately added to an existing navigation group via the additional form fields provided by the NAVT plugin on the Manage/Pages and Manage/Categories screens.

The form fields for NAVT group assignment are located in the WordPress Manage Pages sidebar. NAVT form fields for Categories appears at the bottom of the WordPress Manage Categories page. NAVT provides the same configuration elements for navigation items on the WordPress screens. This means that when you add or edit pages or categories you also have an opportunity to assign or reassign the navigation group or change the configuration of the navigation item.

Navigation List Formats

The default construction for navigation lists by the NAVT plugin is done by creating a standard HTML un-numbered list (UL) and wrapping each of the items with HTML LI tags. Alternatively, the NAVT plugin is capable of turning any of your navigation lists into a standard HTML dropdown (SELECT) list: Home A page A category another page A link To use this format select the Use Dropdown Style from the navigation group's menu. Selecting the option will place a √ symbol before the option indicating that it has been selected.

The option to show the number of posts contained within a category also works with dropdown menus. The category name will appear with the number of posts appended to the name as in: Daily Madness (300) Believe it or not (20) The Lastest Buzz

Multiple Dropdown Menus

Navigation list dividers can be used to split a single navigation group into a series of multiple dropdown lists separated by a header. This is accomplished by inserting one or more list dividers (preferrably a Plain Text divider) into the navigation group to act as partitions. For examplem, using the plain text divider will cause the divider's text to be displayed above a dropdown list that follows it. This is useful for creating what would appear to be indivual navigation lists from a single group:

Limited Undo

If you make modifications and then change your mind (and you haven't clicked the Apply button) then clicking the Cancel button will restore the menu groups and item associations from the last time any changes were saved.

Navigation List Styling

The visual style of the lists created by this plugin are determined by the class attributes you have defined in your theme's style sheet. The plugin provides ample class information for the unnumbered list that defines the navigation group. It also provides classes for each of the list items. The unnumbered list (UL) for the navigation group is always assigned the class "menu". In addition, the UL is assigned a class that corresponds to the navigation group name.

For example, if the navigation group were named topmenu, the UL class assigned to the UL would be: class="menu topmenu"

Each list item (LI) is assigned the class page_item. Each LI is given an additional class that corresponds to the item type. Page items are assigned the class pagetab; category items are assigned the class categorytab. The class for the home link is hometab and the class for the login link is admintab.

If the currently displayed page corresponds to a list item in a displayed navigation list, the LI for the page_item class is modified to become current_page_item. This follows the same convention established by the WordPress function call wp_list_pages.

---

An example of a navigation list can be seen by clicking the link below.

A Navigation List Example (Show/Hide Example)

---