Modul:File link/doc: Unterschied zwischen den Versionen

Aktuelle Version vom 8. Oktober 2022, 09:37 Uhr

This is a documentation subpage for Modul:File link.
It contains usage information, categories and other content that is not part of the original modul page.

This module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing.

This module depends on the following other modules:

This module is used to construct wikitext links to files. It is primarily useful for templates and modules that use complicated logic to make file links. Simple file links should be made with wikitext markup directly, as it uses less resources than calling this module. For help with wikitext file markup please refer to the documentation at mediawiki.org.

If none given, this automatically adds the global image file extension (.svg) to the filename.

Usage from Lua[Quelltext bearbeiten]

First, you need to import the module.

local mFileLink = require('Module:File link')

Then you can make file links using the _main function.

mFileLink._main(args)

args is a table of arguments that can have the following keys:

file - the filename. (required)
format - the file format, e.g. 'thumb', 'thumbnail', 'frame', 'framed', or 'frameless'.
formatfile - a filename to specify with the 'thumbnail' format option. The filename specified will be used instead of the automatically generated thumbnail.
border - set this to true or "yes" (or any other value recognized as true by Module:Yesno) to set a border for the image.
location - the horizontal alignment of the file, e.g. 'right', 'left', 'center', or 'none'.
alignment - the vertical alignment of the file, e.g. 'baseline', 'middle', 'sub', 'super', 'text-top', 'text-bottom', 'top', or 'bottom'.
size - the size of the image, e.g. '100px', 'x100px' or '100x100px'.
upright - the 'upright' parameter, used for setting the size of tall and thin images.
link - the page that the file should link to. Use the blank string '' to suppress the default link to the file description page.
alt - the alt text. Use the blank string '' to suppress the default alt text.
caption - a caption for the file.
page - sets a page number for multi-paged files such as PDFs.
class - adds a class parameter to image links. The MediaWiki software adds this parameter to the class="..." attribute of the image's <img /> element when the page is rendered into HTML.
lang - adds a language attribute to specify what language to render the file in.
start - specifies a start time for audio and video files.
end - specifies an end time for audio and video files.
thumbtime - specifies the time to use to generate the thumbnail image for video files.

To see the effect of each of these parameters, see the images help page on mediawiki.org.

Examples[Quelltext bearbeiten]

With the file only:

mFileLink.main{file = 'Example.png'}
-- Renders as [[File:Example.png]]

With format, size, link and caption options:

mFileLink.main{
	file = 'Example.png',
	format = 'thumb',
	size = '220px',
	link = 'Wikipedia:Sandbox',
	caption = 'An example.'
}
-- Renders as [[File:Example.png|thumb|220px|link=Wikipedia:Sandbox|An example.]]

With format, size, and border:

mFileLink.main{
	file = 'Example.png',
	format = 'frameless',
	size = '220px',
	border = true
}
-- Renders as [[File:Example.png|frameless|border|220px]]

@@ Zeile 1: / Zeile 1: @@
 {{documentation subpage}}
