Extension:TopicTags

Under Development

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

This page is 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.

One of the new, key features of these topic-tags, is they can be scoped to specific locations within the body of a page. They are not just page-level tags. Links to those tags will scroll the browser directly to the tag location in the body text, instead of just to the top of the page.

Demo here: https://gunretort.xyz/index.php/Portal:Tags

This project represents a continuation and expansion of a concept for section-transclusion, proposed in 2006 by User:Dovi et al.

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

Advantages of TopicTags
(section under construction)

TopicTags takes the same basic concept of section tagging in a new direction.

Where the original proposal viewed transclusion as the only function of region-marking, TopicTags envisions marked regions as having additional features uses.
 * Transclusion is all about how the marked region looks on some other page. TopicTags, on the other hand, are concerned with how the marked-region looks in it's original page, in situ. Unlike LST, which provides no visible indication on the source page that a section of text is marked, TopicTags provides visual cues to the reader, such as labeling and highlighting.
 * Unlike LST, TopicTags relates marked regions to each other by tag-name. This creates opportunities for cross-referencing tagged regions.

region transclusion, which TopicTags will soon have via DPL. But, where LST only transcludes sections from a single page, TopicTags transcludes regions from pages throughout the wiki.

Now, TopicTags extension helps fill in a bit more of the original proposal, and also covers ground in new directions. TopicTags introduces some new user-interface features not considered by USERS, including FEATURES. 

But neither provide these TopicTags benefits:


 * Anchors
 * Inline labels
 * Highlighting
 * Relating page-sections by tag-name (DPL3 might)
 * Tag Information pages
 * Tag descriptions
 * Description editor widget

Why Not Use Categories?

 * Category scope is limited to the page-level. TopicTags can pinpoint specific text-regions within the page. Categories can't do that.
 * Links to a tag on a page are anchored directly to the tag-location, within the body-text-- the visitor's browser scrolls directly to that location.
 * We don't want Categories to interfere with, or be interefered with by, these TopicTags. Topic-tags should never appear in CategoryTrees or category lists.
 * TopicTags are intended to provide a finer-grained taxonomy than Categories.
 * Where wiki curators may use Categories as a hierarchical organizing system, TopicTags are always non-hierarchical.

Labeled section transclusion
The 2006 proposal was to mark off a region of text in an article only for the purpose of transcluding that region elsewhere.

Extension:Labeled_Section_Transclusion
Extension:Labeled_Section_Transclusion (LST) fulfilled the essential requirement of the proposal, to label and transclude a section of text. Of note, LST supports overlapping regions.

Feature-Complete
Functionally, the current implementation does just about everything i want for a first-release, in terms of user-experience and behaviors.

=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.

Pages:


 * For each unique tag-name, there's a Tag Page, containing a description of the tag, and a list of all pages containing the tag.
 * Also available is a public page listing all tags used in the wiki.

Inline Tags
An inline tag appears as a very small, super-script text-link. The font is extra-small, to differentiate from other common superscript text.

When clicked, reader is directed to the Tag-Page. (see image, above). The browser will be scrolled to the specific tagged location in the body text.

When user hovers mouse over tag-name, the entire tagged-region will get highlighted.



Hovering over the tagged-region itself will not get highlight.

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 Page
For each tag, there's a Tag Page, containing a description of the tag, and a list of all pages tagged with that tag-name.

Tags Page
A list of all tags used in the wiki.

=Usage=

Hovering Inline Tags
When user hovers mouse over tag-name, the entire tagged-region will get highlighted.

Hovering over the tagged-region itself will not get highlight.

Clicking the tag-name in a tagged article
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:
 * Key feature: If the tag is inline on the related wiki-page, the browser will be scrolled 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.

Inserting Tags
Tagging syntax was designed to be as simple as possible. 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 insert an inline tag. Displays as a small superscript in the article, with NO list of related articles.

The EndTag is optional. If ommitted, the tagged region will end at the end of the current paragraph: 

Nested tags
Nested tags are allowed. Eg: It was a roadster. There were three pies in the trunk. The purple roadster had cakes in it's trunk.

Page Tags
Use the following syntax to insert a page-level tag. Intended to be inserted at bottom-of-article. Displays normal-size bold, with list of related articles: 

Creating a Tag Description
The Tag Description can be edited by members of the Admins and Curators groups. This step isn't required. You can insert a new tag into an article, and it will still work immediately.

But, if you want to create a new tag-description:
 * 1) Browse to the Tag Page for the desired tag:
 * 2) Click the empty description box to start edit-mode.
 * 3) Enter new tag-description, and click "Save".

Existing descriptions can be edited the same way.



=Installation= 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.

Done.
 * 1) Install all
 * 2) Create the.

