PieLinkingPages

Linking Pages

Pie offers the following types of links:

Links Inside Continuous Text

The simplest way of linking to resources is to make use of Pie's auto recognition of certain types of text blocks just as you type them in.

Wiki-Names

The first link type Pie regognizes is character strings consisting of strict, native Wiki-names. Wiki-names placed somewhere in the continuous text are automatically recognized as Wiki-links, that is, links to other pages on the same server.

External Links

The second type Pie regognizes is character strings consisting of valid URLs. URLs, too, are displayed as links embedded into the surrounding continuous text. Note that a valid URL needs its protocol to be included. Consequently, http://www.gnu.org/ is recognized as a link, but www.gnu.org is not. URLs referring to resources on external network entities, that is, pages beyond the local web server, are always opened in a new window.

The third type of recognized links is e-mail addresses. If your text contains a valid e-mail address, like info@foo.bar, it is rendered as a link instead of continuous text and readers can directly click it to address the respective recipient.

Internal Links

In the section about Creating Pages you learned why and how to create links to new or already existing pages. To put an internal Pie-link onto your page pack its name into double brackets:

 [[MyPage]]

Wiki-names, as long as in their native format, are automatically recognized as links when you type them and do not need to be enclosed in double brackets. It is a question of personal style whether or not to include the additional brackets on both sides of the Wiki-word. Some people accept the pain of typing the four extra key strokes to make their sources more readable and bullit proof.

To emphasize the meaning, you can do the same for external links, packing the URL into brackets. Yet, for well-formed URLs, http://www.gnu.org/ is just the same as http://www.gnu.org/

Note that the auto recognition of links work for strict Wiki-names only. Persona_thought_on_autumn_moods, being a valid Pie-name but not a Wiki-name, is not recognized as a link. You would have to enclose it in brackets. The reason for this inconvenience is downward compatibility support of the original Wiki syntax.

Last comes a special internal link that refers to the Pie-engine itself: "me:". Placed as the first part of a text inside double brackets, it creates a link with the server's name and file path of the installed Pie library, followed by any text that succeeds the colon.

 [[me:?action=upload]]

for instance, creates a link of Pie's location plus the additional command specifier ?action=upload. Naturally, me: has to be enclosed in brackets to be recognized as a special construct.

Internal Anchors

You can place labels (i. e. anchors) anywhere in your document using the pound (#) selector, followed by the label. The label itself must consist of a Wiki-name. Labeled page sections can be referred to by links via

[[PageName#LabelName]]

Note that if you place internal anchors on lines by themselves, Pie creates a separate line in the output. Therefore, you might want to place them somewhere in your continuous text instead. Example:

== [#InternalAnchors]Internal Anchors
You can place labels (i. e. anchors) anywhere...

Alternate Text

To provide an alternate text to be displayed along with your link, append the page name or URL with any kind of blank-separated text, like this:

 [[MyPage my personal page]]

the result of this being the link's alternate text being displayed instead of the link pointer. The same way, you can apply alternate text to any other type of link, be it internal yap_Binary resource or external link.

 Have a look at [[MyPage this page]], please.
 And this is [[info@foo.bar my e-mail address]].

Alternate texts work only for links placed inside brackets, of course.

In chapter Editing Pages you will learn that text spans are surrounded by single brackets. However, if a span lacks a selector (that is, the character that defines the enclosed text's behaviour), but starts with a capital letter followed by a combination of valid Pie-name-compatible characters instead, the span's content is assumed to be a link. Consequently, you could put links in single brackets instead of double brackets, saving two characters (brackets) along the way. Yet, the use of double brackets represents the most preferable and straight forward approach to mark a portion of text as a link.

Links to yap_Binary Files & Resources

Uploaded yap_Binary files can be linked by their respective names, just the same as bracketed page names:

 [[TechnicalDetails.pdf]]

represents a link to the local homonymous file. yap_Binary file names, too, represent a superset of native Wiki-names and therefore require brackets to be recognized as links.

One sort of yap_Binary files is special: images. Images are displayed on your pages directly instead of being just linked. Pie recognizes (i. e. guesses) the types of linked files by their name extensions. It treats files with the following name extension as images: gif, jpg and png.

[ Seite drucken ] [ nach oben ]
Zuletzt bearbeitet am 2005-07-21 03:08 von .
Ausgegeben in 0.0123 sec