-{{module rating|release}}
+{{module rating|protected}}
+{{Lua|Module:Yesno|Module:Arguments}}
-This module is used to construct wikitext links to files, using a fluent Lua interface. This is done by creating a <var>fileLink</var> object, which has various methods corresponding to different file link parameters. The module is used from other Lua modules, and cannot be used directly from wiki pages.
+This module is used to construct wikitext links to files. It is primarily useful for templates and modules that use complicated logic to make file links. Simple file links should be made with wikitext markup directly, as it uses less resources than calling this module. For help with wikitext file markup please refer to the [[mw:Help:Images|documentation at mediawiki.org]].
-== Usage ==
+{{tmbox|type=notice|text=If none given, this automatically adds the global image file extension (<code>{{#invoke:Util|globalFileExtension}}</code>) to the filename.}}
-=== Creating the object ===
+<!--== Usage from wikitext ==
-First, you need to import the module.
+From wikitext, this module should be called from a template, usually {{tl|file link}}. Please see the template page for documentation. However, it can also be called using the syntax <code><nowiki>{{#invoke:File link|main|</nowiki>''arguments''<nowiki>}}</nowiki></code>.-->
-<source lang="lua">
+== Usage from Lua ==
-local fileLink = require('Module:File link')
-</source>
-Then, create the object using the <code>fileLink.new</code> function. The first parameter is the filename, and is optional.
+First, you need to import the module.
-<source lang="lua">
-local obj = fileLink.new('Example.png')
-</source>
-=== Basic usage ===
-You can add parameters to the file link using the fileLink object's methods. (See [[#Methods|the Methods section]] below for the full list.)
-<source lang="lua">
-obj:width(220)
-obj:alt('The alt text')
-obj:caption('The caption.')
-</source>
-You can then produce the link wikitext using the object's <code>render</code> method.
-<source lang="lua">
-obj:render()
-</source>
-This will produce the following wikitext:
-<pre>
-[[File:Example.png|220px|alt=The alt text|The caption.]]
-</pre>
-=== Call-chaining ===
-All the object's methods apart from the <code>render</code> method return the object itself, so can be used to call-chain.
-<source lang="lua">
-obj:width(220):alt('The alt text'):caption('The caption.'):render()
-</source>
-Apart from the <code>name</code> method, all of the object's methods support nil as an input, so call-chaining can be performed with variables whose value is unknown. However, an error will be raised if the input is of an unsupported type for that method. Please see [[#Methods|the Methods section]] for supported input types for each method. Passing nil to a method will overwrite any existing values.
-=== Use with tostring ===
-Instead of using the <code>render</code> method, you can call <code>tostring</code> on the object to create the link wikitext.
-<source lang="lua">
-obj:width(220):alt('The alt text'):caption('The caption.')
-tostring(obj)
-</source>
-== Methods ==
-=== Name ===
-<source lang="lua">
-obj:name(s)
-</source>
-Sets the filename. <var>s</var> must be a string. Nil values are not accepted, as every file link requires a filename. The filename can also be set in the first parameter to <code>fileLink.new</code>, although in that case it is optional.
-=== Format ===
-<source lang="lua">
-obj:format(s, filename)
-</source>
-Sets the display format. <var>s</var> must either be nil, or one of the strings 'thumb', 'thumbnail', 'frame', 'framed', or 'frameless'. To see the effect of each of these values, see the [[mw:Help:Images#Format|images help page on mediawiki.org]]. Note that the ''border'' format is not set with this method, but with the [[#Border|border method]]. (This is because the border option can be set independently of the values that can be set with this method, for example in the code <code><nowiki>[[File:Example.png|frameless|border|caption]]</nowiki></code>.)
-The <var>filename</var> variable is an optional variable that can be used to set the filename for thumbnails. The filename specified will be used instead of the automatically generated thumbnail. This option doesn't have any effect on the other format options.
-=== Border ===
-<source lang="lua">
-obj:border(hasBorder)
-</source>
-Sets a border for images. <var>hasBorder</var> must either be nil, or a boolean value. A border will be set if <var>hasBorder</var> is true. To see the effect of this option, see the [[mw:Help:Images#Format|images help page on mediawiki.org]].
-=== Width ===
-<source lang="lua">
-obj:width(px)
-</source>
-Sets a width for the file in pixels. <var>px</var> must either be nil or a number value. Width can be used in conjunction with the [[#Height|height method]], but will produce an error if used when the ''upright'' option has been set by the [[#Upright|upright method]].
-=== Height ===
-<source lang="lua">
-obj:height(px)
-</source>
-Sets a height for the file in pixels. <var>px</var> must either be nil or a number value. Height can be used in conjunction with the [[#Width|width method]], but will produce an error if used when the ''upright'' option has been set by the [[#Upright|upright method]].
-=== Upright ===
-<source lang="lua">
-obj:upright(isUpright, factor)
-</source>
-Sets the ''upright'' option, used for images that are taller than they are wide. <var>isUpright</var> must either be nil, or a boolean value. The upright option will be set if <var>isUpright</var> is true. <var>factor</var> provides an optional conversion factor for the upright option; the factor is the image's width divided by its height. If no factor is specified, the MediaWiki software uses the default of 0.75. <var>factor</var> must be either nil or a number value. If a width or height has been set with the [[#Width|width]] or [[#Height|height]] methods, then setting the upright value will result in an error.
-=== ResetSize ===
-<source lang="lua">
-obj:resetSize()
-</source>
-This method clears any size-related data the fileLink object is holding. This includes width, height, the upright option, and any upright factor.
-=== Location ===
-<source lang="lua">
-obj:location(s)
-</source>
-Sets the ''location'' option. This is also known as the ''horizontal alignment'' option. <var>s</var> must either be nil, or one of the strings 'right', 'left', 'center', or 'none'. To see the effect of each of these values, see the [[mw:Help:Images#Horizontal alignment|images help page on mediawiki.org]].
-=== Alignment ===
-<source lang="lua">
-obj:alignment(s)
-</source>
-Sets the ''alignment'' option. This is also known as the ''vertical alignment'' option. <var>s</var> must either be nil, or one of the strings 'baseline', 'middle', 'sub', 'super', 'text-top', 'text-bottom', 'top', or 'bottom'. To see the effect of each of these values, see the [[mw:Help:Images#Vertical alignment|images help page on mediawiki.org]].
-=== Link ===
-<source lang="lua">
-obj:link(s)
-</source>
-Sets a link target for the file, instead of the default target of the file description page. <var>s</var> must either be nil or a string value. The link can be a wiki page or a URL, although the exact formatting of the string is not checked by this module. To specify no link, use the blank string: {{code snippet|obj:link('')|lua}}.
-=== Alt ===
-<source lang="lua">
-obj:alt(s)
-</source>
-Sets [[WP:ALT|alt text]] for the file. <var>s</var> must either be nil or a string value.
-=== Page ===
-<source lang="lua">
-obj:page(num)
-</source>
-Sets a page number for multi-paged files such as PDFs. <var>num</var> must either be nil or a number.
-=== Class ===
-<source lang="lua">
-obj:class(s)
-</source>
-Adds a <code>class</code> parameter to image links. The MediaWiki software adds this parameter to the <code>class="..."</code> attribute of the image's <code><nowiki><img /></nowiki></code> element when the page is rendered into HTML. <var>s</var> must either be nil or a string value.
-=== Lang ===
-<source lang="lua">
-obj:lang(s)
-</source>
-Adds a language attribute to specify what language to render the file in. <var>s</var> must either be nil or a string value. This module does not check whether the language tag is valid or not.
-=== StartTime ===
-<source lang="lua">
-obj:startTime(time)
-</source>
-Specifies a start time for audio and video files. <var>time</var> must be nil, a number, or a string value. Numbers are interpreted as the number of seconds since the start of the file. Strings can be in the format "''mm'':''ss''" to specify the number of minutes and seconds of a file, or "''ss''" to specify the number of seconds since the start of the file.
-=== EndTime ===
-<source lang="lua">
-obj:endTime(time)
-</source>
-Specifies an end time for audio and video files. <var>time</var> must be nil, a number, or a string value. Numbers are interpreted as the number of seconds since the start of the file. Strings can be in the format "''mm'':''ss''" to specify the number of minutes and seconds of a file, or "''ss''" to specify the number of seconds since the start of the file.
+<syntaxhighlight lang="lua">
+local mFileLink = require('Module:File link')
+</syntaxhighlight>
-=== ThumbTime ===
+Then you can make file links using the <code>_main</code> function.
-<source lang="lua">
+<syntaxhighlight lang="lua">
-obj:thumbTime(time)
+mFileLink._main(args)
-</source>
+</syntaxhighlight>
-Specifies the time to use to generate the thumbnail image for video files. <var>time</var> must be nil, a number, or a string value. Numbers are interpreted as the number of seconds since the start of the file. Strings can be in the format "''mm'':''ss''" to specify the number of minutes and seconds of a file, or "''ss''" to specify the number of seconds since the start of the file.
+<var>args</var> is a table of arguments that can have the following keys:
+* <code>file</code> - the filename. (required)
+* <code>format</code> - the file format, e.g. 'thumb', 'thumbnail', 'frame', 'framed', or 'frameless'.
+* <code>formatfile</code> - a filename to specify with the 'thumbnail' format option. The filename specified will be used instead of the automatically generated thumbnail.
+* <code>border</code> - set this to true or "yes" (or any other value recognized as true by [[Module:Yesno]]) to set a border for the image.
+* <code>location</code> - the horizontal alignment of the file, e.g. 'right', 'left', 'center', or 'none'.
+* <code>alignment</code> - the vertical alignment of the file, e.g. 'baseline', 'middle', 'sub', 'super', 'text-top', 'text-bottom', 'top', or 'bottom'.
+* <code>size</code> - the size of the image, e.g. '100px', 'x100px' or '100x100px'.
+* <code>upright</code> - the 'upright' parameter, used for setting the size of tall and thin images.
+* <code>link</code> - the page that the file should link to. Use the blank string <nowiki>''</nowiki> to suppress the default link to the file description page.
+* <code>alt</code> - the alt text. Use the blank string <nowiki>''</nowiki> to suppress the default alt text.
+* <code>caption</code> - a caption for the file.
+* <code>page</code> - sets a page number for multi-paged files such as PDFs.
+* <code>class</code> - adds a <code>class</code> parameter to image links. The MediaWiki software adds this parameter to the <code>class="..."</code> attribute of the image's <code><nowiki><img /></nowiki></code> element when the page is rendered into HTML.
+* <code>lang</code> - adds a language attribute to specify what language to render the file in.
+* <code>start</code> - specifies a start time for audio and video files.
+* <code>end</code> - specifies an end time for audio and video files.
+* <code>thumbtime</code> - specifies the time to use to generate the thumbnail image for video files.
-=== Caption ===
+To see the effect of each of these parameters, see the [[mw:Help:Images#Format|images help page on mediawiki.org]].
-<source lang="lua">
+=== Examples ===
-obj:caption(s)
-</source>
-Sets a caption for the file. <var>s</var> must either be nil or a string value.
+With the file only:
+<syntaxhighlight lang="lua">
+mFileLink.main{file = 'Example.png'}
+-- Renders as [[File:Example.png]]
+</syntaxhighlight>
-=== Render ===
+With format, size, link and caption options:
+<syntaxhighlight lang="lua">
+mFileLink.main{
+	file = 'Example.png',
+	format = 'thumb',
+	size = '220px',
+	link = 'Wikipedia:Sandbox',
+	caption = 'An example.'
+}
+-- Renders as [[File:Example.png|thumb|220px|link=Wikipedia:Sandbox|An example.]]
+</syntaxhighlight>
-<source lang="lua">
+With format, size, and border:
-obj:render()
+<syntaxhighlight lang="lua">
-</source>
+mFileLink.main{
+	file = 'Example.png',
+	format = 'frameless',
+	size = '220px',
+	border = true
+}
+-- Renders as [[File:Example.png|frameless|border|220px]]
+</syntaxhighlight>
-Renders the link wikitext.
 <includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||