View source for Extension:TopicTags

<big><big>''(page under construction)''</big></big>

== Proposed Extension ==

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==
[[File:TopicTags inline tag.png|thumb|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.'' Links to those tags 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 [[#Pedigree|'''expansion''']] of a concept for section-transclusion, '''[https://en.wikisource.org/w/index.php?title=Wikisource:Labeled_section_transclusion&oldid=247062 proposed in 2006]''' by [https://en.wikisource.org/wiki/User:Dovi User:Dovi] et al. 

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

== Advantages of TopicTags ==
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.
* <u>Marked Region</u>: 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. 
* <u>Cross Referencing</u>: Unlike LST, TopicTags relates marked regions to each other by tag-name. This creates opportunities for cross-referencing tagged regions. 
*<u>Region Transclusion</u>: 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?==
* 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 ==
=== Labeled section transclusion ===
The '''[https://en.wikisource.org/w/index.php?title=Wikisource:Labeled_section_transclusion&oldid=247062 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 prototype does nearly everything i want ''for a first-release, ''in terms of user-experience and behaviors.

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

[[File:Tag-hover.png|none|thumb|Tagged region on hover tagname]]

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

==Page Tags==
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.
[[File:TopicTags page-level tag.png|none|thumb|Page-level Tag]]

==Tag Page==
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.
[[File:TopicTags tag page.png|none|thumb|Tag Page]]

==Tags Page==
A list of all tags used in the wiki. 
[[File:Tags Page.png|none|thumb|Tags Page]]

=Usage=
==Reading==
=== 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_Pages|Tag-Page]].

===Clicking a related-page link===
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==
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. 

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

The EndTag is optional. If omitted, the tagged region will end at the end of the current paragraph:
<pre>{{Tag|CommonGround}} The sky is blue, and the earth is brown. Many things are green, like grass and money. Wild dogs roam the land.</pre>

==== Nested tags ====
Nested tags are allowed. Eg: <pre>
{{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}}
</pre>

===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:<pre>{{Tag|CommonGround|}}</pre>

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

But, if you want to create a new tag-description:
# Browse to the TopicTag Page for the desired tag: <code>index.php/Tag?Tag=Puppies</code>
# Click the empty description box to start edit-mode.
# Enter new tag-description, and click "Save".

Existing descriptions can be edited the same way.

[[File:TopicTags description edit-mode.png|none|thumb]]

=Installation=
The current version of this extension is '''[[#PHP-Free_Experiment|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. 

# Install all [[#Dependencies]]
# Create the [[#Extension Pages]]. 
Done.

==Dependencies==
* [[Extension:Page_Forms]]
* [[Extension:UrlGetParameters]]
* [[Extension:DynamicPageList3]] (Does not work for MediaWiki 1.31)
* [[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 [[#Dependencies|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==
=== 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. 
[https://meta.wikimedia.org/wiki/Help:Anchors anchors]. 

Inline tags will render HTML like this:

<syntaxhighlight lang=html>
<span id=Tag:Purple>
</syntaxhighlight>

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. 

[[#Creating_a_Tag_Description]]

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:
<pre>{{Tag|CommonGround}}</pre>
creates an HTML anchor on the host page. The rendered HTML looks like:

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

This page-level tag-code, with trailing pipe,
<pre>{{Tag|CommonGround|}}</pre>
produces a list of related pages. That enables the user to jump directly to any related page:

<syntaxhighlight lang=html>
<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>
</syntaxhighlight>

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==
When a tag-name is clicked in a tagged wiki-page, user is directed to [[/Page-Tag|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 [[phab:T194571|rejected by admins]].

== Region-tagging ==
Enables editor to apply a topic-tag to a '''''<u>region</u>''''' 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. {{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 ==
=== Tag Descriptions Page ===
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 ===
Descriptions are added/edited using the visible TopicTag Page. That's done with a contentEditable div and javascript.

==DPL Format==
The DPL3 format syntax is:
<pre>| format=Startall,Start,End,Endall</pre>

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: <pre>[[page_name#anchor_name|display_as]]</pre> (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
<pre>| format   = ,\n* [[%PAGE%#Tag:{{#urlget:Tag}}|%PAGE%]],,</pre>

''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=
Must-haves before publishing this extension:
* Resolve '''[[#Known Issues|one high-risk, high-impact issue]]'''.

==Solve==
Solve all high-risk, high-impact [[#Known Issues|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 [[Talk:Phabricator/Project management#Setting Priority in Phabricator|whether or not someone volunteered to work on it]]. In software dev, that's an invalid definition of "Priority".)

== Conflict with <code><nowiki>Template:Tag</nowiki></code> ==
Risk: Low

Impact: High

<code><nowiki>Template:Tag</nowiki></code> is not part of mediawiki core, but it is used on mediawiki.org. This extension can't be used on wikis that use <code><nowiki>Template:Tag</nowiki></code>.

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 <code><></code> 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

== Popups ==
=== Inline Tags ===
On hover, show info and click-features, such as TopicTag Description, Share, etc
=== Related Pages ===
On hover, show first X characters of tagged text
=== Tags List ===
On hover, show info such as TopicTag 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. [[#Related]]

*

== 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<pre>{{Tags|Green, Blue, Yellow|}}</pre>. Automatically get "Related Pages" section-header.

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

== Stats ==
Would be cool to display usage stats, click stats, and other info about the TopicTag on the TopicTag 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 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 ==
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 <code><nowiki>{{EndTag}}</nowiki></code> 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|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]]



[[Category:All extensions]]
[[Category:Under construction]]