MediaWiki

Extension:TopicTags

(page under construction)

Proposed Extension

edit

This proposed extension provides inline topic-tags, which are completely independent of Categories. Wiki editors can insert topic-tags inline anyplace on a wikipage.

This page describes a working demo, built by cobbling together existing extensions.

Under Development: This page is under development, and may contain errors or omissions.

Introduction

edit
Inline Tags

This proposed 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. A link to a TopicTag will scroll the browser directly to the TopicTag 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

edit

TopicTags helps fill in a bit more of the original proposal, and also takes the same basic concept of section tagging in a new direction.

Where the original Dovi proposal viewed transclusion as the only function of region-marking, TopicTags envisions marked regions as having additional features.

  • Marked Region: Transclusion (LST) 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.
  • Cross Referencing: Unlike LST, TopicTags relates marked regions to each other by tag-name. This creates opportunities for cross-referencing tagged regions.
  • Region Transclusion: Where LST only transcludes sections from a single page, TopicTags transcludes regions from pages throughout the wiki.


Neither LST nor DPL 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?

edit
  • 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 TopicTag on a page are anchored directly to the tag-location, within the body-text-- the visitor's browser scrolls directly to that location.
  • TopicTags are intended to provide a finer-grained taxonomy than Categories. TopicTags are a lower-level taxonomy than Categories.
  • Where wiki curators may use Categories as a hierarchical organizing system, TopicTags are always non-hierarchical.

Topic-tags should never appear in CategoryTrees or category lists. We don't want Categories to interfere with, or be interefered with by, these TopicTags.

Pedigree

edit

Labeled section transclusion

edit

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

edit

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

edit

Functionally, the current prototype does nearly everything i want for a first-release, in terms of user-experience and behaviors.

Appearance

edit

TopicTags have 2 formats:

  • Inline, where the TopicTag is associated with a specific location on a page.
  • Page-level, where the TopicTag is associated with an entire page.

TopicTag Info Pages:

  • For each unique tag-name, there's a TopicTag 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

edit

An inline TopicTag 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.

 
Tagged region on hover tagname

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

Page Tags

edit

A page TopicTag 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.

 
Page-level Tag

Tag Page

edit

For each tag, there's a TopicTag Info Page, containing a description of the tag, and a list of all pages tagged with that tag-name.

 
Tag Page

Tags Page

edit

A list of all tags used in the wiki. Clicking any TopicTag on the Tags page will direct the browser to description-page for that TopicTag.

 
Tags Page

Usage

edit

Reading

edit

Hovering Inline Tags

edit

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

edit

Click a tag-link to be directed to the Tag-Page.

Clicking a related-page link

edit

Click a related-page link to be directed to a related wiki-page:

  • Key feature: If the TopicTag is inline on the related wiki-page, the browser will be scrolled to the specific tagged location in the body text.
  • If the TopicTag is page-level TopicTag on the related wiki-page, the reader will be directed to the top of the tagged page.

Inserting Tags

edit

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

edit

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

The sky is blue, and the earth is brown. {{Tag|Green}} Many things are green, like grass and money.{{EndTag}} Wild dogs roam the land.

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

{{Tag|CommonGround}} The sky is blue, and the earth is brown. Many things are green, like grass and money. Wild dogs roam the land.

Nested tags

edit

Nested tags are allowed. Eg: 

{{Tag|Cars}}It was a roadster. 
     {{Tag|Pie}}There were three pies in the trunk.{{EndTag}} 
     {{Tag|Cake}}The purple roadster had cakes in it's trunk.{{EndTag}} 
{{EndTag}}

Page Tags

edit

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:

{{Tag|CommonGround|}}

Creating a TopicTag Description

edit

The TopicTag Description can be edited only by members of the Admins and Curators groups. Manually creating a description isn't required. You can insert a new TopicTag into an article, and it will work immediately.

If you want to add a description to the TopicTag page:

  1. Browse to the TopicTag Page for the desired tag: index.php/Tag?Tag=Puppies
  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

edit

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.

  1. Install all #Dependencies
  2. Create the #Extension Pages.

Done.

Dependencies

edit

Extension Pages

edit

To create these pages, you need only to paste in the wikitext provided at the links below:

Implementation

edit

Simple, Yet Complicated

edit

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.

Secret Sauce

edit

Anchors

edit

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: 

<span id=Tag:Purple>

Template:Pin simplifies creation of anchors.

List Editor

edit

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.

#Creating_a_Tag_Description

I hope to make this feature a separate extension.

Template:Tag

edit

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: 

{{Tag|CommonGround}}

creates an HTML anchor on the host page. The rendered HTML looks like: 

<span id="Tag:CommonGround"><small><sup><a href="/index.php/Template:Tag?Tag=CommonGround">CommonGround</a></sup></small>

This page-level tag-code, with trailing pipe, 

{{Tag|CommonGround|}}

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>
</p>
<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 TopicTag appears.

Visible TopicTag Page

edit

When a tag-name is clicked in a tagged wiki-page, user is directed to visible page "Tag". TopicTag 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 TopicTag 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

edit

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

What this fixes

edit

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

edit

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

Rendered HTML

edit

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

Flaws

edit

Tagged region can't overlap paragraph breaks. But i think that's not a blocker-- most tagging will be within a paragraph. Inability to overlap paragraph breaks is an undesirable but acceptable limitation.

Tag Descriptions

edit

Tag Descriptions Page

edit

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

Tag Page

edit

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

DPL Format

edit

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: 