Dependencies

 * Extension:Page_Forms
 * Extension:UrlGetParameters
 * Extension:DynamicPageList3
 * Extension:HTML_Tags
 * Extension:Labeled Section Transclusion
 * Extension:Arrays
 * Extension:ParserFunctions

Extension Pages
To create these pages, you need only to paste in the wikitext provided at the links below:
 * /Form-CreateTag
 * /Template-Tag
 * /Template-Tag/Preload
 * /Template-TagDPL
 * /Template-TagLink
 * /Page-Tag
 * /Page-Tags
 * /Template-EndTag
 * /CSS-Common.css
 * /JS-Common.js
 * /Template-Span

=Implementation=

Simple, Yet Complicated
This extension does something pretty simple. I think it's features ought to be handled by MW core. But due to limitations of MediaWiki, the implementation is more complicated than i would like. To achieve it's simple goals requires some funky workarounds, and depends on at least six different extensions.

Still, it's pretty simple. There's no php (yet), and very little wiki-text. It's not at all large (not counting the needed extensions). I try to separate functional blocks into different pages, for clearer understanding and easier maintenance/upgrades.

Anchors
Inline tags render as an HTML-anchor. That's the secret sauce that makes it possible to link directly to the tag-location in the body of the wiki-page. anchors.

Inline tags will render HTML like this: Template:Pin simplifies creation of anchors.

List Editor
This extension includes a feature i've not seen anywhere else, yet: the ability to add/edit items in a list which is maintained on a wikipage. Edits are performed using an editable textbox that can be placed on any wikipage.

Tag descriptions are all stored in a single page (instead of creating a separate hard-wired page for each tag-description). That makes it possible to dynamically generate the visible, tag-specific information page.



I hope to make this feature a separate extension.

Template:Tag
Through Transclusion, Template:Tag renders clickable HTML-links in tagged host-pages.

Inserted Topic-Tags are transclusions. When a host wiki-page contains the tag-code for Tag:Purple, it passes the tag-name, as a wiki-parameter, by nested transclusion, 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:  creates an HTML anchor on the host page. The rendered HTML looks like: CommonGround This page-level tag-code, with trailing pipe,  produces a list of related pages. That enables the user to jump directly to any related page: <a href="/index.php/Template:Tag?Tag=CommonGround">Tag:CommonGround</a></b> <ul> <li> <a href="/index.php/Portal:Welcome#Tag:CommonGround">Portal:Welcome</a></li> <li> <a href="/index.php/Openers#Tag:CommonGround">Openers</a></li> <li> <a href="/index.php/Draft:blame_guns.#Tag:CommonGround">Draft:blame guns.</a></li> <li> <a href="/index.php/homicide_rate.#Tag:CommonGround">homicide rate.</a></li> </ul>

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.

Visible Tag Page
When a tag-name is clicked in a tagged wiki-page, user is directed to visible page "Tag". Tag displays the tag-description and list of related pages.

Individual tag-pages are dynamically generated on the fly, for each tag-name. There's only one visible Tag page, which serves all tag-names. A Url parameter is used to pass the tag-name into page Tag. That's the purpose of Extension:UrlGetParameters.

It would be better, more MediaWiki-ish, if MediaWiki supported page-parameters. Then we could do everything in wikitext, instead of mingling wikitext with HTML. But that was rejected by admins.

Region-tagging
Enables editor to apply a topic-tag to a  region  of text.

What this fixes
Shows the reader exactly which region of text is being tagged.

IMO, both addressable regions and pin-points should be considered core MW concept. Where Semantic Wiki datafies at the page-level, i'm proposing datafication at the level of text and character-position.

Implementation: Template:Span
Uses Template:Span. renders HTML on the host-page.

Rendered HTML
HTML-ID for anchor, HTML-Class for hover-CSS, CSS for highlight on hover.

Flaws
Tagged region can't overlap paragraph breaks. But i think that's not a blocker-- most tagging will be within a paragraph.

Tag Descriptions Page
Tag Descriptions Page is a list of all tag-descriptions. When visible page Tag is viewed for a particular tag, the tag-description is pulled from Tag Descriptions Page. This is done with Extension:Labeled_Section_Transclusion.

Tag Page
Descriptions are added/edited using the visible Tag Page. That's done with a contentEditable div and javascript.

DPL Format
The DPL3 format syntax is: | format=Startall,Start,End,Endall

In our DPL statement, the commas are placeholders for each format-section (Startall,Start,End,Endall).

In this extension, only one format-section has formatting: the Start section. Start represents the beginning of each article in the list.

The star resolves to a bullet in the output.

https://help.gamepedia.com/DPL:Parameters:_Controlling_Output_Format#format

