Editing Menu

Overview

This document contains full instructions for editing and maintaining the menu tree for the website.

The easiest way to get started is to get me to demonstrate it to you.  However this document might be useful as a reference.

Contents of this document

Other pages

Introduction

Editing a menu consists of using the menu editor to add, delete, move or change menu items.

The editor is very easy to use.  It's also very powerful since it can move whole chunks of menu around at once.

These chunks are called subtrees which we'll now explain.

Branches, leaves and subtrees

Think of a menu system as a tree consisting of branches and leaves.  The leaves are the documents you want to find, and the branches are category labels to help you find them.

The difference between a branch and a leaf is that a branch leads to other branches or leaves on the menu, while a leaf is where the menu stops.  A leaf provides a link to something off the menu.

The editor handles whole subtrees.  A subtree is everything that a branch leads to, including the branch itself. Here's a diagram to make it clear:

tree diagram

In this diagram, A...P represent menu items, ABCFJKN are branches, DEGHILMOP are leaves and BCFDEGHI is the subtee defined by B.

Both leaves and branches have labels - they're the words you click on.  But as we've said, leaves also have links. A link is the address of the document that the browser will fetch if you click on the label.  The link isn't visible from the menu, but it's still necessary to edit it.

Editing

We can do all the editing we need by using combinations of just these few operations below:

The editor comes with a set of commands to carry out all these operations.

Running the editor

When you run the menu editor it displays the familiar menu, which although it looks normal, behaves very differently in the editor than it does on a normal page.

The difference is that when you click on a leaf, the link isn't fetched.   Instead, clicking is used to designate that item and everything it leads to as a subtree for editing.  The designated item and information about it are all shown in a box on the right to help you be certain you're dealing with the right item.