[[page_name#anchor_name|display_as]]

(actually, i think we're currently doing it with html "a" TopicTag 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%#Tag:{{#urlget:Tag}}|%PAGE%]],,

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

Release Version

edit

Must-haves before publishing this extension:

Solve

edit

Solve all high-risk, high-impact issues.

Reduce dependencies

edit
  • 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

edit

"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 Template:Tag

edit

Risk: Low

Impact: High

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

Fix: Call it TopicTag instead of Tag.

edit

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

edit

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

edit

Templates

edit

It's been recommended to implement this entire TopicTags system using native Templates. A simple native solution is more stable and future-proof, so if all the current features can be achieved with Templates and other native MW features, that would be better than using extensions. If enhancements listed on this page can be implemented with Templates, even better.

Native implementation should be wrapped in a native abstraction layer, to automate insertion of tags in the visual editor, automatic creation of meta-pages, and automated front-end behavior and rendering.

Here's are notes and code-sample donated to this project by Want:

Use templates for similary purposes. It's more variable. You can use name of the tag as first argument, and content as second. It's native transclusion function of the mediawiki. For example I use templates: do, done and substitution template TODO (where is documented using of this) for ToDo specify.

https://www.thewoodcraft.org/wiki/index.php/Template:TODO

By extension (DPL) I solve only generating list of the actually actived ToDo's from instances of the templates contents, see here:

https://www.thewoodcraft.org/wiki/index.php/Kategorie:ToDo

You want use tag as target? With the template isn't problem. I use it here:

https://www.thewoodcraft.org/wiki/index.php/Warren,_1853/_D%C4%9Bjiny_Od%C5%BEibvej%C5%AF

But it's more sofisticated code for editors, because must be specified WHAT is part of the paragraph for concretly the subtitle. But principle is same. The point is that when the template is terminated incorrectly, it is immediately obvious that there is an error in the code, but the missing termination of the element (tag) on the page can be interpreted in different ways. Write own extension doesn't make sense, because the MediaWiki core constantly changing, and if will be replaced any functions by anothers, you'll have to find someone to fix. This no danger with templates.

Your example solved by template

Code of this page:

--VV--

{{Tag|Cars|It was a roadster.

      {{Tag|Pie|There were three pies in the trunk.}}

      {{Tag|Cake|The purple roadster had cakes in it's trunk.}}

}}

--AA--

Code template Tag:

--VV--

{{na|{{{1}}}}}{{{2}}}

--AA--

Code template na:

--VV--

<includeonly><span id="{{{1}}}"></span></includeonly>

--AA--

And html source of the interpreted page:

--VV--

<div class="mw-parser-output"><p><span id="Cars"></span>It was a roadster.

</p>

<pre>    <span id="Pie"></span>There were three pies in the trunk.

     <span id="Cake"></span>The purple roadster had cakes in it's trunk.

</pre>

</div>

--AA--

And sample of the code for DPL for Tag template, which can be parametrized:

--VV--

<DPL>

uses  = Template:Tag

include  = {Tag}:1,{Tag}:2

nottitlematch = TODO|TODO/doc|+

table    = class="wikitable sortable",,Target Name,Content

tablerow

=align=left|%%,bgcolor=lightyellow|%%,align=right|<small>%%</small>,\n|align=right|%%

</DPL>

--AA--


Syntax

edit

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? Should TopicTags use LST <> syntax, instead of double-curlies? Can TopicTags be separate but compatible?

Should we break down TopicTags functionality into more extensions/gadgets/widgets, that admins can mix and match? That would keep things leaner, and cut out what we 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. But, interdependency carries the risk that changes to one part could break things.

If TopicTags is just the first of a family of intelligent-text extensions, then it could be advantageous to use a syntax that lends itself to a variety of smart-text applications, beyond TopicTags.

Possible modules

edit
  • Marking text
  • Sharing
  • Related-page list
  • All tags list
  • Description maintenance
  • Transclusion
  • Inline features-- labeling, highlighting, popup menu

Popups

edit

Inline Tags

edit

On hover, show info and click-features, such as TopicTag Description, Share, etc

edit

On hover, show first X characters of tagged text

Tags List

edit

On hover, show info such as TopicTag description, # pages tagged, etc

Sharing

edit

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

edit

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.

Example of overlapping topicTags:

{{TopicTag|Cats}}Some content about cats. {{TopicTag|Tigers}}Content about all cats, including tigers. {{EndTopicTag|Cats}}Content about tigers which doesn't apply to other cats.{{EndTopicTag|Tigers}}

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.

If possible, it would improve ease of use if both ambiguous and non-ambiguous tags are supported.

List Editor Improvements

edit
  • 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.
  • Support Enter key to save.

Rights

edit
  • 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

edit

Easier way to add multiple page-level tags. Eg

{{Tags|Green, Blue, Yellow|}}

Automatically get "Related Pages" section-header.

Selective Page-Tag Label

edit

Only show "Also tagged" label if any other pages with same TopicTag exist. Else just show tag-name.

Stats

edit

Would be cool to display usage stats, click stats, sharing stats, and other info about the TopicTag on the TopicTag page.

Full Excerpts

edit

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 TopicTag more than once. Would have to mod other DPL, for Portal:Tags, since that lists each TopicTag each time it appears on a page.

Rename Tags, Merge Tags

edit

Global renames, merging, etc.

Config Options

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

Toolbar

edit

Topic:Ucx3870iubclp1i7

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:TopicTags&oldid=6503343"