Extension:TopicTags

Under Development

This works if installed as directed. But seeking feedback and improvements before release.

This page is also under development, and may contain errors or omissions.

=Introduction= This extension provides inline topic-tags, which are completely independent of Categories. Wiki editors can insert topic-tags inline anyplace on a wikipage. The new, unique feature of these topic-tags, is they are not just page-level tags. They can be scoped to specific locations within the body of a page.

Secret Sauce: Anchors
The secret sauce is anchors. Inline tags render as an HTML-anchor-- that makes it possible to link directly to the tag-location in the body of the wiki-page.

(Note this extension is unrelated to MediaWiki edit-tags)

=Appearance= Topic-tags have 2 formats:
 * Inline, where the tag is associated with a specific location on a page.
 * Page-level, where the tag is associated with an entire page.

For each tag, there's a Tag Page, containing a description of the tag, and a list of all pages containing the tag.

Inline Tags
An inline tag appears as a very small, super-script text-link. When clicked, reader is directed to the Tag-Page.

Page Tags
A page tag appears at the bottom of the page in full-size text. Also displayed are "Related Pages": a list of links to all other pages containing the same tag.

Tag Pages
For each tag, there's a Tag Page, containing a description of the tag, and a list of all pages containing the tag.

=Operation=

Clicking the tag-name in a tagged article
Test Click a tag-link to be directed to the Tag-Page.

Clicking a related-page link
Click a related-page link to be directed to a related wiki-page:
 * If the tag is inline on the related wiki-page, the reader will be directed to the specific tagged location in the body text.
 * If the tag is page-level tag on the related wiki-page, the reader will be directed to the top of the tagged page.

Creating Tags
To create a new tag:
 * 1) Browse to YOUR-WIKI-URL/Form:Tag
 * 2) Enter tag-name, and click "Create tag".
 * 3) Enter tag-description, and click "Save page".

Inserting Tags
Two topic-tag formats can be used in articles. The only difference is the trailing pipe | character. A tag-name may not contain an embedded space.

Inline Tags
Use the following syntax to create an inline tag. Displays as a small superscript in the article, with NO list of related articles. : 

Page Tags
Use the following syntax to create a page-level tag. Intended for bottom-of-article tags. Displays normal-size bold, with list of related articles: 

=Installation=


 * 1) Install all
 * 2) Create the following wikipages. You need only to paste in the wikitext provided at the links below:
 * 3) New-Tag Form
 * 4) Tag Template
 * 5) Tag-list
 * 6) /Template-Tag/Preload

=Dependencies= Extension:Page_Forms

Extension:UrlGetParameters

Extension:DynamicPageList3

Extension:HTML_Tags

Extension:Labeled Section Transclusion

=Implementation= The current version of this extension is php-free, and can be installed manually. FTP is needed to install the depended-extensions, but not needed to install any part of this extension.

A topic tag is a tranclusion of the Template:Tag page 

The transclusion creates a link in the host to Template:Tag. In other words, Template:Tag creates a link to itself. Here's the html transcluded onto the host-page: Tag:CommonGround

When that link is clicked, the tag-name is passed into Template:Tag as a ''url-parameter. ''

When visitor clicks a tag-name in a tagged page, they're first directed to

Template:Tag has multiple functions:
 * When a tag-name is clicked in a tagged wiki-page, user is directed to the page named for that tag Template:Tag. Template:Tag directly displays tag-description and list of related pages. A Url parameter is used to pass the tag-name into the Template. That's the purpose of Extension:UrlGetParameters. Viewing a Template is atypical in MediaWiki, but works well for this purpose.

 '''creates an HTML anchor on the host page. That anchor is the secret to inline-tags. '''The rendered HTML look like: CommonGround This page-level tag-code:  produces a list of related pages. That enables the user to jump directly to any related page: Tag:CommonGround</b> <ul><li> Portal:Welcome</a></li> <li> Openers</a></li> <li> Draft:You can't blame guns for socioeconomic problems.</a></li> <li> The U.S. does NOT have the world highest gun-homicide rate.</a></li></ul>
 * Inserted Topic-Tags are transclusions. When a host wiki-page contains the tag-code for Template:Tag, it passes a wiki-parameter to Template:Tag. This enables Template:Tag to return HTML to be rendered on the host page. For example, this inline tag-code on a wiki-page:

Notice the string "#Tag:" in each related-page link. That causes the link to go directly to the anchor-location in the body-text where the tag appears.

Tag Pages
Individual tag-pages exist for each tag-name, but the reader never sees them. They can be in a hidden namespace. The only function of the individual tag-pages is to store the tag-descriptions. When Template:Tag is viewed for a particular tag, the tag-description is pulled from the individual tag-page.

=Known Issues=

