Links

Links Guide

How to make and use links in the GasBuddy Organization (GBO) message forum.

Return to Guides Index

Tutorial philosophy

Some have remarked that this tutorial is too technical. For those who wish simplicity, let us boil this entire page down to "Fill out the Insert Link form." As usual, when things are maximally simplified, problems arise, because you don't really know what is going on "behind the curtain." When there is only one button to be pushed, if things don't go as planned when you push it, you have a choice: give up or engage in a long voyage of exploration to learn how it all works (or doesn't). The voyage has been taken for you and this page is the result. Read it, and, while you may not remember it all, perhaps some of it will resonate when things don't go as expected.

Legend:

1. Numbered notes are shown at the bottom of this page, below the Appendices. The arrow at the beginning of each note is a backlink to the point where the note originated.
2. System parts (functions, forms, buttons, etc.) are shown in italics.
3. System input that must be entered by the user and output that the system displays is shown in monospace type with a light gray background.
4. For reference purposes, examples of links are numbered in grayed-out italics; they are intentionally non-functional.

About links in general

Use

Links are clickable Webpage elements which allow the author to offer the reader the choice to move around between:

• Portions of a page ("section links"). For GBO pages, this is a suspected, but not known option.
• Pages of a Website
• Websites
• Some combination of the above.

Terminology

• Anchor - The place where a link is clicked. The author places an anchor on the page where desired.
• Target - The place—Website, page or place on a page—where a link leads to. This is the URL typically copied from some page the author wishes the reader to visit.
• Back link - A link at the target that will return the reader back to the anchor from whence he started. GBO does not provide back links, depending instead upon the reader to manually return to the anchor page.

Appearance

Links should have, are not required to have, but almost always do have, a special appearance so that the reader will know they are links. Typically, links are underlined and appear in blue, a practice always followed on GBO pages.

Construction

Links are formed by enclosing segments of code—which make the links work—within delimiting characters, this assemblage being called an element. The codes used therein and the characters used for delimiters depend upon the venue where they are used:

• Webpages - Uses HyperText Markup Language (HTML) tags that are delimited by angle brackets (< and >). HTML tags don't work on GBO pages (see Appendix 1, below for an explanation).
• Other wikis and forums - Standard ones may use Universal Bulletin Board Code markup (UBBC), delimited by square brackets ([ and ]). These are ignored on GBO pages.
• GBO forum - The forum uses a custom tag, delimited by square brackets ([ and ]). This is the subject of this wiki, because the first two, above, are useless for forming links on GBO pages.

Link use limited to Senior Members

You must be a Senior Member—have earned 10,000 points—in order to post a link in a forum message; those with fewer points will have all links, regardless of how they are created, stripped from messages when they are posted. Note that until they achieve senior status, anyone can post a URL in a message; it just won't be a clickable link.

Fine Technical Point: This scenario demonstrates the need to be a Senior Member:

1. The author, a Sr. Member, logs in.
2. The author prepares a message containing a link.
3. The author opens a second instance of GasBuddy in another tab of the same browser (in which he will be continued to be logged in).
4. The author logs out of the second instance.
5. The author posts the message in the first instance.
6. The system displays the message, but the link will not present, because, the author logged out and the system, no longer able to recognize his senior status, deleted the link.

A custom link tag for the forum

A link tag is the only custom GBO tag known. It is case-insensitive and may be placed anywhere in a forum message. A delimiter is a character marking the start and finish of a tag. The link tag is delimited by square brackets ([ and ]). It takes this form:

Example 1:     [L=someURL]somelinktext[/L]

where, [L= is the first half of the opening tag,
           someURL] is the second half of the opening tag, containing the Web address of the link target,
           somelinktext is the text the reader will see as the link, and
           [/L] is the closing tag.

There are two kinds of links: external and internal. The system knows the difference and treats them differently in order to improve the readers' experience, and this, too, will be explained in detail.

The rules for link text in the forum

Link text is the underlined word(s) that user will see in a forum message to indicate the presence of a link and it is what is clicked to activate a link. In venues other than the forum, if no link text is furnished, it is assumed that the URL itself is to be displayed as the link text, but not at GBO. Here are the rules:

1. If visible link text is furnished, a link will be formed and the text will be displayed as one would expect.
2. If no link text is furnished, no link is formed, and the characters of the link, tags and all, will be displayed in the message, forming sort of a poor-man's error message.
3. If invisible link text is furnished, it is uncertain if a link will be formed, but in any case, the link will not be usable because the reader will see no place to click.

The rules are illustrated by these examples:

Ex.	This link when posted	appears as this, but	will it form a link?	Does link work?	Rules followed?
2	[L=someURL]sometext[/L]	sometext	Yes	Yes	Yes
3	[L=someURL][/L]	[L=someURL][/L]	No	No	No link text
4	[L=someURL] [/L]		Can't tell	No	No visible text
5	[L=someURL]   [/L]		Can't tell	No	No visible text
5	[L=someURL]&nb‌sp;[/L]		Can't tell	No	No visible text
6	[L=someURL]_[/L]	_	Yes	Yes	Cute, but yes

After a message is posted, if the link tags are visible as in Example 3, you know to edit the message and type in some link text so that it will look like Example 2.

External links

An external link is one to a non-GBO resource, that is to, say, a Website outside the GBO system. The link is formatted as follows:

Example 7:     [L=http://someURL]somelinktext[/L],

where, http:// is the protocol indicator for the World Wide Web
          someURL is the Web address of the destination page, called the target and
          somelinktext is the underlined text that the reader will see as the link.

If the following real link is posted in a forum message,


Example 8:     [L=http://gb-guides.shoutwiki.com/wiki/fs-links]A guide for links[/L],

it would link to the page you are now reading and appear in the message as:


Example 9:     ;A guide for links.



Internal links

An internal link is one to a GBO site page. An internal link is formatted differently than the external link shown in Examples 7 - 9. The protocol and domain name are omitted, leaving only the page and link text:

Example 10:     [L=somepage]somelinktext[/L]

where, somepage is all of the target page's Web address that normally follows the domain name, namely, the page name and coding parameters used by that page (if any) and
          somelinktext is the underlined text that the reader will see as a link.

The following actual link example, when inserted in a forum message, would link to a moderator's topic through whichever site the reader was currently using (this "site anonymization" is further explained in Appendix 3):

Example 11:     [http://www.sactogasprices.com/Forum_MSG.aspx?master=1&category=1055&topic=200714&page_no=1&FAV=N]

The URL of Example 11 was copied from a browser address bar after accessing a GBO site. For the curious, more information about how a typical GBO URL is constructed is available in Appendix 3.

Methods of entering a link in a message

• Manual entry - The author types the complete link into a message where desired. The author of a manually-entered link is responsible for some not-too-obvious technical ramifications which will be explained below, or,
• Insert Link feature - The system provides a form to guide the author. It has desirable automatic features that relieves the author of certain technical responsibilities and is explained below under Insert Link feature.

Use of Reserved Characters in URLs

Certain characters, called reserved characters, are not allowed in URLs by the rules of the Internet. They are:

RFC 3986 section 2.2 Reserved Characters (January 2005)

!

*

'

(

)

;

:

@

&

=

+

$

,

/

?

#

[

]

Nevertheless, GBO will tolerate most of these characters in a URL and will form a link which contains them when a message is posted. There are three exceptions as used in these examples for a fictitious URL, http://somesite.com/aaXaa.html, where X is the reserved character:

Ex.	Char	URL in Link Tag/Insert Link (Input)	Finished Link (Output)	Result
12	'	http://somesite.com/aa'aa.html		No link is formed.
13	[	http://somesite.com/aa[aa.html	[L=http://somesite.com/aa[aa.html][[/L]	Link is malformed.
14	]	http://somesite.com/aa]aa.html	aa.html]]	Link is malformed.

To sum up, these characters must not be used directly in a GBO forum link target URL even if they work on the Internet in spite of breaking the rules. An actual example of such a rule-breaker that works is: https://en.wikipedia.org/wiki/Governor's_Mansion_State_Historic_Park. Yet, due to the apostrophe, this URL will not form a link in the forum.

However, there is a workaround for any link containing one or more of the three troublesome characters, namely, using a URL-shortening service (explained below) to avoid their direct use. (In the case of the Park example, it has been shortened to http://tinyurl.com/nadgen6, which, of course, will form a link in the forum.)

System link length limits

Depending on several factors, the link has a maximum size for both URL and link text fields and also the two combined (see Appendix 2, below, for details). This presents a big problem to users who have no knowledge of the limit. If the maximum is exceeded, the system will delete some portion of the link and one or more text deleted phrases will be inserted, which is the only warning the author gets. Unfortunately, this occurs only after the message is posted, that is to say, when it is nearly too late to do anything about it. So the author has only five minutes—the current edit window length&emdash;to deal with the size problem, which may enough time, especially if the author is inexperienced. Thus it behooves the author to test a suspiciously-too-long link first before using it.

To test a link in the forum,

1. Open a new topic in the Just For Fun Category.
2. To prevent reader confusion, label the topic, Test (Do not read)
3. Enter the proposed link in the message, either manually or by use of the Insert Link feature.
4. Post the message.
5. Inspect the result as it appears in the posted message.
6. Use the link to ensure that it performs as desired.

If the phrase text deleted appears in the link, the link is too long and the author must employ a workaround to shorten the link.



Workarounds for too-long links

If the system rejects a long link by inserting the phrase text deleted in the link, there are ways to deal with it:

• Shorten the link text - The total link length is a factor, so for every character less that is used in the link text, you may either increase the length allowed in the URL field by one or shorten the entire link as a whole.
• Shorten the URL - This will shorten the link as a whole.

Methods of shortening the link text

To show how you can shorten a too-long link, let's begin with one that we know will fail:

Example 15:     [L=http://unicorns.org/apagenamethatistoolongforgasbuddytohandlewithalinktext.html]Click here to see fantastical unicorns.[/L]

If this had worked as the author had wished, the reader would see:

Example 16:     Click to see fantastical unicorns..

However, the long link text used in Example 7 means that the length of the finished link would be greater than the maximum permitted, perhaps yielding this mangled link:

Example 17:     [L=http://www.unicorns.org/text deleted to see fantastical unicorns[/L]

which fails due to the replacement of some of the URL by the phrase text deleted, not to mention a missing square bracket.

Here is the same link code after it has had the link text reduced in length by the simple expedient of shifting some of the verbiage from the link text to text surrounding the link:

Example 18:     Click [L=http://unicorns.org/alongpagenamethatistoolongforgasbuddytohandlewithalinktext.html]here[/L] to see fantastical unicorns.

This rearranged version would appear to the reader as,

Example 19:     Click here to see fantastical unicorns..

The shortened link text has thus brought the link in under the size limit and it should no longer be rejected by the system.

Methods for shortening the URL

You can't very well cut out part of an URL and expect the link to work However, free services exist that will furnish you with a short code that may be substituted for the URL. This is how the process works:

1. Pick a service: tinyurl.com, bitly.com (associated alternates are: bit.ly, j.mp, urls.im, goog.gl
2. Go to the service Website.
3. Furnish the long URL to be shortened:
   

Example 20:
www.foundingfathers.com/georgewashingtonandthomasjeffersonwereconsumategentalmenandreallyfinefellowsnottomentionveryfamous.html

1. A shorter, coded URL is returned by the service:
   

Example 21:     www.tinyurl.com/xb2lsQ

1. Write down the short URL.
2. Test the URL to make sure it works, either by the method shown above in System Link Length Limits, or by using a test feature on the service's site.
3. If tested good, use the short URL in a link.
4. Post the message.
5. When a reader clicks the link, the user is sent to the service's site which substitutes the original, longer URL for the target.

The shortened URL is designed to be unchangeable—it cannot be edited—and is as permanent as the service which provides it.

Some services have terms of service (TOS) forbidding uses of shortened URLs that most users would regard as objectionable. An example is tiny.cc's TOS: http://tiny.cc/terms. It is up to the link author to read the TOS and choose the service that best suits the needs of the readers.

If you intend to use a short URL often in the future, either record it somewhere safe or use a custom version—called an alias

Some reliable URL-shortening sites are (these are not links due to Shoutwiki policy against linking to URL shortening services):

www.tinyurl.com	www.bitly.com	www.goo.gl

Previewing a shortened URL

Some readers may avoid clicking shortened URLs, because they can't tell where the shortened URL will lead; they fear that the true target might be some objectionable Web page. This fear can be assuaged by giving the reader a preview: before proceeding to the target, the shortening service exposes the target URL and asks the user if he wishes to proceed. This preview feature removes doubt at the expense of an additional mouse click (which could annoy some users).

The preview feature is obtained by using a slightly-altered shortened URL. The alteration is different for each service as shown by the examples in this table:

Ex.	Service	Alteration Method	A direct URL	A previewing URL
22	Bitly	Append: "+"	http://bit.ly/1Bonows	http://bit.ly/1Bonows+
23	Google	Append: "+"	http://goo.gl/RT9hAK	http://goo.gl/RT9hAK+
24	Tinyurl	Prepend: "preview."	http://tinyurl.com/m455kl9	http://preview.tinyurl.com/m455kl9

An alternative method is to provide two links; one, a direct link to the target (no preview), and the other, a preview link. The reader can then choose as he sees fit. Here is an example of both kinds of links being provided:

As written in a message by the author:

As published and viewed by the reader:

Note that, as published, except for the link text, there is no visible difference between the two kinds of URL until the reader mouses over the previewed link and sees the altered URL in his browser. In the case of the tinyurl.com previewed link, the prefix, "preview." becomes visible, but that might not mean anything to the unenlightened reader. Thus it is vital that the author explain the differences between the two in the link text as has been done in the examples shown. In other words, it would be poor practice to give both kinds of link with no further explanation in the link text, because the fear-filled reader may not recognize that a preview is being offered in one of them.

Nested links not allowed

A link may not be embedded in the link text of another link, else a failure occurs. A working link would be formed from the first (inner) URL, but the second (outer) link given in the URL field will be inoperative.

The Insert Link feature

This feature has a behavior that is not intuitive in many respects, so it will be explained in great detail.

When a logged-in Senior Member is composing a forum message, there will be an Insert Link button appearing to the left of the message dialog box. When the button is clicked, a form is furnished to aid the author in preparing the link. It overlays the present dialog box, which remains active beneath the form.

The form has two fields for entering the link data and an OK button to signal that the data is complete, but be aware of how the button works!

THE "BUTTON WARNING" - Ignore it at your peril
The Insert Link form's OK button is intended to close the completed form, process the link, paste the link in the message, and return you to the message dialog box to allow the message to be completed and posted. You must keep uppermost in mind that the OK button is not the default when the form is in view; instead, the underlying Post Message button of the message dialog box is the default. Therefore, when working with the form, should you press [Enter], the following inconvenient unintended consequences will result: The Insert Link form will close and the information in it will be lost. The unfinished message will be posted as is. As a result, you will have only five minutes to recover as follows: Start an edit of the message Open the Insert Link form Complete the form Click OK to create the link Correctly position the resulting link in the message Complete the message Click Post Message to post the message Review the posted message Re-edit to make any needed corrections by clicking Edit Click Post Message one final time to post the message
The lesson to be learned here is DON'T USE THE [Enter] KEY when finished with the Insert Link form! Instead click the form's OK button.

Insert Link autopopulates the URL field with a protocol indicator (a problem for external links only)

When the Insert Link form opens, by default, the URL field is populated with the protocol indicator for the World Wide Web, namely http://. When a URL is typed into the remainder of the field following the indicator, having the indicator already there should be no real problem, because you can see that the indicator is already present and simply not re-type it. However, if a URL is copied from a page onto the Windows clipboard and then the clipboard is pasted into the field, the copied page's indicator—a second indicator—comes along with it. This results in two indicators as seen here:

Example 24:     http://http://someURL.




An external link will fail if left in this condition, so, if cutting and pasting (vs. typing) the URL, make sure you delete the second indicator.

Insert Link's site anonymization process (applicable to internal links only)

This automatic process is the most important benefit of using the Insert Link form. When forming the link, the GBO site specified in the link is not used; rather, when the form is submitted, any internal link will be detected and made into a generic link to the same page on the reader's current site. The benefit is that if the reader is logged-in when such a link is clicked, after reaching the target page, he will continue to be logged in because he is still at the site where he used the link. Therefore he will be able to use any function to which he is entitled by virtue of his membership.

What triggers site anonymization

1. The author must use the Insert Link feature.
2. The Link field must contain a properly-formatted and known GBO domain name e.g. http://www.friscogasprices.com
3. The Link field must also contain a page name, either real, e.g. Forum_Category.aspx or dummy, e.g. somedummypage page
4. The Link Text field must contain at least one character, that is, it must not be blank.

If the above conditions are met, then system will construct a site-anonymous link as follows:

1. The protocol indicator, http:// is deleted,
2. The site domain name, somegasprices.com is deleted,
3. The page name, somepage is left untouched,
4. The link text, somelinktext is left untouched,

and the link target will be the specified page on whichever site the reader clicked the link.

For example, with the following URL entered into the Link field:

Example 25:     http://www.sactogasprices.com/Forum_Topics.aspx,

and the following text entered into the Link Text field,

Example 26:     the forum category index page,

when the OK button is clicked, this resulting link is placed in the message:

Example 27:     [L=Forum_Topics.aspx]the forum category index page[/L],

which, when posted, appears to the reader as:

Example 28:     the forum category index page.

With no domain name specified, the reader will see the specified page on the site he is currently using.

Avoiding site anonymization

If the above rules enable anonymization, it follows that anonymization can be disabled by breaking one or more of them. Thus if an author desires to link the reader to some site which the reader is not currently viewing, he can break the first rule to disable anonymization—he can type the link manually into the message instead of using the form:

Example 29:     [L=http://buffalogasprices.com/Prize_Give_Away.aspx]prize info[/L],

which will be posted unchanged exactly as typed, delivering the reader to the desired target site and page. If the reader wishes to use a system function that requires him to be logged in, then he must log in to the target site after arriving.

Where Insert Link places completed links

Links which are created while the message is being composed will be placed as the writer intends. This happens when the text cursor is at the end of the written text. However, links created after the text has been finished will be placed in a block at the end of the message regardless of where the text cursor is, and so they may or may not be where the author intends.

Let's say a block of links is created at the end of the text, but the author wants them distributed throughout the message. In that case the author must manually move them to where they belong within the text. Here is a method to do this:

1. Use the mouse to highlight a link which needs to be repositioned.
2. Copy the link to the Windows clipboard by typing [Ctrl-X] (which also deletes it from its position at the end of the text).
3. Position the text cursor by clicking the mouse in the message where the link is to be placed.
4. Paste the link from the clipboard to the message by typing [Ctrl-V].
5. Examine the inserted link to make sure the link text reads properly (and edit it manually if necessary)
6. Repeat until all links are correctly positioned within the text

-- End --

---

---

Appendices

Appendix 1 - Why HTML doesn't work on GBO Websites

HTML tags of any kind normally used on Web pages are blocked in the forum. When a message is posted, the forum software automatically converts any angle brackets (< and >) into the HTML entities < and >, respectively. An entity is a code appearing in text that will cause a browser to draw a specific character vs. being the actual characters themselves. In this case, when displayed, entities appear to the eye of the reader to be angle brackets, but they are not the angle brackets themselves. For HTML tags to work, the actual angle brackets are required, and any codes substituted for them won't do. Thus the substitution of entities for characters neutralizes the tags, so no HTML can function in the forum. (GBO also uses the same technique to prevent HTML from working in PMs and whiteboards.)

Appendix 2 - Insert Link feature maximum field sizes allowed

The maximum size of a link's URL, including the protocol indicator (http://) is dependent on several factors that are difficult to determine by experimentation. The following is known:

• The limit is affected by a combination of the URL length and the link text length.
• A combined limit of 97 characters exists if both the URL length and the link text length are both less than 85 characters each.
• A combined limit of 84 characters exists if either the URL length or the link text length are more than 84 characters long.
• The length of the URL is seemingly unlimited if broken up by certain characters, e.g. forward slashes. (This is currently being researched.)

If the limit is exceeded, some portion of the URL and link text will be discarded and the following magically-mangled markup mess will be materialize in the finished message:

Example 30:     [L=http://someURL/text deleted/L]

Notice that two of the square brackets normally present in the GBO custom tag have been deleted. This is overkill, because the formation of a useable link has already be prevented. Upon posting, if your link looks like the above, you have no choice but to edit the message within the five-minute editing window and substitute fewer characters to obtain an acceptable-length link. It is easier to be aware of the limit, use testing to see if it will be violated and take corrective measures before posting the final message.

Appendix 3 - GBO URL structure

Typically, in GBO forum URLs, all material to the right of the topic number is used for GBO housekeeping and reader navigation and may be deleted without detriment when used in links; the topic parameter alone will get to the topic. FYI: Regardless of which parameters they are, it is the nature of the .ASPX language that the first parameter in a URL must be preceded by a question mark (?) and all following parameters must be preceded by an ampersand (&). Keep this in mind if you shorten a URL by deleting one or more parameters. But, as a rule, all GBO URLs of any length generated by the system should be accepted and not require shortening. Some GBO URLs are known to require the presence of more than one parameter—some photo album URLs for example—so if you choose to prune GBO URLs, testing may be in order to make sure they still work properly.

Appendix 4 - Do you need WWW in a URL?

WWW is the subdomain name for the World Wide Web. http://www.somesite.com and http://somesite.com are two different addresses. Most Websites are configured to treat these exactly the same and so an address will function properly either way. However, some Websites will intentionally have separate uses for addresses with and without WWW, in which case whether or not WWW is present in the address matters. Rarely, a Website that has no reason to require WWW is simply misconfigured and so fails to work. In that case, you must include it (unless you can convince the operators to correct the error and then wait for the correction to filter through the Internet). To sum up, be sure to test the address first if you intend to omit the subdomain name to shorten a URL.

Notes

Version: 20161105 2:18 PM PDT --CampKohler
Backup: 20161105 --CampKohler

Top Return to Guides Index.