Genii Weblog

Anchors aweigh

Sun 2 Nov 2003, 11:31 PM



by Ben Langhinrichs
Notes/Web Coexistence Tip #2

It is so much fun writing technical content on something other than rich text, I'll think I'll throw in another one from my Advanced Notes/Web Coexistence session at the recent UK Admin-Developer Conference.  Let me know if you think I should keep posting these coexistence tips or retreat back to my rich text cage. <grin>

Back in Notes R4.6, Lotus added a great new feature, anchor links, with the kind of irritating limitation that seems to plague Lotus when adding great new features.  An anchor link lets you go to a specific spot in a document, not just to the document.  Anchors are used extensively on the web as a way to point at another part of the same document (table of contents) or to a specific point on a complex page.  These were destined to be a big hit in the Notes world, right?

Wrong!  As a matter of fact, it is not uncommon to find that developers don't even know they exist, and users, who should be able to use these easily, are not taught to use them at all.  Why, because the product management at Lotus did not think hard about how anchors could really be used, and made two crucial mistakes:

1) Anchors cannot be made on their own.

Never mind that anchors on the web are virtually always made separately from the links which point to them.  In Notes, you have to make the anchor at the same time as you make the link, meaning that the person making the link to point to the source document must have the ability to modify the target document.  

2) Links can't be modified to point to an anchor.

It almost would have been OK to have the first limitation, but the second clinched the problem.  If a second person wanted to make a link to a specific document to a specific location, they had to make a new anchor and link, and know what the previous one was called, and know to delete the anchor they just created, etc. etc.  It just wasn't usable.

So, as Release after Release of Notes came out, one might have assumed that these issues would be addressed.  Unfortunately, they have not been.  So, short of using the C API or Midas to create anchors and links to anchors, they have become a very much underutilized feature.

Anchors on Forms
If you think that I have a magic solution to this problem, you're wrong.  What I do have is a semi-solution, using yet another feature which isn't documented to work with anchors.  While precious little is documented about anchors, it is clear given the only way they can be created that they are not supported on forms.  Additionally, even if you could put an anchor on a form, you couldn't create a link to it (see #2 above).  But there is a trick, and it works for both the Notes client and the web.

Step 1) In any document with a rich text field, create an anchor link with the desired anchor name.  It can be a throwaway document, since you don't really want an anchor link there.

Step 2) Copy the small anchor symbol  from where it was created to where you want it on the form.

Now, you have an anchor on the form where you want it.  You then have two choices of how to use the anchor.  The first is a link that is also on the form, so a long, complex form could have a Go to Top link, for example.  In this case, the following steps allow you to set a link to the anchor (which is presumably at the top of the form).

Step A1) Go to the place on the form where you want the link, enter the desired text, such as "Go to Top".

Step A2) Select the text and create an Action Hotspot.

Step A3) Change the client action type to LotusScript and enter the following script (assuming the anchor name is "Top"):

Sub Click(Source As Button)
   Dim ws As New NotesUIWorkspace
   Dim uidoc As NotesUIDocument
   Dim doc As NotesDocument
   Set uidoc = ws.CurrentDocument
   Set doc = uidoc.Document
   uidoc.Close
   Set uidoc = ws.EditDocument(False, doc, False, "Top")
End Sub

Step A4) Switch the Run parameter to Web and make sure the web action type is JavaScript and type the following script:

top.location = "#Top"

Step A5) Make sure the hide-when flags for the action hotspot are set to hide when the document is open for editing, as this code will not work properly unless you are in read mode.

Now you have a functioning anchor and anchor link for both the Notes client and web in a single link, albeit with slightly different code for Notes and web.  Now, what if you want to create a link in a rich text field on the document to the same anchor on the form?

You have two choices.  One choices is that you can create a link just the way we just did for the form and put it in the rich text field.  The second choices is that you can use the Edit - Copy As Link - Anchor Link... and create an anchor link to the document with the exact same name as the anchor on the form, then delete the anchor () tag and make your link as a regular link hotspot, either on this document or another.  The link will go to this document, but the spot it will go to is the anchor on the form.

There you have it.  Fixed anchors on forms, and code or techniques to link to those anchors.  Whether you choose to use this the way it is done on the web, to form a mini-table of contents with links to places on the same document, or to provide a link to specific spot on a different document, you do not have to live with all the limitations that you normally face with anchors.  Maybe in Notes 7, IBM will finally address these issues and make it even easier, but until then, make better use of this great feature that has been around since R4.6.

About the title
By the way, if anybody thinks I mistyped the title, and it should be "Anchors away", see this page for a bit of elucidation.