Caching delays updates of related pages displayed in transcludes.
As with some other extensions (eg Extension:CategoryTree, caching can muck things up. Still haven't found a solution for this. This only affects the related-pages list displayed on page-level tags, on the tagged page. Does not affect the list displayed in Template:Tag. Possible solutions:
 * Hmm-- how to prevent a transclusion from getting cached, even while the page that hosts it does get cached?
 * Or-- how to force a transclusion to refresh on page-load?
 * Or-- does MediaWiki support partial-page caching?
 * Or partial-page refreshes?

I believe some extensions (maybe even core) do some ajaxy stuff. If MW can't do this, it should :)

Inline tag links incorrectly wherever the inline-tag get included in an unrelated DPL
If some unrelated page contains a DPL list, which in-turn includes text which contains a topic-tag, when clicked that topic-tag will not correctly link to Template:Tag.

Breaks if non-existent tag inserted.
Possible solutions:
 * Auto-create tag page when tag is clicked. Since tag links to Template:Tag, then Template:Tag would have to execute code to the create page.
 * Eliminate tag-pages.
 * Eliminate tag-descriptions.

Tag-links on Tags page open in new window
The Tags page contains a list of all topic-tags in the wiki. When any tags in the list are clicked, user is directed to the tagged-pages list for that tag. Problem is, it opens in a new window.

Possible solutions:

=Release Version= I hope to achieve the following before publishing this extension:

Eliminate individual tag pages
Rationale: To allow tags to be auto-created the instant they are used. Currently, the NewTag form must be used to create a new tag.

Blocker: The pipe
To eliminate tag-pages, we'd want to transclude Template:Tag for all embedded-tags. Eg., <Green ></Green> instead of <undefined ></undefined>. For that to work, DPL (or API) would have to be able to tell the difference between <Green ></Green> and <Blue ></Blue> But DPL cannot tell the difference. It will count both as the same transclusion. DPL can't tell the difference, because DPL cannot see pipes. It can only find static pages. The tags inserted must transclude a specific page for DPL to find them (eg, <undefined ></undefined>. It can only tell the difference between <undefined ></undefined> and <undefined ></undefined> . So far, the MW API struggles with the pipe as well. No solution to this yet.
 * https://www.mediawiki.org/wiki/Topic:Ucmsdl9osvcbes0l
 * https://phabricator.wikimedia.org/T194039

Progress
We're partway there, as currently related-page lists are created dynamically-- they are all a direct display of the Template:Tag page, using URL-parameters to pass the tag-name to the Template.

Benefits
This has the side benefit of eliminate the Page_Forms dependency and maybe others.

Storing Descriptions

 * Currently, one purpose for tag-pages is to store tag-descriptions. To eliminate individual tag pages, we must find a way to store all tag-descriptions in a db table or a single wikipage. How to save a list of tag-descriptions in a single table or wiki-page? Some possible or rejected solutions:
 * Extension:Cargo: Rejected: Cargo is not appropriate for arbitrarily storing/retrieving individual records from a list.
 * Extension:ExternalData: Could be used to retrieve descriptions, but does not seem to offer a way to store individual records in a table or list. SemantcWiki is suggested
 * Extension:DataTable2: Unknown if feasible:
 * https://www.mediawiki.org/wiki/Topic:Udh53bn9qmovy1xd
 * https://www.mediawiki.org/wiki/Topic:Ud1kiswqh0cc1zsy
 * Custom PHP. But, to maintain our "php-free" goal, i'd make that a general purpose data-storage extension, separate from TopicTags.
 * No descriptions: A simple solution would be to eliminate tag-descriptions. That would eliminate individual tag-pages and the Page_Forms dependency. For a first release, that might be a good option. In fact, a required option, if i can't find a code-free way to store/retrieve descriptions. However, that won't fix the pipe issue. And in long-run, descriptions seem an essential feature for Topic-Tags.

Solve

 * caching issues.
 * New-window issue.

Reduce dependencies
That would simplify installation and reduce footprint. Personally, i believe everything this extension does should be doable without any extensions. I feel all behaviors are things that should be part of the MW core-- this extension isn't really doing anything groundbreaking. It all seems very consistent with core MW features.
 * Extension:UrlGetParameters: Could be eliminated if MW supported page-parameters. Feature rejected: https://phabricator.wikimedia.org/T194571

=Future Enhancements=
 * Stats: Would be cool to display usage stats, click stats, and other info about the tag on the Tag page.
 * There might be advantages to using separate tag-pages, as those pages might display statistics or other data more easily than the current dynamic template. Therefor, this can remain an option.

=PHP-Free Experiment= This project is an exploration into the feasibility of php-free extensions, which could be created by non-php programmers, using only wikitext.

Tentatively called "PHP-Free Extensions". A shorter name would be preferrable. Maybe "miniExt", "freelette", "pluglette", etc.

To facilitate non-programmer publishing of php-free extensions, there could be a generic installer, which registers the extension and creates needed pages.. Creation of extension pages could be automated with an API Import action.

Or, even better, the extension pages could themselves transclude model-pages from an external server, enabling extension developers to instantly roll-out improvements to any wiki which uses this extension.