Վիքիպեդիա:ՎիքիՆախագիծ Ուղեգիծ/Հաքաթոն/Օգնություն:Կաղապար

Կաղապար:Wiki նշումներ

↱
  • H:T
  • ՎՓ:ԿԱՂԱՊԱՐ

։Գտնելու համար շատ օգատործվող կաղապարները, նայել Կատեգորիա:Վիքիպեդիայի կաղապարներ

Կաղապարը Վիքիպեդիայի էջ է, ստեղծված այլ էջերում ներառվելու նպատակով։ Կաղապարները սովորաբար ներառում են կրկնվող նյութ, որը կարող է կարիք ունենալ ցույց տրվելու ցանկացած քանակով հոդվածներում կամ էջերում։ Դրանք սովորաբար օգտագործվում են կաղապարային հաղորդագրություններում, ստանդարտ նախազգուշցումներում կամ ծանուցումներում, տեղաքարտերում, նավարկային տուփերում և նման այլ դեպքերում։ Կաղապարների օգատագործման ամենատարածված մեթոդը կոչվում է ներառում, որտեղ վիքիտեսքտ նշանակետ (target) տեսքը ներառում է հղում կաղապարի վրա, օգտագործելով {{Կաղապաարի անուն}} շարահյուսություն։ Մեկ ուրիշ եղանակ է փոխարինումը, որում կաղապարի պարունակությունը կրկնօրինակվում է նշանակետ վիքիտեքստում, միայն մեկ անգամ, երբ այն հիշվում է։

Առարկայի համառոտ ներկայացման համար տես Արագ ծանոթացումը կաղապարներին։

Հիմնական խմբագրել

Հիմնական կաղապարները էջեր են Կաղապարային անվանատարածքերում, ինչը նշանակում է, որ դրանք ունեն այս տեսքի վերնագրեր՝ "Կաղապար:ԱԱԱ"։ Ամեն դեպքում հնարավոր է ներառել և փոխարինել ցանակցած անվանատարածքից,[1] և այսպիսով որոշ կաղապարային էջեր տեղաորված են ուրիշ անվանատարածքում, ինպես օրինակ Օգտագործողի անվանատարածք։ Ինչպես ուրիշ էջերը, այնպես էլ կաղապարները, կարող է կապված ունենալ քննարկման էջեր։ Կաղապարները կարող են պարունակել ցանկալի վիքիտեսքստեր, ներառելով այլ կաղապարների կանչեր։ Դրանք ունեն որոշակի սահմանափակ ծրագրավորման հնարաավորություններ․ customizable արժեքներ (կոչվող պարամետրեր), հաշվարկ և ճյուղավորում (օգտագործելով շարահյուսական վերլուծող ֆունկցիա), և մուտքի թույլտվություն հատուկ վիքի փոփոխականներին (կախարդական բառեր), ինչպիսիք են ամսաթվերը, ժամերը և էջերի անունները։ Դրանք կարող են նաև ներառել թեգեր, որոնք սահմանում են, թե վիքիտեքստի որ մասերը պիտի օգտագործվեն, երբ կաղապարը ներառվել է, կամ փոխարինվել։ Սա նշանակում է, որ կաղապարի էջի արտաքին տեսքը պարտադիր չէ, որ լինի նույնը, ինչ ներառված հատվածը, (օրինակ, այն կարող է պարունակել դոկումենտացիա, կատեգորիաներ, և այլն կաղապարների համար)։ Կաղապարը հոդվածում կամ էջում ներառելու համար հարկավոր է հավաքել {{կաղապարի անունը}} վիքիտեսքտի այն հատվածում, որում այն պետք է երևա։ ("Կաղապար:" նախածանցը պարչդաիր չէ, որ ներառված լինի։) Էջի դիտվելու ժամանակ սերվերները կստանան կաղապար էջի պարունակությունը, և կտեսադրեն արդյունքը կաղապար թեգի տեղում։ Այլ անվանատարածքում գտնվող կաղապարները ներառվում են նույն կերպ, սակայն նախածանց անվանատարածքը, ինպիսինէ "Օգտագործող:"-ը, պիտի նշվի։ Էջը Ներառելու համար mainspace-ում, հարկավոր է, էջի անունից առաջ դնել երկու կետ, ինչպես օրինակ {{:Էջի ունուն}} (հակառակ դեպքու այն կաշխատի որպես հղում էջի, որը գտնվում է Կաղապարների աանվանատարածքում)։ Եթե փորձ է կատարվում նեռարել գոյություն չունեցով կաղապար, ապա այն նշվում է որպես կարմիր հղում, ինչպես հղում, ցանկացած այլ գոյություն չունեցող էջի։ Այդ հղումով գնալը, թույլ է տալիս ստեղծել համապատասխան կաղապարը։ Հնարավոր չէ ներառել էջեր տարբեր նախագծերից (ինչպիսիք են տարբեր լեզուներով Վիքիպոդիաները) – որպեսզի այն օգտագործվի այլ լեզվով Վիքիպեդիայում, հարկավոր է, որ նրա կրկնօրինակը այդ նախագծում ստեղծվի։