To ensure links in the list go to those inline anchors, DPL must include pound-anchor in the links it outputs for found pages. Must output wikitext syntax for anchors: display_as (actually, i think we're currently doing it with html "a" tag and url-params. Should change to wikitext style, if possible).

https://meta.wikimedia.org/wiki/Help:Anchors

DPL format is newline + found-page name linked to tag-anchor on found-page | format  = ,\n* %PAGE%,,

Note, if users use same tag in multiple locations on the page, then DPL anchor-links will go to the FIRST tag on the page.

=Release Version= Must-haves before publishing this extension:
 * Resolve one high-risk, high-impact issue.

Solve
Solve all high-risk, high-impact issues.

Reduce dependencies

 * That would simplify installation and reduce footprint. But might not be possible, without writing some custom PHP.
 * Maybe we can bundle the dependencies into one installer.
 * Personal opinion: 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. But there are holes in MediaWiki core.
 * Extension:UrlGetParameters: Could be eliminated if MW supported page-parameters. But, feature rejected: https://phabricator.wikimedia.org/T194571

=Known Issues= "Risk" as used here means "likelihood of occurring."

"Impact" as used here means "how bad is it, if it happens."

Top-priority should be given to items which are both high-risk and high-impact.

(Priority shall not be based on whether or not someone volunteered to work on it. In software dev, that's an invalid definition of "Priority".)

Conflict with
Risk: Low

Impact: High

is not part of mediawiki core, but it is used on mediawiki.org. This extension can't be used on wikis that use.

Fix: Use TopicTag instead of Tag.

Caching causes delays in updating related pages list displayed in transcludes.
Risk: high

Impact: high

As with some other extensions (e.g. 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:
 * Added __NOCACHE__ to all extension templates. That seems to have improved things somewhat. Extension:MagicNoCache
 * 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?
 * Find wikitext or extension to purge page by name or ID. Then, in Template:Tag, put wikitext to purge all related pages.
 * Problem: May purge every time new page is displayed, not just when tagged.

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

Inline tags break if included in an unrelated DPL
Risk: low

Impact: high

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.

(need to confirm, might be working now)

=Future Enhancements=

Merge/Fork?
TopicTags depends on LST and DPL. Going forward, syntax and some features should be made consistent. Which extension should be the model for the others? TopicTags? DPL? Or Labeled Section Transclusion? Which syntax to use? Switch to LST  syntax? Be separate but compatible?

My favorite is: break down into more extensions/gadgets/widgets, that admins can mix and match. Keeps things leaner, cut out what you don't need. Then no one extension gets too top-heavy, or too insular. This arrangement demands interoperability, which is a darn good thing for MediaWiki.

Possible modules:
 * Marking text
 * Sharing
 * Related-page list
 * All tags list
 * Description maintenance
 * Transclusion
 * Inline features-- labeling, highlighting, popup menu

Inline Tags
On hover, show info and click-features, such as Tag Description, Share, etc

Related Pages
On hover, show first X characters of tagged text

Tags List
On hover, show info such as Tag description, # pages tagged, etc

Sharing
On hover, reveal a "share" option on marked text, to share the region by email, copy link, or post it to social media. The shared text will link back to its exact location in the source page.

Overlapping Regions
It would be useful to allow overlapping regions. That means can't have ambiguous closing tags. Might also mean can't use standard HTML tags.

Some ideas:


 * Use non-html tags in the rendered doc. Then, on hover, convert the hovered tags into HTML tags for the purpose of highlighting.
 * Performance could be an issue.
 * Could use <> tags same as Extension:Labeled Section Transclusion. That might help combine the extensions.



List Editor Improvements

 * Hide box until user clicks on description.
 * Disable Save button until user changes something. Use MediaWiki-style flat-blue button.
 * Display 'Click to edit' on the far lower-right, for Curators and higher only.

Rights

 * Disable editing interface for users who don't have edit-rights to the list.
 * Different groups for different lists. Based on protection-settings of target namespace for now.
 * Can differ from list to list.

Bulk Page Tags
Easier way to add multiple page-level tags. Eg. Automatically get "Related Pages" section-header.

Selective Page-Tag Label
Only show "Also tagged" label if any other pages with same tag exist. Else just show tag-name.

Stats
Would be cool to display usage stats, click stats, and other info about the tag on the Tag page.

Full Excerpts
On Tag-page, use DPL to dynamically render all tagged-regions. Use CSS to collapse the excerpts, expandable on click.

This could be an issue where same page contains same tag more than once. Would have to mod other DPL, for Portal:Tags, since that lists each tag each time it appears on a page.

Rename Tags, Merge Tags
Global renames, merging, etc.

Config Options

 * Label color
 * Enable/disable highlighting
 * Highlight style/color
 * Background color
 * Dotted underline
 * Hotspot footprint size

Toolbar

 * Put TopicTag button on WikiEditor toolbar https://www.mediawiki.org/wiki/Extension:MsWikiEditor
 * Auto-insert  at end of selected text.

=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.

Topic:Ucx3870iubclp1i7