==Very short introduction==
Just have a look to the 2 [[Mediawiki_RawFile#Short_example|examples]] to see how to use the extension
and to the [[Mediawiki_RawFile#Installation|Installation]] section to see how to install the extension in your [[MediaWiki]] server
==Introduction==
Originally the idea was to be able to download directly a portion of code as a file.
I've numerous code examples in my wiki and I wanted an easy way to download them, easier than a copy/paste!
But from there it was rather easy to get something very close to [http://en.wikipedia.org/wiki/Literate_programming literate programming] just by allowing multiple blocks referring to the same file, which will be concatenated together at download time.
* It must work with pre, nowiki, js, css, code, source, so let's make it general: take the tag that comes after the parser function we'll create and select data up to the closing tag.
* There are two distinct functionalities provided by the extension:
** the parser that will convert a magic word into a link to the download URL
** an extended ?action=raw that will strip the raw output to keep the desired code
==Syntax==
The extension introduces 3 elements:
;Anchor
: Used to flag that the next code block in the wiki text belongs to a specific file. The code block can be any wiki block (such as '''<pre>''', '''<code>''', '''<tt>''', '''<source>'''...). '''<br>''' tags are ignored. Note that anchors are invisible in the wiki display.
;Link
: They are transformed by the extension into links that allows for downloading all blocks attached to a given anchor name.
;Anchor-link
: A shortcut notation mixing both an anchor and download link, handy for regular use, when a single code block is used and when the download link can be at the same position as the anchor.
The syntax is as follows. The syntax using tag <file> and tag attribute class is new since v0.4. Note that elements of both syntaxes can be mixed in a same page.
{| border="2" cellspacing="4" cellpadding="3" style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaaaaa solid; border-collapse: collapse; empty-cells:show;"
!width="80em" style="background: #8da7d6;"|Element!!style="background: #8da7d6;"|Syntax and description
|-
|'''Anchor'''
|
{{#fileAnchor: anchorname}}
...</pre>
...</code>
...</code>
...
Indicates that the next wiki block is attached to an anchor ''anchorname''. The content of that block will be downloaded (possibly appended with other blocks if there are several blocks attached to the same ''anchorname'') when a file link is clicked on.
'''(since v0.4)''' To attach an anchor ''anchorname'' to a wiki block, simply add an attribute class="anchorname" to it. The extension supports multi-class specification, meaning that a same block can be associated to different files, and that the class attribute can still be used to specify custom CSS properties as in standard wiki text.
; ''anchorname''
; class="''anchorname''"
: The name of the anchor to which the wiki block is attached
|-
|'''Link'''
|
[{{#fileLink: anchorname}} link text]
[{{#fileLink: anchorname|pagetitle}} link text]
link text
Creates a link to download all blocks that are attached to an anchor ''anchorname''.
;''anchorname''
;anchor="''anchorname''"
: The name of the anchor to look for. All blocks attached to an anchor ''anchorname'' will be downloaded.
;name="''filename''"
:''Optional'' - Specifies the name of the file to download. If absent, ''anchorname'' is then used as the name of the downloaded file.
; ''pagetitle''
;title="''pagetitle''"
: ''Optional'' - Indicates that the blocks to download are on the wiki page titled ''pagetitle''. If absent, blocks are looked for on the current page.
; ''link text''
: The text of the link to display.
|-
|'''Anchor-link'''
|
[{{#file: filename}} link text]
link text
Creates a link to download the next wiki block as a file named ''filename''.
'''(since v0.4)''' The attribute tag can be used to specify the ''tagname'' of the block to download.
; ''filename''
; name="''filename''"
: The name of the file to download.
;tag="''tagname''"
:''Optional'' - When set, the extension only looks for blocks whose name matches the given ''tagname''. This attribute is particularly useful when there are some irrelevant blocks between the '''anchor-link''' and the block you want to download. If absent, the first encountered block following the anchor is downloaded.
; ''link text''
: The text of the link to display.
|}
===Short example===
The extension works with any block such as pre, nowiki, js, css, code, source,...
This example is using the syntax highlighting tag provided by [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi SyntaxHighlight extension] (using [http://qbnz.com/highlighter/ GeSHi Highlighter])
If you didn't install that extension on your MediaWiki, you can try the example by using instead of .
Let's save the following code [{{#file: myscript.sh}} as myscript.sh]
will give:
----
Let's save the following code [{{#file: myscript.sh}} as myscript.sh]
===Complete example===
And a full example with anchors & link:
Let's start with the Bash usual header:
{{#fileanchor: myotherscript.sh}}
Then we'll display a welcome message:
{{#fileanchor: myotherscript.sh}}
And we finally exit cleanly:
{{#fileanchor: myotherscript.sh}}
[{{#filelink: myotherscript.sh}} myotherscript.sh is now available for download below the code]
will give:
----
Let's start with the Bash usual header:
{{#fileanchor: myotherscript.sh}}
Then we'll display a welcome message:
{{#fileanchor: myotherscript.sh}}
And we finally exit cleanly:
{{#fileanchor: myotherscript.sh}}
[{{#filelink: myotherscript.sh}} myotherscript.sh is now available for download below the code]
=== Example using templates ===
The new syntax <file name="..." [tag="..."]>...</file> allows for using the RawFile extension in templates as well.
The example below uses the template [[Template:Rawfiledownloadexample]] to avoid duplication between the file name in the text and as a parameter in the <file> tag.
See the template source for instructions on how to create the template.
{{Rawfiledownloadexample|name=myfile.txt|content=Once upon a time
There was a Tag
Tag was clickable
And clicked it was}}
The code above gives
{{Rawfiledownloadexample|name=myfile.txt|content=Once upon a time
There was a Tag
Tag was clickable
And clicked it was}}
==The code (the ultimate example)==
Which you can of course download just by following [{{#filelink: RawFile.php}} this link :-)]
So let's explain a bit the code in a Literate Programming way...
===Hooks===
First some hooks for our functions...
We will create:
* a [http://www.mediawiki.org/wiki/Manual:Parser_functions Parser Function] (see also [http://meta.wikimedia.org/wiki/Help:Parser_function here]), with help of
** [http://www.mediawiki.org/wiki/Manual:%24wgExtensionFunctions $wgExtensionFunctions] or [http://www.mediawiki.org/wiki/Manual:Hooks/ParserFirstCallInit ParserFirstCallInit global hook] to define the setup function
** [http://www.mediawiki.org/wiki/Manual:Magic_words Magic Words]
** [http://www.mediawiki.org/wiki/Manual:Tag_extensions Tag extensions]
** [http://www.mediawiki.org/wiki/Manual:Hooks/LanguageGetMagic LanguageGetMagic] hook to initialize the magic words
* a [http://www.mediawiki.org/wiki/Manual:Hooks/RawPageViewBeforeOutput RawPageViewBeforeOutput] hook to intercept the raw output
{{#fileanchor: RawFile.php}}