Լրիվ շարահյուսությունը ներառման և փոխարինման համար խմբագրել

Ներառման հիմնական շարահյուսությունը, որը տրված է վերևում, կարող է ընդլայնվել, ավելացնելով լրացուցիչ պարամետրեր, որոնք օգտագործվում են կառավարելու կաղապարի էկրանին դուրս բերածը։ Դրա համար շարահյուսությունը հետևյալն է՝

  • {{կաղապարի անուն|պարամետր|պարամետր|...}}

որտեղ, յուրաքանչյուր «պարամետրը» ինչպես կարող է պարունակել պարզապես արժեք, (դրանք կոչվում են անանուն պարամետրեր), այնպես էլ լինել այս տեսքի՝ անուն=արժեք (անվանված պարամետրեր)։ Առաջին, երկրոր,․․․ անանուն պարամետրերը համարժեք են "1", "2", ․․․ անվանված պարամետրերին։

Վիքիբացատ սիմվոլները (բացատներ, tabs, returns) ջնջվում են անվանված պարամետրերի անուններից և արժեքների սկզբերից և վերջերից , բայց ոչ մեջտեղից, այսպիսով {{ ... | իմպարամ = սա թեստ է }} ունի նույն էֆֆեկտը, ինչ {{ ... |իմպարամ=սա թեստ է}}-ը։ Սա չի վերաբերում անանուն պարապետրերին, որոնց դեպքում, վիքիբացատները պահպանվում են։ Ինչ պարամետրեր կարող են, կամ պետք է փոխանցվեն կաղապարներին, և ինչպես դրանք անվանել, կախված է կաղպարի ծրագրավորումից։ Անվանված պարամետրերը կարող են սահմանվել ցանկացած կարգով։ Ավելորդ կամ սխալ անվանված պարամետրերը կանտեսվեն, չսահմանված պարամետրերին կվերագրվեն լռությամբ արժեքները։ Եթե պարամետրը սահմանված է մեկից ավելի անգամ, ապա վերջին արժեքն է աշխատում։

Պարամետրի արժեքը կարող է լինել դատարկ տող (pipe or equals sign followed immediately by the next pipe or the closing braces)։ Սա տարբեր է պարամետրը չսահմանված թողնելուց(չնայած կաղապարները հաճախ ծրագրավորված են այնպես, որ երկու դեպքում էլ հասկական նույնը)։ Եթե կաղապարը պիտի փոխարինված լինի վիքիտեքստում, ավելի հաճախ, քան ներառված, ավելացրեք հետևյալ ձևափոխիչը՝ subst: after the initial pair of braces, as in {{subst:afd}}։ Պարամետրերը կաչող են ավելացվել ինչպես վերևու։ (Եթե էջը փոխարինվում է mainspace-ում, "subst" բառը պիտի հետևի երկու կետին)։ Կաղապարային անունները, ճիշտ այնպես ինչպես մնացած անունները Էջի անուն․ մեծատառ-փոքրատառի հանդեպ զգայուն են, բացառությամբ առաջին տառի, և բացատները տակի գծերից չեն տարբերվում։ Եթե # սիմվոլը (սովորաբար օգտագործվող էջի հատվածում հղում դնելու նպատակով) դրվում է ներառման մեջ, ապա դա, և դրանից հետո եկող ցանկացած սիմվոլ անտեսվում է։ Եթե ներառման համար օգտագործված էջի անունը վերահղում է, ապա վերահղվող նշանակետը կներառվի դրա փոխարեն․ սա նշանակում է, որ կարող են ստեծվել այլընտրանքային անուններ կաղապարների համար։ Ծանուցումները, որոնցում օգտագործված է նույն երկու {{ շարահյուսությունը, ինպես Վիքիմեդիայի փոփոխականները և Շարահյուսական վերլուծող ֆունկցիաները (տես Օգնություն:Կախարդական բառեր)։ Օրինակ հետևյալ կոդը՝ {{անվանատարածք}} կունենա կաղապարի կանչի տեսք, սակայն այն իրականում փոփոխական է, որի արժեքը այս էջի անվանատարածքի նախածանցն է։


