= 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:
[^]
}}}
You could of course achieve the same effect by doing this:
{{{
{{{
#!html
[^]
}}}
}}}
Resulting in this:
{{{
#!html
[^]
}}}
But who wants to do all that typing?
That's what [http://en.wikipedia.org/wiki/Macro_(computer_science) 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 [http://github.com/dwclifton/tractopmacro/tree/master/0.11/top/macro.py#path 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:
{{{
${select('*')}
}}}
'''Note''': Returning false from the lambda, or anonymous, function prevents the browser from kicking in it's own event model.
== Installation ==
Download the zipped source from [/attachment/wiki/TopMacro/topmacro.zip?format=raw here] or
clone the repository (see [#Source below]) from !GitHub to a location on your local drive.
Unzip the archive to a temporary location, visit the [http://github.com/dwclifton/tractopmacro/tree/master/0.11 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: [http://github.com/dwclifton/tractopmacro/tree/master/0.11 GitHub].
* Public clone URL:
{{{
git clone git://github.com/dwclifton/tractopmacro.git
}}}
== Bugs/Feature Requests ==
Existing bugs and feature requests for TopMacro are [query:status!=closed&component=TopMacro&order=priority here].
If you have any issues, create a [/newticket?component=TopMacro&owner=dwclifton new ticket].
== Recent Changes ==
[[ChangeLog(topmacro, 3)]]
== Author/Contributors ==
* '''Author:''' [wiki:dwclifton].
* '''Contributors:''' The Python/Trac development community.