Extension:HTMLets
This extension is currently not actively maintained! Although it may still work, any bug reports or feature requests will more than likely be ignored. If you are interested in taking on the task of developing and maintaining this extension, you can request repository ownership. As a courtesy, you may want to contact the author. You should also remove this template and list yourself as maintaining the extension in the page's {{Extension }} infobox. |
Release status: unmaintained |
|
---|---|
Implementation | Tag |
Description | Lets you inline HTML snippets from files |
Author(s) | Daniel Kinzler (Duesentriebtalk) |
Latest version | Continuous updates |
MediaWiki | 1.23+ |
PHP | 5.3+ |
Database changes | No |
License | GNU General Public License 2.0 or later |
Download | |
$wgHTMLetsDirectory |
|
<htmlet> |
|
Quarterly downloads | 21 (Ranked 118th) |
Translate the HTMLets extension if it is available at translatewiki.net | |
The HTMLets extension provides a way to include (inline) static HTML snippets into wiki pages.
Installation
[edit]- Download and move the extracted
HTMLets
folder to yourextensions/
directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/HTMLets - Add the following code at the bottom of your LocalSettings.php file:
require_once "$IP/extensions/HTMLets/HTMLets.php"; $wgHTMLetsDirectory = "$IP/extensions/HTMLets";
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Usage
[edit]Includes HTML snippets into wiki pages without changing the default setting of $wgRawHtml .
Snippets are located in files in a special directory on the web server.
This addresses the demand for a simple way to insert special JavaScript code, an <iframe>
, or an HTML form, without allowing users to insert arbitrary and potentially harmful code.
Including a HTML snippets is done using a special tag, <htmlet>
.
For example, if you put this on a wiki page:
<htmlet>foobar</htmlet>
This will include the contents of the file foobar.html
from the htmlet directory.
If the snippet may change often, and you want those changes reflected on the wiki page right away, you can tell HTMLets to disable the parser cache for this page:
<htmlet nocache="yes">foobar</htmlet>
The htmlet directory can be configured using $wgHTMLetsDirectory
; it defaults to "$IP /htmlets"
, i.e. the directory htmlets
in the installation root of MediaWiki; but note that if you follow the instructions given above for adding code to your LocalSettings.php file, the htmlet directory will be set to "$IP/extensions/HTMLets".
$wgHTMLetsDirectory
may also refer to a place on a webserver, for example, you can set it to http://localhost/htmlets/
, if you provide htmlets in that location - note that the .html
ending is enforced, query strings are not allowed in the htmlet's name.
Parser issues and hacks
[edit]Currently, the MediaWiki parser doesn't leave the output of parser hooks alone as it should (task T10997). This means that the HTML from your snipped file would be mangled under some circumstances (for example, if it contained indented or blank lines).
As of revision 19966, HTMLets works around this by supplying "hack modes".
Which hack is applied can be controlled using the hack
attribute for the <htmlet>
tag, the global default can be set using the $wgHTMLetsHack
setting in LocalSettings.php.
The following values are defined (the first is the name to use with the hack
attribute, the second is the constant name to use in LocalSettings.php):
- "bypass" (HTMLETS_BYPASS_HACK): should work safely; Works by outputting a Base64 encoded version of the HTML from your snippet file, and then decoding it an ParserAfterTidy hook. This is the default.
- "strip" (HTMLETS_STRIP_HACK): strip or encode anything that might trigger mangling. This will break any <pre> formatted text, and might also interfere with JavaScript code under some circumstances.
- "none" (HTMLETS_NO_HACK): just leave the content of the snippet file to the parser's mercy. In a perfect world, this should be fine. Right now, it will lead to unexpected results if you are not very careful not to trigger mangling. Known triggers are blank lines, and lines starting with blanks, "#", "*", ";", or ":". Blanks before a colon (":") anywhere in the line are also a problem. The cases mentioned here are the ones handled by HTMLETS_STRIP_HACK. There may be others, and the parser's behavior might change.
See also
[edit]- HTML restriction - list of extensions that allow for the inclusion of raw HTML
- Extension:HTML Tags
- Extension:CloudImage - embed images directly from image hosting services e.g. Flickr, OneDrive, Dropbox and others
- Extension:Widgets