Examples with parameters

An example of a template that takes parameters is Template:For. Type {{for|the card game|Contract bridge}} in the sandbox to produce the following text:

This usage takes two unnamed parameters, but the same template can also be used with different numbers of parameters to give slightly different results, as explained in the documentation on the template page. Note in particular the usage with an empty parameter: {{for||USE1|USE2}} – here the consecutive pipes mean that the first parameter passed to the template is the empty string.

Other templates, particularly more complex ones, take named parameters (or a mixture of named and unnamed ones). A simple example is Template:Payoff matrix, used to generate a 2-by-2 grid. Type:

{{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }}

Կաղապար:Payoff matrix to produce the grid you can see on the right.

See the template page for more possibilities. Notice that the template is used here without defining all its possible parameters – undefined parameters are given default values.

The spaces around the equal signs and before and after the parameters are used only for clarity – they are not needed, and are ignored when the template is evaluated (although this is not the case with unnamed parameters). However parameter names are fully case sensitive – for example, it is not possible to replace "DR" by "dr" or "Dr" in the above example. Parameters with names that are not used by the template are simply ignored.

Օգտագործման հուշումներ և շրջանցման եղանակներ

Հետևյալ կետերը կարող են ոչինչ չնշանակել, եթե օգտագործեք կաղապարներ։

  • Անանուն պարամետրը չի կարող պարունակել սովորական հավասար է նշանը, քանի որ դա կինտերպրետացվի ինչպես անուն ունեցող պարապետրի վերաանվանում։ (Սա չի աշխատում, եթե հավսար է նշանը գալիս է այլ կաղապարի կանչի հետ, կամ այլ կետով, ինչը շարահյուսական վերլուծող ֆունկցիան հասկանում է առանձին։) Անանուն պարամետրերին հավասար է նշանը փոխանցելու համար (օրինակ URL բանալի/արժեք-ի զույգեր), փոխարինել հավասար է նշանը այս հատուկ կաղապարով {{=}}, ինչը վերադարձնում է հավասար է նշանը, որը առանձին չի ինտերպրիտացվի։ Մեկ այլ եղանակ է փոխարինել անանուն պարամետրը (և ցանկացած հերթական անանուն պարամետրեր) անունով պարամետրերով՝ աձաջին անանուն պարամետրը կլինի համարժեք "1" պարամետրին, և այսպես շարունակ։ Այսպիսով կաղապարը կանչելու համար {{done}}-ը "ա=բ" պարամետրովմ հավաքեք {{done|ա{{=}}բ}} կամ *{{done|1=ա=բ}}.
  • Նույն կերպ, հնարավոր չէ օգտագործել սովորական ուղղահայաց գիծը՝ | կաղապարում, որովհետև այն կինտերպրետացվի որպես բաժանիչ։ (Կրկին, սա չի աշխատի, եթե այն գալիս է մեկ այլ շարահյուսորեն առաձին վերլուծվող վիքիհղման հետ։) Այս անգամ, խնդիրը կարող ենք լուծել օգտագործելով հատուկ կաղապար {{!}} ուղղահայաց գծի փոխարեն, կամ (եթե ուղղահայաց գծիկը նախատեսված չէ ավելի բարձր մակարդակում բաժանված լինել) օգտագործելով HTML entity |.
  • Remember that whitespace characters (spaces, tabs, carriage returns and line feeds) are not automatically stripped from the start and end of unnamed parameters (as they are from named parameters). Including such characters (or any other non-visible characters in any parameters) may in some cases affect the template's behaviour in unexpected ways. (Template designers can use {{StripWhitespace}} to remove unwanted whitespace in unnamed parameters.)
  • In documentation and discussions it is often convenient to be able to produce the template call syntax, with a link to the template in question, but without actually calling the template. This can be done easily using the "{{tl}}" template (the template link template). For example, using the text "{{tl|tc}}" produces "{{tc}}". There is an extended version, {{tlx}}, which also supports parameters.
  • When a template is changed (when the template or one of its subtemplates is edited), the change will be reflected on all pages on which the template is transcluded. However the change may not become visible on all pages immediately – a previously cached version of a page, based on the previous version of the template, may continue to be displayed for some time. Use the purge function to force a page to be displayed using the latest versions of templates. (This includes the template page itself, if it contains usage examples.)
  • When viewing old versions of pages, remember that templates will be transcluded as they are now, not necessarily as they were when the old page version was active.
  • To list all pages onto which a template is transcluded, use What links here on the template page. (This will not include pages where the template has been substituted.)
  • To get a list of templates transcluded on a page, click "Edit", and find the list below the edit window. This list also includes the sub-templates used by the templates that are directly transcluded. To get such a list for a page section, an old version of the page, or your newly edited version prior to saving, click "Show preview" on the appropriate edit page. (For an old version, the subtemplate tree will be constructed according to the templates' current state.)

Creating and editing templates

Templates are created and edited in much the same way as any other page: choose an appropriate name, navigate to that page, then click the Edit tab or create a new page as needed. As mentioned above, templates are normally placed in the Template namespace, though templates intended for your own personal use or for experimentation can be created in your own user space. Anything that can be included on a normal page or article can be included on a template, including other templates (called subtemplates). Templates often make use of programming features – parameters, parser functions and other magic words – which allow the transcluded content to vary depending on context. There are also special tags to control which information is transcluded and which is not.

Before creating a template, do a quick search for existing templates (e.g. by exploring Category:Wikipedia templates) to see if there's already a template that does what you want, or a similar template whose code can be copied and modified (or left in place and expanded). Look for generic templates on which the new template can be based (for example, navbox templates can be easily created by calling the generic Template:Navbox).

There is no hard rule about what name to choose for a template – make it short but reasonably descriptive. If similar templates exist, try to follow the a consistent naming pattern. Templates can be renamed without breaking existing transclusions, provided a redirect to the new template name is left behind.

Be extremely careful when editing existing templates – changes made can affect a large number of pages, often in ways you might not expect. For this reason many high-use templates are protected against editing except by administrators (other editors can propose changes on the talk page). Some templates offer a sandbox and test cases for experimentation.

To propose the deletion of unused or inappropriate templates, or other changes in the way particular templates are used, go to Templates for discussion (TfD).

Handling parameters

The values of the parameters which can be fed to a template are represented in the template code by items enclosed between triple braces:

  • the code {{{xxx}}} will be replaced by the value of the parameter named xxx
  • the codes {{{1}}}, {{{2}}} etc. will be replaced by the first, second etc. unnamed parameter (or the value of a parameter named 1, 2, etc.)

If a parameter is not assigned a value, then the above replacements will not take place – the form "{{{xxx}}}" will remain as the effective value of the parameter. To change this behaviour, define default values using the pipe syntax. For example, {{{1|unknown}}} will be replaced by the first unnamed parameter if there is one, or otherwise by the text "unknown".

Parameters do not get expanded when they are inside nowiki tags or XML-style extension tags. Thus, the following will not work within a template - <myextension xparam={{{tparam}}}> ... </myextension> - because the parameter is not expanded.

Because of the multiple uses of double-brace and triple-brace syntax, expressions can sometimes be ambiguous. It may be helpful or necessary to include spaces to resolve such ambiguity, for example by writing {{ {{{xxx}}} }} or {{{ {{xxx}} }}}, rather than typing five consecutive braces. However, watch out for unwanted whitespace appearing in template expansions.

System variables and conditional logic

Template code often makes use of the variables and parser functions described at Help:Magic words, in order to make the template's behaviour depend on the environment (such as the current time or namespace) or on the parameter values which are passed to it. They can also be used for arithmetical calculations. Notice that full string manipulation is not available (although templates have been created which provide such functionality, though very inefficiently and imperfectly), nor are certain standard programming features such as loops and variable assignment.

Some of the most often used variables and functions are listed below. For more, see Help:Magic words, and the fuller documentation at the MediaWiki pages mw:Help:Magic words and mw:Help:Extension:ParserFunctions.

Examples of core parser functions
Description Text Entered Result
Uppercasing text {{uc: Heavens to BETSY! }} HEAVENS TO BETSY!
Lowercasing text {{lc: Heavens to BETSY! }} heavens to betsy!
Getting a namespace name {{NS: 1 }} Քննարկում
Getting a wikipedia URL {{fullurl: pagename }} //hy.wikipedia.org/wiki/Pagename

The parserFunctions extension gives more programming-oriented parser functions.

Examples of extension parser functions
Description Text Entered Result
Testing between options {{#ifeq: yes | yes | Hooray...! | Darn...! }}
{{#ifeq: yes | no | Hooray...! | Darn...! }}
Hooray...!
Darn...!
Testing if a parameter is set {{#if: {{{param|}}} | Hooray...! | Darn...! }} Darn...!
making a calculation {{#expr: ( 27 * 46 / pi ) round 2 }} 395.34
Examples of System Variables
Description Text Entered Result (for this help page)
Page names {{PAGENAME}}
{{FULLPAGENAME}}
ՎիքիՆախագիծ Ուղեգիծ/Հաքաթոն/Օգնություն:Կաղապար
Վիքիպեդիա:ՎիքիՆախագիծ Ուղեգիծ/Հաքաթոն/Օգնություն:Կաղապար
Name of the current namespace {{NAMESPACE}} Վիքիպեդիա
Number of registered users {{NUMBEROFUSERS}} 143 247
Number of pages in a given category {{PAGESINCATEGORY:"Weird Al" Yankovic albums}} 0
Current software version {{CURRENTVERSION}} 1.43.0-wmf.1 (8e1947e)
Timestamp of last revision {{REVISIONTIMESTAMP}} 20191222062552

The PAGENAME and NAMESPACE variables are particularly useful, and frequently used, to change template behavior based on context. For example, if the template transcludes a category link (e.g. cleanup templates, which transclude a link categorizing the page as a page which needs cleanup), it will often check the NAMESPACE variable to make sure that talk pages, user pages, or anywhere else the tag might incidentally be placed do not themselves get categorized as pages needing cleanup.

Nesting templates

Templates may contain other templates – usually called 'nesting'. As the template is processed, the wikitext produced by any nested templates is transcluded into the nesting template, so that the final product is essentially processed from the most deeply nested template out. While fairly straight-forward in application, it involves some noteworthy quirks and tricks.

To pass a parameter value to a nested template, place a parameter tag as the value of one of the nested template's parameters.

  • Examples:
    • Template:A contains "the quick brown {{B|{{{3}}}}} jumped over...". This takes the value passed to the third positional parameter of Template:A and passes it as the first positional parameter of Template:B, then returns the wikitext produced by B as part of the phrase.
    • Template:A contains "the quick brown {{B|waldo={{{3}}}}} jumped over...". As above, except the third positional parameter of Template:A is passed to the named parameter 'waldo' of Template:B.

Template parameters themselves can be chosen conditionally.

  • Example:
    • Template:A contains "the quick brown {{B|{{{3}}}=fox}} jumped over...". Template:A passes the word 'fox' to a parameter of Template:B that's named in A's third positional parameter.

A template can call itself, but will stop after one iteration to prevent an infinite loop.

When a nested template contains unmatched curled-brackets – as in {{lb}} – the unmatched brackets are treated as text during processing, and do not affect the parsing of brackets in the nesting template. If the nested template is substituted, however, the substitution is processed first, and this will change how braces are parsed in the nesting template. This has little practical use, but can occasionally introduce unexpected errors.

See the help:advanced templates and meta:Help:Recursive conversion of wikitext for more information. These pages also contain information on unusual calls such as {{template {{{parameter|}}} }}.

Noinclude, includeonly, and onlyinclude

By default, when a template is transcluded (or substituted), the entire wikitext (code) of the template page gets included in that of the target page. However it is possible to modify that behaviour, using tags that specify which parts of the template code are to be included. This makes it possible to avoid transcluding information intended for display only on the template page itself, such as the template's documentation, categories and interwiki links. It is also possible to have parts of the code be transcluded, but not be processed on the template page itself (e.g. categories to be applied to the target pages which do not apply to the template). The tags are as follows

  • <noinclude>...</noinclude> – the text between the noinclude tags will not be included when the template is transcluded (substituted)
  • <includeonly>...</includeonly> – the text between the includeonly tags will be transcluded (substituted), but will not be processed on the template's own page
  • <onlyinclude>...</onlyinclude> (not often used) – specifies that nothing on the page except what appears betweeen the onlyinclude tags will be transcluded (substituted)

Perhaps the most common issue with the use of these blocks is unwanted spaces or lines. It is important to remember that the effect of these tags ends immediately after the last angle bracket, not on the next line or with the next visible character.

These tags can be nested inside each other, though (for a given page) this really only applies to the 'onlyinclude' tag; nesting 'includeonly' and 'noinclude' tags is fairly pointless. Be careful not to split the tags, however. Constructions like this <onlyinclude>abc<includeonly>def</onlyinclude>ghi</includeonly> will not work as expected. Use the 'first opened, last closed' rule that is standard for XML.

Problems and workarounds

  • If the first included character of a template is one of the Wiki markup characters :;*#, then it is processed as though it is at the beginning of a line (even when the template tag is not). This allows the creation of various kinds of lists in templates where the template may not always be in the correct place for a list. To avoid this effect use <nowiki>#</nowiki> or a numeric character reference (Կաղապար:Mlw) or HTML entity such as &#58; for a colon. This NCR is also useful in conjunction with definition lists.
  • For issues involving the substitution of templates (for example, how to control whether subtemplates are substituted as well when the parent template is substituted), see Help:Substitution.
  • The template {{StripWhitespace}} can be used to strip any initial or final whitespace from unnamed parameter values, if this would cause problems (named parameter values are automatically stripped in this way).
  • For debugging templates the following techniques are sometimes helpful:
    • using 'subst:' - substituting a template (rather than transcluding it) can show more clearly what is happening when the template is transcluded.
    • using 'msgnw:' - this keyword (short for "message, nowiki") transcludes the wikitext of the template page, more or less, rather than the processed contents. it is not perfect: lists are rendered, comments are removed, and single newlines are replaced with spaces (which is particularly confounding when transcluding wikitext tables).
    • using Special:ExpandTemplates to see the full recursive expansion of one or more templates.
  • To protect server resources and avoid infinite loops, the parser imposes certain limits on the depth of nesting of transclusions and on the page size with expanded templates. This may cause pages to break when using very complex templates, particularly if there are multiple such templates on the same page. For more information, see Template limits. (A page's overall load on the server can be checked by examining the generated HTML for a page and looking for the "NewPP limit report" comments.)
  • Do not use = wikimarkup to create section headers within a template which is intended for use in article space — this will create an [edit] link that when transcluded will confusingly open the template for editing.

Documentation and categories

Categorizing your template and documenting its proper usage will make it easier for other editors to find and use. For detailed advice, see Wikipedia:Template documentation.

Documentation for users, together with the template's categories and interwiki links, is normally placed after the template code, inside "noinclude" tags. It is normally necessary to put the opening "noinclude" tag immediately after the end of the code, with no intervening spaces or newlines, to avoid transcluding unwanted whitespace.

In the case of complex templates, the documentation (together with categories and wikilinks) is often kept on a separate subpage of the template page (named "Template:XXX/doc"). This also applies to many protected templates (to allow the information to be edited by non-administrators). This is achieved by placing the {{Documentation}} template after the main template code (within "noinclude" tags). If the "/doc" subpage does not exist, a link will then appear enabling it to be created.

Some templates contain category definitions in their transcluded code, i.e. they are intended to place the target pages in particular categories. This is often done with maintenance categories (placing articles into ordinary content categories in this way is discouraged). When doing this, it may be necessary to use "includeonly" tags to keep the template itself out of the category. The template should also be designed to suppress categorization in the case of demonstration uses – see Category suppression in templates.

See also

Help pages Manual pages Special pages Other pages not for direct viewing

  1. Namespaces from which transclusion is not allowed are specified on a wiki by the variable $wgNonincludableNamespaces