Copyright © 2003 Genii Software Ltd.

What has been said:


64.1. Ned Batchelder (11/03/2003 05:38 AM)

Well, you are undoubtably right that anchors could be much more useful and used if they had been more usable.

But some of the design is not contrary to the web, but a consequence of it. In particular, your first point: that the target document must be modifiable by the creator of the link. This is how the web works, and is one of the deficiencies the creators of XPointer and XPath hoped to fix. Named anchors in URLs can only point to <a> tags already present in the target document. This means the author of the document is the only one who can create targets for links. If you want to link to a section of a document not anticipated by the author, you must be able to modify the document in order to do it.

The same rule is present in the Notes implementation. I guess we could have tried harder to do it differently, but the goal at the time was to make Notes use more of the concepts familiar to Web developers.

If you wanted to link to content without prior anticipation by the author, how would you do it? XPath and XPointer want to do it like p[4] (the fourth paragraph), but what if the content is edited? You could do it by content (the paragraph that begins, "You have two choices"), but again: what if the content is edited? The only way to guarantee effective links is to let the author leave an explicit target in the document. This puts back the requirement that the linker be an author.

I'm sure we could have done a better job, and I apologize for my part in the deficiencies, but some of this behavior is the best of all possible worlds.


64.2. Ben Langhinrichs (11/03/2003 06:00 AM)

Ned, sorry if I was a little harsh. I don't entirely agree with your point about this being a consequence of the web. It is true that if the author has not anticipated the use of the anchor, the person pointing must have the right to modify the target, but that seems to ignore almost all real use of anchors on the web. I point people at specific anchors on the web all the time, and have never had the ability to modify any of those pages. Why? Because the anchors could be and were created prior to use of the link, and because I could specify an anchor in the URL without adding it to the document at the same time.

The solution in Notes would be quite simple. 1) Allow a menu item to Insert Anchor. 2) Allow a document link to be modified (via the drop down button that is already there) to be an anchor link and specify the anchor manually. Neither change would require much coding, I would guess, and neither would have much UI impact, but those two small changes would make anchors much, much easier to use.

Again, I hope I didn't offend you, but the limitations on this feature have been an annoyance for years.

By the way, I must admit that I have tried to follow the logic behind XPath and XPointer (XLink) and have gotten hopelessly confused. It seems a very complex solution to a relatively simply problem, but I'd love to see a simple explanation of the general idea, either here or in your blog. Any chance?


64.3. Ed Brill (11/03/2003 10:44 AM)

kind of an oops in your RSS feed, where I was able to read: "Why, because the --{strikethrough}brainless fools-- product management at Lotus did not think hard about how anchors could really be used, and made two crucial mistakes". not that I haven't been called worse ;0


64.4. Ben Langhinrichs (11/03/2003 10:52 AM)

Ahh, yes, my first version. I changed it after Ned seemed to take offense, but my RSS doesn't percolate through as quickly. Good thing my boss isn't likely to fire me <grin>. OK, it was a bit harsh, but this is one of those omissions that is hard to deal with. Anchors were a great added feature that has barely been used, and you folks have released the 4th major feature release without making minor changes to make them usable. I certainly don't want to slam you, Ed, but it is the sort of thing that gives Lotus a bad name, and neither of us wants that. So, sorry about the nastiness, but the general sentiment stands.


64.5. Ned Batchelder (11/03/2003 07:07 PM)

I didn't take offense. I know in my own work, if I have to live with something imperfect, I prefer to understand the reasons behind it than to have to accept it unquestioned. I was just trying to provide some background.

Besides, being an engineer, who am I to question your assessment of product management? ;-)


64.6. Ben Langhinrichs (11/04/2003 08:09 PM)

Thanks. I appreciate the additional information. I like your idea about auto-creating the ids. I didn't even know you could use ids that way for anchors, but I'll look into ways I could use that as well. Cheers!


64.7. G. Bendtsen (09/20/2004 08:44 AM)

Fantastic article. I started investigating the use of Anchor links on Friday, 9/17/2004. So far, I have found a lot of information and started to realize the limitations, which your article explains quite well. One of the steps was quite counter-intuitive (create an anchor that you will throw away, etc.) but I did it anyway and it worked, at least from my initial attempts. Thanks for the information!

By the weigh (grin), I didn't make any headweigh (foolish grin) at first on this, as I couldn't think of the term Anchor; my brain could only come up with Bookmark.


64.8. Tim C (19/10/2004 08:50 PM)

Awesome blog Ben. The solution you provided for using anchors in forms is just perfect. While this is just a work around, it's a damned good one.

I am using this method in a template for complex technical documentation. Well done and thanks once again.