Its label and link (if it's a leaf) are also shown in editable yellow boxes called Designated Item Label and Designated Item Link.  You can change these if you like and have the changes incorporated into the menu (using the Update current entry as modified below command).

Any subsequent editing command will act upon the designated item.

So if you click the Prune command, the designated element and all its descendents will be cut from the tree.  You can then if you wish Graft this subtree as a set of descendents of some other item.  (But you must do so before pruning anything else as this operation only works for  the last pruned subtree).

To create a new item from scratch at the start of the menu, type in the new label into the Designated Item Label box, (and if you're creating a leaf type in the link into the Designated Item Link box) and click the command Insert item below at start of menu.

If you want to insert a new item somewhere else than the start of the menu, first designate (i.e. click on) the item you want to graft onto, then type in the new label and link information, and finally click the command Graft item below onto designated item.

Whenever you carry out an operation, the change shows up immediately on the menu you're viewing, so you instantly see if it's what you intended.  However no changes are saved until you carry out a specific save operation (described later).  If you make a mistake which you can't see how to fix, you can merely exit the editor without saving and no harm is done.

If you've understood so far, the use of the edit should be fairly straightfoward.

Saving

When we're happy with our work we need to save it.  The menu is saved in a file called menu.js.
(it's actually in the subdirectory "/common/")

However, saving the menu file is potentially the most dangerous operation you can perform.  The menu you've just created might be full of errors you havent spotted yet.  If you're not careful you'll overwrite the original menu.  So before you go any further, protect it (see below).

The current menu is saved as a javascript text file called menu.js kept in a special folder.  There is a command labelled Generate output menu which creates the correct contents for such a file, and all we have to do is save the result.

You may notice there is no file save command.  This is because, for very good reaasons, web pages can't save files.  (This is to prevent a malicious website from messing with your files.)   So we need a workaround.  Fortunately it only takes a few seconds.

Firstly click the command Generate output menu.  This brings up a new web page in another browser full of text like this:


   var menu1 = new Array(

   --- here there are lots of lines of text

   );

There will probably be an enormous amount of this text. All you have to do is copy and paste this into a blank text file, and save it as menu.js. It only takes a few seconds. (But of course you back up the old one first ... see below).

So altogether there are these three steps:

  1. Click the command Generate output menu.  A new browser appears showing the text to be saved.
  2. Copy the text.  To do this click anywhere on the page and type Ctrl-A to select everything, then Ctrl-C to copy it all to the clipboard.
  3. Save the clipboard contents in a file.  To do this open notepad and create a new, blank file, click anywhere in the new file then type Ctrl-V to paste the clipboard contents.  Then save the file with the name menu.js.

Precautions and Version Control

Because the document system depends crucially on the integrity of the menu, and because it's easy to corrupt a perfectly good menu and make the system unusable, it's necessary to take careful precautions when editing the menu.

It's a good idea to save the menu file using a name which includes a serial number - something like menu-00735.js, where 00735 is the serial number which you increment every time the menu's changed.   The actual working menu file must be called menu.js, and you obtain it by making a copy of say menu-00735.js and renaming the copy menu.js.   If this version doesn't work you just delete it and replace it with a re-named copy of the last, correctly functioning menu, say menu-00724.js.

It's a bit tedious, but if you've ever confused yourself by cutting corners you'll never make the same mistake again!

You'll also need to keep a careful record of what was changed in each version of the menu.  Such records are typically kept in a computer log file whose serial number also forms part of its filename, and which is also incremented each time the file is edited.

Another good precaution with any type of editing is run two versions of the entire system - a live version and a work-in-progress version.  The latter is the one you make changes to, which would include editing the menu.   Because it's a complete copy of the whole system you can check that everything on it works, including all the links between items.  When you're totally sure everything's OK you can make the work-in-progress copy the live version, or if the only change you made is the menu, you could just repace the menu, having backed up the old one of course.

Testing a new menu

When you test the menu, or anything else you need to check two things:

Sorry, but you can only check these things by doing a lot of clicking!

Link format and Relative Addressing

Here's a note about links.

Firstly, we've said that every leaf must have a link.  Actually in our system this is not quite true.  There is a default page which is what you get if you don't specify the link.  This default page is just the dummy one which appears for menu items which haven't been supplied.  It's quite useful having a dummy page because it means we can expand the menu in preparation for pages which aren't ready yet.  So for our particular system you can actually leave a blank where there should be a link and you'll get the dummy page.  What follows therefore is for other, normal pages.

When specifying a link, it must be in the correct format or the browser won't be able to find the page.  Usually it's very straightforward, but there are some special circumstances you need to watch.

A link refers either to an address on the Internet or to a local file on the same computer or a local network.

Internet link

If it's an Internet address it must begin with http://.  It will usually take the form

http://www.whatever.com

Local file

If it's a local file we specify it using its file name.  But if the other file isn't in the same directory as the page calling it we need to be a bit careful.

Here's how it works.

Example of local file link

Here's an example which covers all possibilties.  The diagram below refers to files in folders.  It looks a lot like the structure of the menu.  That's because they're both tree structures.  But don't confuse menus with folders.

Suppose you're viewing a document called doc3.html.   Suppose that document is embedded in a folder structure like this. 


folderA———folderB———folderC———doc1.html
        |         |         |
        |         |         |—doc2.html
        |         |
        |         |—doc3.html   <— document the user is viewing
        |         |
        |          —doc4.html
        |
        |
        |—folderD———doc5.html
        |         |
        |          —doc6.html
        |
        |
        |—doc7.html


In other words

folderA contains folderB, folderD and doc7.html

folderB contains folderC, doc3.html and doc4.html

folderC contains doc1 and doc2.html

folderD contains doc5 and doc6.html

Suppose you click a link to doc4.html.  Because doc4.html and doc3.html are both in the same folder, the correct format to write this link is simply doc4.html.  This rule covers the majority of cases.

But if you click a link to doc1.html the correct format would be

folderC/doc1.html.

because folderC is in the same folder as doc3.html and doc1.html is in folderC.  Note that we don't need to mention folderB.

If however the link refers to doc7.html the correct form is then

../doc7.html

The notation ../ (dot dot slash) means "the folder up one level from this folder" (i.e. folderA which contains doc7.html).  Similarly .../ means "up two levels from this folder" and so on.  Note that ./ means "this current folder" and we normally omit it since the current folder is used by default.

Although ../ actually means folderA we deliberately don't refer to it by name, just by its position relative to the current folder. This is called relative addressing and has a great advantage explained below.

Finally if the link refers to doc5.html we'd write

../folderD/doc5.html

We can think of this as "up one level of folder (to folderA) then down through folderD to doc5.html".

Why?

This relative addressing has a huge advantage.

With relative addressing we can copy entire web sites, including all the folder structures, and the copy will work perfectly. 

The only alternative is to use absolute addressing where we must specify the full path to the document which might be something like:

"file:///c:Applications/MyWebStuff/folder1/folder2/folder3/folderA/doc7.html"

The problem is not just the length of the specification.  If we copy the website, we'd also need to change every link in the menu in the copy version because the rest of the path name would be different.  This would include, not just the links in the menu, but all the internal links in all the documents themselves.

But why would we want to copy a web site?   Copying web sites is actually something we constantly want to do.  As we've already pointed out, we usually edit and work on a copy of a web site on a local computer, to avoid corrupting the live version which is usually on a remote server.  As long as both copies share the same relative addresses we don't need to bother with the absolute addresses.

Diagnosing problems

The editor contains a checkbox labelled Indent menu file.  When this is checked the generarted menu file, menu.js is indented to make it easier for humans to ready at the slight cost of increasing the file size.

(C) John Gordon 2007.    Last modified : 2007-Apr-19