Extension:TemplateData

This extension comes with MediaWiki 1.35 and above. Thus you do not have to download it again. However, you still need to follow the other instructions provided.

MediaWiki extensions manual

TemplateData Release status: stable
Implementation	Tag , API
Description	מאפשר לאחסן, לאחזר ולהמחיש מידע על תבניות
Author(s)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Latest version	0.1.2 (עדכונים שוטפים)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	>= 1.43
PHP	5.4+
Database changes	No
License	GNU General Public License 2.0 or later
Download	Download extension Git [?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review
Parameters $wgTemplateDataUseGUI
Tags ‎<templatedata>
Hooks used EditPage::showEditForm:fields EditPage::showEditForm:initial MultiContentSave OutputPageBeforeHTML ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Quarterly downloads	277 (Ranked 19th)
Public wikis using	6,971 (Ranked 24th)
Translate the TemplateData extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

התוסף TemplateData מציג את התג ‎<templatedata> ואת ממשק ה-API הנלווה אליו, שאיתם עורכים ידעו איך להשתמש בתבניות. מידע זה זמין כטבלה בפורמט יפה עבור משתמשי קצה, וכ-JSON API, המאפשר להשתמש דרך מערכות אחרות (כגון VisualEditor ), וכן לבנות ממשקים עבור התבניות. ראו Help:TemplateData לעזרה מעמיקה.

התקנה

• Download and move the extracted TemplateData folder to your extensions/ directory.
  Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData
• Add the following code at the bottom of your LocalSettings.php file:

  wfLoadExtension( 'TemplateData' );
  

•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

עריכת מידע

התוסף TemplateData פועל באמצעות התג ‎<templatedata> המוגדר בקוד ויקי של הדף. תוסף זה נבנה עבור התאמת הפריסה הנפוצה של תיעוד תבניות במיזמי הוויקימדיה. תוכן התג ‎<templatedata> חייב להיות כתוב ב-JSON בפורמט המתואר להלן; יש לשים לב כי כל התיאורים חייבים להיות בטקסט רגיל.

כאשר התג ‎<templatedata> נכלל בדף, התוסף TemplateData מבצע את הבדיקות הבאות כאשר הדף נשמר:

1. התוכן חייב להיות כתוב ב-JSON.
2. כל פריט בתוך מבנה ה-JSON חייב להיות מהסוג כמפורט להלן (למשל אובייקט, מערך או פרימיטיבי).
3. עבור אותם פריטים שלהם רשימה מוגדרת של ערכים אפשריים (לדוגמה, הערך type של פרמטר), הערך באובייקט JSON חייב להיות תואם לאחד מהערכים הללו.

אם אחת מהבדיקות הללו נכשלת, לא יתאפשר לבצע שמירה בדף שעליו בוצעה העריכה, וכן תוצג הודעת שגיאה מעל דף העריכה.

עבור ערכי autovalue, הבעיה T4700 מונעת מ-subst: לעבוד בכל תבנית שנמצאת בתוך התג, כולל התגיות ‎<ref> ו-‎<gallery>. התוסף TemplateData יישמר כראוי, אך הקוד ויקי שיתקבל לא ינותח כראוי בעת השימוש בתבנית.

יש להימנע משימוש ב-{{#tag:templatedata}} מאחר ולא יהיה ניתן להשתמש בעורך התבניות.

פורמט

להלן גרסה חזותית של נתוני ה-JSON כפי שניתן להגדיר בדף התבנית המוקף בתגיות ‎<templatedata>‎</templatedata>. המפרט הפורמלי זמין במאגר TemplateData. לגרסה העדכנית ביותר, ראו Specification.md.

אובייקט TemplateData

האובייקט TemplateData הוא שורש JSON המוקף באלמנט ‎<templatedata> בדף התבנית.

מפתח	סוג	תיאור
description	InterfaceText או null	תיאור קצר של התבנית. זה חייב להיות טקסט רגיל. לאחר שערך זה מולא, ניתן להציג אותו ככיתוב בעת עריכת תבנית בודדת וכן אפילו בתוצאות החיפוש. ברירת המחדל הוא null. → For more details see: description
params	אובייקט הכולל רשימה של פרמטרים	אובייקט שממפה ומאפיין את כל שמות הפרמטרים של התבנית עבור הפרמטרים. → For more details see: params
paramOrder	מערך של פרמטרים	הסדר הלוגי של הצגת הפרמטרים על ידי המערכת. המערך כולל את כל הפרמטרים שהוגדרו ב-params (כל אחד מהפרמטרים שמופיע ב-params מוגדר פעם אחת). לכל מחרוזת חייב מפתח תקין בתוך האובייקט params. → For more details see: paramOrder
sets	מערך המכיל סטים	מערך המכיל מפרטי סט. סט הוא קבוצה של פרמטרים שיש להשתמש בהם יחד. ברירת המחדל הוא []. שימו לב שהפונקציונליות של sets עדיין בפיתוח.
format	מחרוזת, inline או block	הגדרה כיצד יש להציג את התבנית בקוד ויקי. ברירת המחדל הוא inline. ראו כאן עבור פורמטים אפשריים אחרים.
maps	אובייקט המכיל מפות	אובייקט שמקשר שם צרכן (כלומר Citoid, Special:MyLanguage/Wikidata וכו') לאובייקט מפה שמקושר לשם פרמטר צרכן לאחד או יותר של פרמטרי התבנית.

פרמטרים

מפתח	סוג	ברירת מחדל	תיאור
label	InterfaceText	null	שם קצר (מאוד) לפרמטר. יש לשמור על פחות מ-20 תווים. → For more details see: label
description	InterfaceText	null	תיאור קצר של הפרמטר, כדי שמשתמשים יוכלו לדעת מה לבחור מרשימת האפשרויות. → For more details see: description
required	בוליאני	false	האם חייב להשתמש בפרמטר כדי שהתבנית תעבוד. → For more details see: required
suggested	בוליאני	false	האם מוצע להשתמש בפרמטר כדי שהתבנית תעבוד. → For more details see: suggested
deprecated	בוליאני או מחרוזת	false	האם הפרמטר הוצא משימוש. הערך יכול להיות מחרוזת שנותנות למשתמש הנחיות מה ניתן לעשות במקום זאת או פשוט true. → For more details see: deprecated
aliases	מערך של מחרוזות	[]	רשימה של כינויים. כינוי הוא שם חלופי לפרמטר שניתן להשתמש בו במקום (לא בנוסף) לשם הראשי. כינויים אינם מתועדים באובייקט כפרמטר נפרד. אם הפרמטר מוגדר כ-deprecated, גם הכינויים שהוגדרו ייחשבו כ-deprecated. → For more details see: aliases
default	InterfaceText	null	הגדרת ערך ברירת מחדל עבור הפרמטר (במידה ולא הוקצה לו ערך). → For more details see: default
autovalue	מחרוזת	null	ערך ברירת מחדל שנוצר באופן דינמי בקוד ויקי, כגון התאריך של היום או שם המשתמש העורך; זה יכלול לעתים קרובות החלפה של קוד ויקי, כגון {{subst:CURRENTYEAR}}. → For more details see: autovalue
example	InterfaceText	null	טקסט לדוגמה לפרמטר, כדי לעזור למשתמשים למלא את הערך המתאים. → For more details see: example
type	מחרוזת	"unknown"	סוג הפרמטר, המרמז לסוג שלו. זה יכול להיות אחד מהבאים: ערך מחרוזת סוג פרמטר "unknown" אם לא מוגדר, יש לשער מה ערכו. → For more details see: value ‘unknown’ "number" כל ערך מספרי (ללא נקודות עשרוניות או פסיקי האלפים) → For more details see: value ‘number’ "string" כל ערך טקסטואלי. עשוי להכיל מעברי שורה. → For more details see: value ‘string’ "line" שדה טקסט קצר - בדרך כלל עבור שמות, תוויות ושדות קצרים אחרים. זה אמור להיות טקסט ללא מעברי שורה. → For more details see: value ‘line’ "boolean" ערך בוליאני (הערך '1' עבור true, הערך '0' עבור false והערך '' עבור לא ידוע); ראו לוגיקה טרינארית. → For more details see: value ‘boolean’ "date" תאריך בפורמט ISO 8601. לדוגמה: "2014-05-09" או "2014-05-09T16:01:12Z". → For more details see: value ‘date’ "url" כתובת URL, כולל פרוטוקול URL. לדוגמה: "http://www.example.org", "https://example.org", או "//example.org". → For more details see: value ‘url’ "wiki-page-name" שם דף חוקי במיזם. הדף לא חייב להיות קיים, אבל אם הוא לא קיים, הוא צריך להיות בעל שם דף חוקי שניתן ליצור. → For more details see: value ‘wiki-page-name’ "wiki-file-name" שם קובץ חוקי במיזם. הקובץ לא חייב להיות קיים, אבל אם הוא לא קיים, הוא צריך להיות בעל שם קובץ חוקי שניתן ליצור. לא צריך לכלול את מרחב השם שלו (לדוגמה: יש להכניס "Foo.svg" ולא "File:Foo.svg" או "קובץ:Foo.svg" או "תמונה:Foo.svg"). → For more details see: value ‘wiki-file-name’ "wiki-template-name" שם תבנית חוקית במיזם. → For more details see: value ‘wiki-template-name’ "wiki-user-name" שם משתמש חוקי במיזם. המשתמש לא חייב להיות קיים, אבל אם הוא לא קיים, הוא צריך להיות בעל שם משתמש חוקי שניתן ליצור. לא צריך לכלול את מרחב השם שלו (לדוגמה: יש להכניס "Foo" ולא "User:Foo" או "משתמש:Foo" או "משתמשת:Foo"). → For more details see: value ‘wiki-user-name’ "content" תוכן עמוד בקוד ויקי, כגון סגנון טקסט, קישורים, תמונות וכו'. → For more details see: value ‘content’ "unbalanced-wikitext" קוד ויקי גולמי שאין להתייחס אליו כאל תוכן עצמאי מכיוון שהוא לא מאוזן - לדוגמה, תבניות המשרשרות קוד ויקי לא שלם כמכלול גדול יותר, כגון {{echo|before=<u>|after=</u>}}. → For more details see: value ‘unbalanced-wikitext’ → For more details see: type
inherits	מחרוזת	כלום ניתן להחלפה	מפתח השם של פרמטר אחר (חייב להיות מפתח חוקי באובייקט params). הפרמרט הנוכחי יירש את המאפיינים של הפרמטר שצוין, כאשר המאפיינים המקומיים יגברו על אלו שעברו בירושה. → For more details see: inherits
suggestedvalues	מערך של מחרוזות	[]	מאפיין פרמטר אופציונלי. יוצר רשימה של ערכי פרמטרים שבהם משתמשים יוכלו לבחור את הערך הרצוי. בכדי שהערכים המוצעים יוצגו ב-VisualEditor, יש להגדיר את סוג הפרמטר לאחד מהערכים הבאים: content line string number unknown unbalanced wikitext → For more details see: suggestedvalues

סטים

מפתח	אובייקט או סוג פרימטיבי	תיאור
label	InterfaceText	שם קצר (מאוד) לקבוצת הפרמטרים. יש לשמור על פחות מ-20 תווים.
params	מערך של מחרוזות	שם אחד או יותר של פרמטרים שיש לכלול בסט (כל אחד מהם חייב להופיע באובייקט params). הפרמטר חייב להיות במספר סטים. לא כל פרמטר חייב להיות מוגדר בסט.

מפות

מפות הוא מבנה נתונים אחד שמגיע לעומק של מספר רמות.

מפתח	סוג	ברירת מחדל	תיאור
שם הצרכן	אובייקט	{}	אובייקט שמקשר שם צרכן לאובייקט מפה שמקושר לשם פרמטר צרכן לאחד או יותר של פרמטרי התבנית. ניתן לציין את פרמטרי התבנית כמחרוזת (שם אחד), מערך של מחרוזות (מספר שמות) או מערך של מערכים של מחרוזות (מספר קבוצות של שמות); כל אחת מהמחרוזות הללו חייבת להיות בעלת מפתח חוקי באובייקט params במקום אחר ב-TemplateData של אותה תבנית. פרמטר תבנית ספציפי עשוי להופיע במספר מפות, והוא עשוי להופיע במספר מרובה של ערכי מפתח במפה נתונה, אך לא כל פרמטר חייב להופיע במפה. הדוגמה המקוצרת הבאה הלקוחה מ-Template:Cite_news#TemplateData מוויקיפדיה האנגלית ממחישה את המבנה של מפות ב-TemplateData. { "proveit": { "main": "title", "textarea": [ "quote" ] }, "citoid": { "title": "title", "url": "url", "publisher": "publisher", "publicationTitle": "work", "date": "date", "ISSN": [ "issn" ], "ISBN": [ "isbn" ], "contributor": "others", "author": [ [ "first", "last" ], [ "first2", "last2" ], [ "first9", "last9" ] ], "editor": [ [ "editor-first", "editor-last" ] ] } }

InterfaceText (מחרוזת או אובייקט)

טקסט חופשי בקוד ויקי או אובייקט המכיל את המחרוזות הללו הממוקמות לפי קוד שפת ויקי.

ערך ברירת המחדל עבור שדות InterfaceText הוא null.

סוג מחרוזת

אם זו מחרוזת, היא חייבת להכיל מחרוזת לא מקומית בשפת התוכן של הוויקי המקומית.

סוג אובייקט

אם זה אובייקט, האובייקט חייב להיות ממופה כך:

מפתח	סוג	תיאור
קוד השפה של מיזם ויקימדיה	מחרוזת	מחרוזת מקומית לשימוש בוויקיפדיה בקוד השפה הקיים.

דוגמה למיפוי שכזה:

מפתח	ערך
"en"	"Welcome to Wikipedia"
"de"	"Willkommen bei Wikipedia"
"fr"	"Bienvenue sur Wikipédia"
"nl"	"Welkom op Wikipedia"
"it"	"Benvenuti su Wikipedia"
"es"	"Bienvenidos a Wikipedia"
"ru"	"Добро пожаловать в Википедию"

דוגמה

להלן דוגמה למבנה TemplateData כפי שנכתב בקוד ויקי של התבנית.

<templatedata>
{
    "description": "Label unsigned comments in a conversation.",
    "params": {
        "user": {
            "label": "User's name",
            "type": "wiki-user-name",
            "required": true,
            "description": "User name of person who forgot to sign their comment.",
            "aliases": ["1"]
        },
        "date": {
            "label": "Date",
            "suggested": true,
            "description": {
                "en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
            },
            "aliases": ["2"],
            "autovalue": "{{subst:#time:Y-m-d}}"
        },
        "year": {
            "label": "Year",
            "type": "number"
        },
        "month": {
            "label": "Month",
            "inherits": "year"
        },
        "day": {
            "label": "Day",
            "inherits": "year"
        },
        "comment": {
            "required": false
        }
    },
    "sets": [
        {
            "label": "Date",
            "params": ["year", "month", "day"]
        }
    ],
    "maps": {
        "ExampleConsumer": {
            "foo": "user",
            "bar": ["year", "month", "day"],
            "quux": [
                "date",
                ["day", "month"],
                ["month", "year"],
                "year"
            ]
        }
    }
}
</templatedata>

להלן כיצד הדוגמה תיראה בדף התבנית.

Label unsigned comments in a conversation.

Template parameters

Parameter		Description	Type	Status
User's name	user 1	User name of person who forgot to sign their comment.	User	required
Date	date 2	Timestamp of when the comment was posted, in YYYY-MM-DD format. Auto value {{subst:#time:Y-m-d}}	Unknown	suggested
Year	year	no description	Number	optional
Month	month	no description	Number	optional
Day	day	no description	Number	optional
comment	comment	no description	Unknown	optional

ממשק תוכנה (API)

לעזרה בנושא ראו Special:ApiHelp/templatedata. קריאה לדוגמה (מעוצבת לקריאות אנושית) היא:

api.php?action=templatedata&titles=Template:Cite%20web&format=json [try in ApiSandbox]

זה מחזיר את נתוני התבנית עבור התבנית Template:Cite web. הבלוק ‎<templatedata>...‎</templatedata> עבור תבנית זו נמצא בדף התיעוד של התבנית.

תוספות ושינויים ל-JSON כפי שהתקבלו מה-API

מבנה ה-JSON שמסופק כחלק מבקשת HTTP Get API שונה באופן משמעותי מזה המוגדר בבלוק ‎<templatedata>...‎</templatedata>. בתגובה לבקשת ה-API, הרחבה TemplateData מבצעת את השינויים הבאים באובייקט JSON:

• מוסיפה שני אובייקטי עטיפה:
  1. אובייקט דפים המכיל לפחות אובייקט עמוד אחד או יותר.
  2. אובייקט עם מפתח מספרי: אובייקט עמוד.
• תוספות/שינויים בפועל לאובייקט TemplateData.
  1. מוסיף את המפתח title עם שם העמוד שממנו נתבקשו הנתונים (למשל "Template:Cite web").
  2. מוסיף את המפתח sets.
  3. משנה את כל מופעי TemplateText שהם רק מחרוזות לאובייקטים עם מפתח יחיד עבור קוד שפת הוויקי של מיזם הוויקימדיה הנוכחי.
  4. מסיר את כל המפתחתות שהוגדרו כ-inherits.
     • מוסיף את כל המאפיינים מפרמטר שממנו הוגדרה ירושה שאינם מוחלפים על ידי מפתחות מוגדרים במפורש בפרמטרים של היורש.
  5. מוסיף ערכי ברירת מחדל עבור כל המפתחות בכל הפרמטרים שלא הוגדרו או לא עברו בירושה.

הבדלים חזותיים באובייקט TemplateData JSON שנמסר על ידי ה-API

אובייקטי עטיפה נוספו ל-JSON שנמסר על ידי ה-API
הם לא מוגדרים באובייקט JSON המוקף בתגיות ‎<templatedata> בדף התבנית.

שורש JSON מפתח סוג תיאור pages אובייקט דף האובייקט Page (מכיל מפתח אחד שהוא מספר העמוד). אם יש יותר מעמוד אחד בבת אחת, יוחזר מספר אובייקטים של Page.

אובייקט דף מפתח סוג תיאור (מספר עמוד) אובייקט TemplateData האובייקט TemplateData מכיל את מטען המידע. המפתח הוא מספר עמוד סטטי עבור דף התבנית שממנו התבקשו נתוני JSON.

אובייקט TemplateData (הוסף על ידי ה-API)
המפתח הבא מתווסף לשורש JSON שמוקף בתגיות ‎<templatedata> בדף התבנית.

מפתח	סוג	תיאור
title	מחרוזת	שם התבנית (לדוגמה: "Template:Cite web"). מפתח זה לא כלול במבנה JSON בדף התבנית. המפתח מתווסף למבנה על ידי תוכנת MediaWiki בדרך למשלוח דרך ה-API.
sets	מערך המכיל סטים	מערך המכיל מפרטי סט. סט הוא קבוצה של פרמטרים שיש להשתמש בהם יחד. אם הסט לא קיים בדף התבנית, הסט מתווסף כמערך ריק למבנה ה-API.

פרמטרים מה-API

מפתח	סוג	תיאור
label	InterfaceText	אם הערך לא נמצא בפורמט, הערך יוגדר כ-InterfaceText.
required	בוליאני	ברירת המחדל הוא false.
description	InterfaceText או null	אם הערך מוגדר כמחרוזת, הערך יוגדר כ-InterfaceText. ברירת המחדל הוא null.
deprecated	בוליאני או מחרוזת	ברירת המחדל הוא false.
aliases	מערך של מחרוזות	ברירת המחדל הוא [] (מערך ריק).
default	מחרוזת	ברירת המחדל הוא "".
type	מחרוזת	ברירת המחדל הוא "unknown".
inherits	(removed)	הגדר מפתחות יורשים עבור מפתח מסוים. מפתחות המוגדרים עבור הפרמטר הנוכחי מקבלים עדיפות וכל מפתח שאינו מוגדר ב-param הנוכחי או אלו שנחשבים יורשים של המפתח יקבלו את ברירת המחדל.

InterfaceText (אובייקט או null):
אובייקט המכיל מחרוזות הממוקמות בקוד שפה.

מפתח	אובייקט או סוג פרימטיבי	תיאור
אובייקט (מכיל מחרוזות מקומיות לפי קוד שפת ויקי) אם השדה TemplateData בדף התבנית מכיל מחרוזת, והוא איננו אובייקט עם מחרוזות מקומיות, MediaWiki מתרגם אותו לאובייקט InterfaceText עם מחרוזת המוקצית לשם המפתח של שפת הוויקי. ברירת המחדל עבור כל השדות של InterfaceText הוא null.
(קוד השפה)	מחרוזת	מחרוזת מקומית לשימוש בוויקיפדיה בקוד השפה הקיים.

דוגמה לאובייקט JSON שמסופק על ידי API

ניתן לראות את אובייקט ה-JSON כפי שמסופר על ידי ה-API עבור המבנה TemplateData שמופיע בפסקה זו (מופיע למעלה):

• בפורמט HTML ראו: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData&format=jsonfm
• כפי שמוצג על פי ה-API ראו: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData

הגדרות

משתנה	ברירת מחדל	תיאור
$wgTemplateDataUseGUI	true	ממשק דו-שיח ניסיוני לעריכת TemplateData ב-JSON

ר' גם

• Extension:TemplateWizard  – ממשק משתמש לבחירה והכנסת קוד ויקי של תבניות, וכל זאת בהתבסס על ה-TemplateData שלהן.
• GitHub: jeblad/TemplateData – גרסה חלופית בסגנון Lua.
• Translatable template
• Wikibase/Maps TemplateData