wiki:TopMacro

Top of page Macro

Description

TopMacro is exceedingly simple, like all good software ;-). In a nutshell, it does exactly what you'd expect, inserts a "top of page" link in your Wiki page. The only option is a string that is inserted into the content of the markup. This defaults to a single circumflex "^" character (more commonly known as a caret), surrounded by square brackets. The anchor element returned includes a "Top of Page" title attribute so the user knows its purpose, and a "topofpage" class so the Wiki author may apply their preferred style rules.

[[Top]] returns:

[<a class="topofpage" href="#" title="Top of page">^</a>]

You could of course achieve the same effect by doing this:

{{{
#!html
[<a href="#" title="Top of page">^</a>]
}}}

Resulting in this:

[^]

But who wants to do all that typing?

That's what macros are for after all. Note that the brackets do not form part of the anchor itself. This is a personal preference. If you pass a string to the macro they are omitted.

Styling

If you like the caret, but prefer to omit the brackets and style the link yourself with CSS, try something like this:

a.topofpage {
  display: block;
  height: 11px;
  width: 11px;
  font-family: 'BitStream Vera Sans',Verdana,Arial,Helvetica,sans-serif;
  font-weight: bold;
  text-decoration: none;
  background-color: #eaeaea;
  color: #e9611c;
  padding: 1px 2px 2px;
  border: 1px solid #c6c7db;
  margin-left: -6px;
}
a.topofpage:hover {
  border-color: #000;
  background-color: #777;
  color: #fc3;
}

Note: If you're going to style the anchor like this you should really pass an argument to the macro or you'll end up with the default brackets in addition to the styling.

Behavior

If you want to get really fancy you can use jQuery to create a smooth scrolling effect when the link is clicked. In your site.html template add:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://genshi.edgewall.org/" py:strip="">
 <head py:match="head" py:attrs="select('@*')">
  ${select('*')}
  <script type="text/javascript">
   jQuery(function($) {
     $('a.topofpage').click(function() {
       $('html, body').animate({scrollTop:0}, 'slow'); 
       return false;
     });
   });
  </script>
 </head>
</html>

Note: Returning false from the lambda, or anonymous, function prevents the browser from kicking in it's own event model.However, it degrades nicely and still works even if the user has JavaScript disabled.

Installation

Download the zipped source from here or clone the repository (see below) from GitHub to a location on your local drive. Unzip the archive to a temporary location, visit the 0.11 directory and run:

python setup.py bdist_egg
cp dist/*.egg /trac/env/Project/plugins

Configuration

Enable the macro in:

/trac/env/Project/conf/trac.ini:

[components]
top.* = enabled

You may need to restart your Web server.

Examples

[[Top]]
[[Top(^)]]
[[Top(top)]]
[[Top(Top of page)]]

Source

  • Browse the source at: GitHub.
  • Public clone URL:
    git clone git://github.com/dwclifton/tractopmacro.git
    

Bugs/Feature Requests

Existing bugs and feature requests for TopMacro are here.

If you have any issues, create a new ticket.

Recent Changes

[5040] by dwclifton on 2008-12-21 21:51:41
New hack TopMacro, created by dwclifton

Author/Contributors

Last modified 14 months ago Last modified on Aug 7, 2013 4:49:20 AM

Attachments (1)

Download all attachments as: .zip