یک الگو در واقع یک صفحهٔ ویکی‌پدیا است که برای گنجانده‌شدن در صفحه‌های دیگر ایجاد شده‌است. الگوها معمولاً دربردارندهٔ محتوایی تکراری هستند که احتمالاً لازم است در تعدادی از صفحه‌ها یا مقاله‌ها نمایش یابند. از الگوها معمولاً برای پیام‌های تکرارشونده، هشدارها و اعلان‌های استاندارد، جعبه‌های اطلاعات، جعبه‌های ناوبری و مقاصد مشابه دیگر استفاده می‌شود.

معمول‌ترین روش برای گنجاندن یک الگو در صفحه‌ها، تراگنجانش نام دارد. در این روش، ویکی‌متن صفحهٔ مقصد با استفاده از عبارت نحوی {{نام الگو}} شامل ارجاعی به الگو می‌شود. روش دیگر استفاده از الگوها در صفحه‌های دیگر، جانشانی است که در آن، محتوای الگو تنها یک‌بار و فقط در زمان ذخیرهٔ صفحه، به درون ویکی‌متن صفحهٔ مقصد کپی می‌شود.

صفحهٔ راهنما:آموزش سریع الگوها به‌طور مختصر به معرفی این موضوع می‌پردازد. صفحه‌های راهنمای بیشتر در مدیاویکی و ویکی‌مدیا را می‌توانید در صفحه‌های راهنمای الگو در مدیاویکی، راهنمای الگو در فراویکی و راهنمای پیشرفتهٔ الگوها در فراویکی مطالعه کنید.

پیوند الگویی به الگو

ویرایش

برای پیوند دادن به یک الگو در متن صفحه به شکلی که آکولادهای دربرگیرندهٔ آن نیز نمایش یابند، می‌توانید از الگوی الگو استفاده کنید. انگیزهٔ اصلی از انجام این کار، ارائهٔ راهنمای استفاده و درج در توضیحات الگو است. در زیر، نمونه‌ای کوتاه از این نحوهٔ استفاده آمده‌است:

{{الگو|فلان}}
که نتیجه می‌دهد:
{{فلان}}

توصیف کلی

ویرایش
بررسی اجمالی ابتدایی از چگونگی عملکرد الگوها (۸ دقیقه؛ به انگلیسی)

اکثر الگوها صفحه‌هایی در فضای نام الگو هستند. به این معنی که از عنوانی به‌شکل «الگو:فلان» برخوردار هستند. با این حال، تراگنجانش و جانشانی صفحه‌ها از تقریباً هر فضای نام دیگری نیز ممکن است.[الف] بنابراین، برخی صفحه‌های الگو در فضاهای نام دیگر مانند فضای نام کاربر قرار دارند. الگوها دارای یک صفحهٔ بحث وابسته نیز هستند.

الگوها می‌توانند شامل هر گونهٔ دلخواهی از ویکی‌متن، از جمله فراخوانی الگوهای دیگر باشند. ظرفیت‌های برنامه‌نویسی در الگو در بعضی زمینه‌ها دارای محدودیت است؛ از جمله، برای این موارد ظرفیتی محدود وجود دارد: مقادیر قابل تنظیم (که به آن‌ها پارامتر گفته می‌شود)؛ دستورهای محاسبه و انشعاب با استفاده از توابع تجزیه‌گر؛ و دسترسی به متغیرهای خاص ویکی (موسوم به کلمات جادویی) مانند تاریخ، زمان و نام صفحه‌ها. الگوها همچنین می‌توانند از برچسب‌های اچ‌تی‌ام‌ال برای مشخص کردن بخش‌هایی از ویکی‌متن استفاده کنند تا این بخش‌ها در زمان تراگنجانش یا جانشانی الگو مشخص شوند. مجموع این موارد باعث می‌شود که گاهی ظاهر صفحهٔ خود الگو با محتوایی که پس از تراگنجانش آن به دست می‌آید، یکسان نباشد (برای مثال، صفحهٔ الگو می‌تواند شامل توضیحات الگو، رده‌ها و مواردی دیگر تنها برای خود الگو باشد که در صفحه‌های محلِ کاربرد الگو، دیده نخواهند شد).

نحوهٔ استفاده از الگوها: برای تراگنجانش یک الگو در یک مقاله یا صفحهٔ دیگر، عبارت {{نام الگو}} را در ویکی‌متن صفحه و در جای مورد نظر برای نمایش الگو تایپ کنید. در صورتی که عنوان الگو با حروف انگلیسی است، فرقی نمی‌کند که حرف اول عنوان آن را با حروف بزرگ بنویسید یا حروف کوچک.

پیشوند الگو: که پیش از نام الگو قرار دارد، پیشوندی پیش‌فرض است و لازم نیست در زمان تراگنجانش درج شود. با این حال، در زمان استفاده از الگوهای قرارگرفته در فضاهای نام دیگر، پیشوندهایی نظیر کاربر: باید در زمان استفاده از الگو درج شوند (مثلاً {{کاربر:فلانی/جعبه کاربر}}. برای تراگنجانش صفحه‌ای که در فضای نام اصلی قرار دارد، پیش از عنوان صفحه یک علامت دونقطه «:» قرار دهید (مثال: {{:نام صفحه}}).

  یادداشت: اقدام به تراگنجانش الگویی که وجود ندارد، درست مشابه پیونددهی به هر صفحهٔ ناموجود دیگر، منجر به تولید یک پیوند قرمز می‌شود. دنبال‌کردن این پیوند قرمز، امکان ایجاد آن الگوی خاص را فراهم می‌کند. تراگنجانش صفحه‌ها میان پروژه‌های مختلف امکان‌پذیر نیست (مثلاً میان نسخه‌های زبانی مختلف ویکی‌پدیا یا از ویکی‌پدیا به ویکی‌کتاب)، برای استفاده از یک الگو در یک پروژهٔ زبانی دیگر، یک نسخه از همان الگو باید در آن پروژه نیز ایجاد شود.

نحوه استفاده

ویرایش

پارامترها

ویرایش

نحو ابتدایی برای تراگنجانش الگوها که در بالا به آن اشاره شد، می‌تواند با افزوده‌شده پارامترها گسترش یابد. این پارامترها برای کنترل‌کردن خروجی الگو کاربرد دارند. نحو الگوها با استفاده از پارامترها به‌صورت زیر است: {{نام الگو|پارامتر|پارامتر|...}}. مثلاً اگر الگویی به اسم «جمع» داشته باشیم که پارامترهایی عددی بگیرد و مجموع آن‌ها را برگرداند، کاربرد چنین الگویی می‌تواند به این شکل باشد: {{جمع|۱۲|۸|۴۹}} و خروجی الگو هم فرضاً ۶۹ خواهد بود.

در نحو الگوها، پارامتر می‌تواند تنها شامل یک مقدار باشد (که به این نوع پارامترها پارامترهای نام‌گذاری‌نشده می‌گویند) یا شامل نام و مقدار پارامتر باشد، به‌شکل نام=مقدار که به آن پارامترها نام‌گذاری‌شده می‌گویند. در واقع، پارامترهای نام‌گذاری‌نشده به صورت خودکار نامگذاری می‌شوند و نامشان با اعداد لاتین 1، 2، 3 و الی آخر نیز مورد استفاده است. به بیان دیگر، دستور الگویی که بالاتر نوشته شده، در اصل از دید نرم‌افزار معادل {{جمع|1=۱۲|2=۸|3=۴۹}} است.

توجه کنید که الگوها می‌توانند از ترکیبی از پارامترهای نامگذاری‌شده و پارامترهای نام‌گذاری‌نشده استفاده کنند. در دستوری شبیه به {{الگو|نام=فلان|سن=بهمان|بسیار}}، دو پارامتر نام‌گذاری‌شده به کار رفته‌اند و یک پارامتر نام‌گذاری‌نشده. پارامترهای نام‌گذاری‌نشده به ترتیب شماره می‌خورند و در این شماره‌گذاری، پارامترهای نام‌گذاری‌شده نادیده گرفته می‌شوند. در مثال بالا، بیسار مقدار پارامتر 1 خواهد بود، نه مقدار پارامتر 3، چون اولین پارامتر نام‌گذاری‌نشده‌ای است که فراخوانی شده‌است.

نویسه‌های فاصله خالی (فاصله‌ها، جهش‌ها، سرخط) از ابتدا و انتهای نام و مقادیر پارامترهای نام‌گذاری‌شده جدا می‌شوند، اما این اتفاق در میانهٔ عبارت رخ نمی‌دهد: بنابراین {{... | پارامتر = این یک آزمایش است}} دارای تأثیری یکسان با {{... |پارامتر=این یک آزمایش است}} خواهد بود. این قاعده به پارامترهای نام‌گذاری‌نشده، که در آن‌ها تمامی نویسه‌های فاصله خالی محفوظ هستند، اعمال نمی‌شود.

آن که چه پارامترهایی (در صورت وجود) می‌توانند یا باید به یک الگو داده شوند و چگونگی نام‌گذاری آن‌ها، بستگی به نحوهٔ کدنویسی آن الگو دارد. پارامترهای نام‌گذاری‌شده را به هر ترتیبی می‌توان تعریف کرد. از پارامترهای زائد یا پارامترهایی با نام‌گذاری بد چشم‌پوشی خواهد شد؛ پارامترهای تعریف‌نشده با مقادیر پیش‌فرض پر می‌شوند. یک یک پارامتر بیش از یک‌بار تعریف شده‌باشد، آخرین مقدار وارد شده برای آن در نظر گرفته خواهد شد.

مقدار یک پارامتر می‌تواند یک می‌تواند یک رشتهٔ خالی باشد؛ به این معنا که بلافاصله پس از نویسهٔ خط عمودی یا علامت مساوی، خط عمودی بعدی یا آکولادهای پایانی الگو قرار گیرند. این، با چشم‌پوشی کلی از یک پارامتر، که درواقع به‌عنوان پارامتر تعریف‌نشده در نظر گرفته می‌شود، متفاوت است؛ با این حال، الگوها معمولاً به گونه‌ای نوشته می‌شوند که در هر دو حالت رفتاری یکسان از خود نشان دهند.

حتی در صورتی که پارامترها در کد الگو تعریف نشده‌باشند، می‌توان آن‌ها را در زمان استفاده از الگو به‌کار برد (هرچند که نتیجه‌ای نخواهند داد). برای مثال، در ویکی‌نبشته پارامتر |reason= غالباً به‌عنوان یک شبه‌پارامتر و به‌منظور ارائهٔ یک توضیح مختصر برای دلیل به‌کارگیری الگو استفاده می‌شود.[ب] برخی الگوها، پودمان بررسی پارامترهای نامعلوم را فراخوانی می‌کنند تا به ویرایشگر هشدار دهند که یکی از پارامترهایی که در حال استفاده از آن است، در کدهای الگو تعریف نشده‌است؛ این قابلیت بیشتر در جعبه‌های اطلاعات و سایر الگوهایی که تعداد زیادی پارامترهای پیچیده دارند، کاربرد دارد که در آن‌ها وجود یک پارامتر ناشناخته معمولاً حاصل خطای غیرعمدی است. در صورتی که چنین الگویی را برای افزودن یک پارامتر جدید به‌روزرسانی کردید، فراخوانی پودمان در الگو نیز برای دربرگرفتن پارامتر جدید باید به‌روز شود.

فراخوانی

ویرایش

استفاده از یک الگو دارای شباهت زیادی به فراخوانی یک تابع در زبان‌های برنامه‌نویسی است، چرا که فراخواندن آن، مقداری (خروجی) را برمی‌گرداند. همچنین بعضی الگوها، مشابه توابع، پارامترهایی که باعث تغییر خروجی می‌شوند را می‌پذیرند.

ویکی‌پدیا با استفاده از نرم‌افزار مدیاویکی درست شده‌است. در مدیاویکی متغیرها دارای معنایی اختصاصی‌تر هستند که آن‌ها را از الگوها متمایز می‌سازد، اما هردوی آن‌ها با آکولادهای دوقلو {{}} شناسایی می‌شوند و هردوی آن‌ها قادر به برگرداندن مقدار هستند.

نام همهٔ متغیرهای مدیاویکی در اصلی به انگلیسی است و تماماً با حروف بزرگ نوشته می‌شود (مثل متغیر {{PAGENAME}} که نام صفحه را بر می‌گرداند). با این حال برای نام متغیرها، معادل فارسی نیز ساخته شده‌است؛ مثلاً {{نام‌صفحه}} مترادف {{PAGENAME}} است. در مقایسه، نام الگوها از همان ویژگی‌های ابتدایی و محدودیت‌هایی برخوردار است که به نام صفحه‌ها نیز اعمال می‌شود: این نام‌ها به بزرگی و کوچکی حروف حساس هستند (به‌جز نویسهٔ اول نام)؛ زیرخط‌ها، همانند فاصله‌ها تجزیه می‌شوند؛ و نام الگوها نمی‌تواند شامل این نویسه‌ها باشد: # < > [ ] | { }. دلیل این محدودیت این است که این نویسه‌ها از پیش برای نشانه‌گذاری ویکی و اچ‌تی‌ام‌ال کنار گذاشته شده‌اند.

علامت مربع # با عنوان یک شناسهٔ قطعه شناخته می‌شود؛ چرا که برای مشخص‌کردن یک قطعه یا یک بخش از یک سند (مانند بخشی در یک مقالهٔ ویکی‌پدیا) به‌کار می‌رود. اگرچه از این نویسه برای پیوند دادن به یک بخش از صفحهٔ الگو می‌توان استفاده کرد (مانند الگو:درگاه#مثال)، اما دلیلی برای قرار دادن یک شناسهٔ قطعه یا نام یک قطعه در ارجاع به الگو وجود ندارد. به‌عنوان مثال، در عبارت {{درگاه#مکان|کتاب}}، رشتهٔ #مکان کاربردی ندارد و در نتیجه از آن صرف نظر خواهد شد.

جانشانی

ویرایش

هنگامی که یک الگو جانشانی شود، محتوای آن به‌جای تراگنجانش، در صفحه سخت‌نویسی می‌شوند. برای آگاهی از چگونگی و زمان مناسب برای جانشانی یک الگو، راهنما:جانشانی را ببینید.

نمونه‌های ابتدایی از کاربرد الگوها

ویرایش

  یادداشت: اگر قصد دارید هر یک از این نمونه‌ها را آزمایش کنید، لطفاً از صفحهٔ تمرین الگو یا یکی از زیرصفحه‌های کاربری خودتان مانند صفحهٔ تمرین‌تان استفاده کنید.

الگو:لامبدا یک نمونهٔ بسیار ساده از الگوها است که برای قرار دادن نماد لامبدا (λ) در محل فراخوانی خود در متن صفحه به‌کار می‌رود. در میان برنامه‌نویسان، این‌طور گفته می‌شود که الگو، نماد لامبدا (λ) را برمی‌گرداند.

روی الگو:لامبدا کلیک کرده و در صفحهٔ الگو روی زبانهٔ «ویرایش متنی» در بالای صفحه کلیک کنید تا کد الگو (ویکی‌متن آن) را مشاهده کنید. بخش «فعال» کد که با عنوان بسط الگو شناخته می‌شود، عبارت &lambda; است.[پ] باقی ویکی‌متن الگو نیز با برچسب‌های <noinclude> محصور شده‌است تا در صفحهٔ خود الگو نمایش یابد، اما در زمان استفاده (یا فراخوانی) الگو در صفحه‌ای دیگر، نمایش داده نشود.

برای تراگنجانش الگو:لامبدا در یک صفحهٔ دیگر (یعنی استفاده از الگو در صفحهٔ دیگر)، عبارت {{لامبدا}} را در ویکی‌متن صفحهٔ مقصد تایپ کرده و دکمهٔ پیش‌نمایش را فشار دهید. پس از آن، پیش‌نمایشی از صفحه نمایش خواهد یافت که در آن فراخوانی الگو با بسط آن جایگزین شده‌است؛ به‌گونه‌ای که گویی متن صفحه دربردارندهٔ &lambda; در محل قرارگیری الگو باشد. صفحهٔ نمایش‌یافته متعاقباً شامل متن «λ» خواهد بود. برای الگوها می‌توان تغییرمسیر هم ایجاد کرد. مثلاً الگو:Lambda تغییرمسیری به الگو:لامبدا است در نتیجه استفاده از دستور {{lambda}} یا {{Lambda}} نیز نتیجه‌ای مشابه استفاده از دستور {{لامبدا}} ایجاد می‌کند. توجه کنید که بزرگی و کوچکی حرف اول نام الگو تفاوتی ایجاد نمی‌کند.

برای تمرین، عبارت یازدهمین حرف از الفبای یونانی لامبدا ({{لامبدا}}) است را تایپ کنید تا در زمان پیش‌نمایش صفحه، یا پس از ذخیره‌کردن تغییرات، عبارت «یازدهمین حرف از الفبای یونانی لامبدا (𝜆) است» را مشاهده کنید. شما می‌توانید بدون اطلاع از جزئیات کد الگوها از آن‌ها استفاده کنید؛ تنها لازم است که آنچه الگو تولید می‌کند و معمولاً در صفحهٔ خود الگو توضیح داده شده‌است را به‌یاد داشته باشید.

راهی دیگر برای استفاده از این الگو، جانشانی کردن آن است. اگر عبارت یازدهمین حرف از الفبای یونانی لامبدا ({{جا:لامبدا}}) است را تایپ کنید و پیش‌نمایش را بفشارید یا صفحه را ذخیره کنید، باز هم جملهٔ «یازدهمین حرف از الفبای یونانی لامبدا (λ) است» را مشاهده خواهید کرد. اما اگر پس از ذخیره کردن صفحه، دوباره به ویکی‌متن ذخیره‌شده بنگرید،[ت] خواهید دید که وقتی صفحه را ذخیره کردید، فراخوانی‌های الگو به‌واقع با بسط الگو جایگزین شده‌اند. جانشانی الگو باعث می‌شود که پیوند میان متن خروجی و صفحهٔ الگو شکسته شود؛ در نتیجه اگر در آینده دستور الگو تغییر یابد، آن تغییرات در صفحه‌هایی که پیشتر الگو در آن‌ها جانشانی شده منعکس نخواهند شد.

نمونه‌هایی همراه با پارامتر

ویرایش

الگوی {{درباره}} نمونه‌ای است از یک الگو که پارامتر نیز می‌پذیرد. نوشتن عبارت {{درباره|چگونگی استفاده از الگوها|شیوهٔ استفاده از پودمان‌ها|راهنما:پودمان}} در صفحهٔ تمرین را امتحان کنید نتیجهٔ آن، متن زیر خواهد بود:

در مثال بالا، الگوی {{درباره}} از سه پارامتر نام‌گذاری‌نشده استفاده می‌کند، اما همین الگو را می‌توان با تعداد مختلفی از پارامترها نیز استفاده کرد که نتیجهٔ آن، مطابق با آنچه در مستندات این الگو آمده، اندکی متفاوت خواهد بود. به‌عنوان نمونه: {{درباره||شیوهٔ استفاده از پودمان‌ها|راهنما:پودمان}}. به کاربرد یک پارامتر خالی در این نمونه دقت کنید. نویسه‌های | که خط عمودی نامیده می‌شوند، اسم الگو را از پارامترهایش و پارامترها را از همدیگر جدا می‌کنند. جایی که دو خط عمودی متوالی می‌بینید به این معنی است که نخستین پارامتری که به الگو «فرستاده شده» یک رشتهٔ خالی است؛ خالی بودن پارامتر اول در این الگو منجر به چشم‌پوشی از جملهٔ «درباره» در ابتدای خروجی الگو خواهد شد. فراخوانی الگو به این شکل، این عبارت را تولید خواهد کرد:

سایر الگوها، به‌ویژه آن‌هایی که پیچیده‌تر هستند، پارامترهای نام‌گذاری‌شده یا ترکیبی از پارامترهای نام‌گذاری‌شده و نام‌گذاری‌نشده را می‌پذیرند. الگو:ماتریس بازده نمونه‌ای ساده از این گونه از الگوها است که برای ایجاد یک جدول دو در دو به‌کار می‌رود. برای مثال:

نشانه‌گذاری نمایش
{{ماتریس بازده| بالاراست = ۷ | بالاچپ = ۵ | پایین‌راست = ۹ | پایین‌چپ = ۲ | نام = استفادهٔ آموزشی}}
راست چپ
بالا ۷ ۵
پایین ۹ ۲
استفادهٔ آموزشی

برای آگاهی از قابلیت‌های بیشتر الگو، صفحهٔ الگو را ببینید. دقت کنید که این الگو در اینجا بدون تعریف‌کردن تمام قابلیت‌های آن به‌کار رفته‌است، پارامترهای تعریف‌نشده، مقدارهای پیش‌فرض خود را به‌کار خواهند گرفت.

فاصله‌های به‌کار رفته در اطراف علامت‌های مساوی و پیش و پس از پارامترها تنها برای وضوح بیشتر استفاده شده‌اند استفاده از این فاصله‌ها الزامی نیست و در زمان ارزیابی الگو از آنها چشم‌پوشی می‌شود (اگرچه چنین چیزی در خصوص پارامترهای نام‌گذاری‌نشده صادق نیست). دقت کنید که نام پارامترها به بزرگی و کوچکی حروف حساس هستند. به‌عنوان مثال، در نمونهٔ بالا به‌جای پارامتر |پایین‌راست= می‌توان از |DR= (نمایندهٔ Down Right) نیز استفاده کرد. اما استفاده از dr یا dR به‌جای آن، امکان‌پذیر نیست. از پارامترهایی که نام آن‌ها مورد استفادهٔ الگو قرار نگرفته‌باشد، به‌سادگی چشم‌پوشی می‌شود.

با بررسی متن مبدأ الگو، نشانه‌گذاری استاندارد جدول را به‌همراه تعدادی آکولادهای سه‌قلو مشاهده خواهید کرد که مشخص‌کنندهٔٔ پارامترها هستند:

{| id="Payoff matrix" style=" float: {{{Float|left}}}; clear:left; text-align:center;" align={{{Float|left}}} cellspacing=0 cellpadding=8 width={{{Width|225}}}
|-
|style="width:33%;                                                     "|
|style="width:33%;                      border-bottom: solid black 1px;"| {{{2R|راست}}}
|style="width:33%;                      border-bottom: solid black 1px;"| {{{2L|چپ}}}
|-
|style="border-left:  solid black 1px; text-align: left;             "| {{{1U|بالا}}}
|style="border-left:  solid black 1px; border-bottom: solid black 1px;  font-size:120%; "| {{{UR|۰، ۰}}}
|style="border-left:  solid black 1px; border-bottom: solid black 1px;  font-size:120%; "| {{{UL|۰، ۰}}}
|-
|style="border-left:  solid black 1px; text-align: left;             "| {{{1D|پایین}}}
|style="border-left:  solid black 1px; border-bottom: solid black 1px;  font-size:120%; "| {{{DR|۰، ۰}}}
|style="border-left:  solid black 1px; border-bottom: solid black 1px; font-size:120%; "| {{{DL|۰، ۰}}}
|-
|style="font-size: 90%;" colspan=3 |''{{{Name| {{PAGENAME}} }}}''
|}

عبارت {{{2L|چپ}}} به الگو می‌گوید که از پارامتر نام‌گذاری‌شدهٔ 2L استفاده کند و در صورت موجود نبودن آن در فراخوانی الگو، متن چپ را نمایش دهد. توجه کنید که چون رابط کاربری ویکی‌پدیای فارسی «راست به چپ» است، در نتیجه شما دستور را در صفحهٔ ویرایش الگو به این شکل خواهید دید: {{{2L|چپ}}}. این پارامتر و سایر پارامترها در متن اصلی الگو در واقع به‌شکل {{{2L|{{{۲چ|چپ}}}}}} آمده‌اند که در ادامه و در بخش § ایجاد و ویرایش الگوها در خصوص آن‌ها توضیح داده خواهد شد.

نکات و راه‌کارهای استفاده

ویرایش

توجه به نکات زیر در زمان استفاده از الگوها می‌تواند مفید باشد:

  • پارامترهای نام‌گذاری‌نشده نمی‌توانند دربردارندهٔ علامت مساوی به‌شکل معمول خود باشند؛ چرا که این کار می‌تواند به تفسیر پارامتر مورد نظر به‌عنوان یک پارامتر نام‌گذاری‌شده منجر شود.[ث] برای فرستادن یک علامت مساوی به یک پارامتر نام‌گذاری‌نشده (مثلاً در یک نشانی اینترنتی دارای جفتِ ویژگی–مقدار)، علامت مساوی را با الگوی ویژهٔ {{=}} جایگزین کنید. این الگوی ویژه یک علامت مساوی را برمی‌گرداند که توسط توابع تفسیر نخواهد شد. شیوه‌ای دیگر برای این کار این است که پارامتر نام‌گذاری‌نشده (و هرگونه پارامتر نام‌گذاری‌نشده دیگری) را با پارامترهای نام‌گذاری‌شده جایگزین کنید، پارامتر نام‌گذاری‌نشده اول برابر است با پارامتر نام‌گذاری‌شده |۱= و باقی پارامترهای موضعی نیز به همین ترتیب می‌توانند نام‌گذاری شوند. برای فراخوانی {{شد}} با عبارت الف=ب به‌عنوان مقداری دقیق برای پارامتر موضعی اول، یکی از عبارت‌های {{شد|الف{{=}}ب}} یا {{شد|1=الف=ب}} را تایپ کنید.
  • به‌طور مشابه، امکان استفاده از نویسهٔ لوله | نیز در پارامترهای الگوها وجود ندارد؛ چرا که استفاده از آن باعث تفسیر شدنش به‌عنوان یک جداکننده می‌شود.[ج] این‌بار مشکل را می‌توان با استفاده از واژهٔ جادویی {{!}} به‌جای نویسهٔ لوله یا در صورتی که بنا نباشد لوله در سطحی بالاتر تجزیه شود، با استفاده از نهاد اچ‌تی‌ام‌ال&#124;‎ حل کرد. متناوباً برای تعبیه‌کردن یک جدول‌های ویکی در الگوها، به‌منظور جلوگیری از استفادهٔ بیش از اندازه از {{!}} می‌توانید از {{جدول ویکی}} استفاده کنید.
  • به‌یاد داشته باشید که نویسه‌های فاصله خالی (فاصله‌ها، جهش‌ها، سرخط و نوخط)، برخلاف پارامترهای نام‌گذاری‌شده، به‌طور خودکار از ابتدا و انتهای پارامترهای نام‌گذاری‌نشده جدا نمی‌شوند. علاوه بر این، چنین نویسه‌هایی (یا هرگونه پارامتر ناپیدا در هر یک از پارامترها) در برخی موارد ممکن است به شیوه‌هایی غیرقابل پیش‌بینی بر روی رفتار الگو اثر بگذارند. (طراحان الگو می‌توانند برای حذف فاصله‌های خالی ناخواسته در پارامترهای نام‌گذاری‌نشده، از {{حذف فاصله خالی}} استفاده کنند)
  • در مستندات الگوها و گفتگوها، معمولاً خوب است که بتوان نحو فراخوانی الگو را به‌همراه پیوندی به الگوی مورد بحث بدون فراخوانی آن در صفحهٔ حاضر ایجاد کرد. این کار را می‌توان به‌راحتی و با استفاده از الگوی {{الگو}} (یا {{tl}} که نمایندهٔ «template link» است) انجام داد. برای مثال، {{الگو|نمونه}} نتیجه می‌دهد: {{نمونه}}. چندین الگوی پیونددهی به الگو نیز با عملکردهای متفاوت در دسترس هستند.
  • هرگاه یک الگو تغییر کند (هرگاه یک الگو یا یکی از الگوهای زیرین و وابسته به آن ویرایش شود)، این تغییر در تمام صفحه‌هایی که الگو در آن‌ها تراگنجانش شده انعکاس خواهد یافت. با این حال، ممکن است این تغییر بلافاصله در تمام صفحه‌ها قابل مشاهده نباشد؛ ممکن است نسخه‌ای از پیش ذخیره‌شده از صفحه که از نسخهٔ پیشین الگو استفاده می‌کرده‌است، برای مدتی همچنان نمایش یابد. برای اجبار صفحه به نمایش با استفاده از آخرین نسخهٔ الگوها، از تابع خالی‌کردن میانگیر استفاده کنید، از جمله در صفحهٔ خود الگو در صورت وجود نمونه‌های کاربرد در توضیحات.
  • در زمان مشاهدهٔ نسخه‌های قدیمی صفحه‌ها، به یاد داشته باشید که الگوها به شکل کنونی‌شان نمایش خواهند یافت؛ نه لزوماً به‌شکلی که در زمان فعال بودن نسخهٔ قدیمی صفحه به آن شکل بوده‌اند.
  • برای فهرست‌کردن تمام صفحه‌هایی که یک الگو در آن‌ها تراگنجانش شده‌است، از پیوندها به این صفحه در صفحهٔ خود الگو استفاده کنید. این فهرست شامل صفحه‌هایی که الگو در آن‌ها جانشانی شده‌است نخواهد بود.
  • برای مشاهدهٔ فهرستی از الگوهای تراگنجانش‌ شده در یک صفحه، روی زبانهٔ «ویرایش متنی» کلیک کنید تا فهرست الگوها را در پایین جعبهٔ ویرایش مشاهده کنید. این فهرست شامل زیرالگوهای مورد استفادهٔ الگوهایی که به‌طور مستقیم تراگنجانش شده‌اند نیز می‌شود. برای گرفتن چنین فهرستی تنها برای بخشی از صفحه، یک نسخهٔ قدیمی از صفحه،[چ] یا نسخه‌ای که اخیراً ویرایش کرده‌اید و هنوز ذخیره نشده، روی دکمهٔ پیش‌نمایش در صفحهٔ ویرایش متناسب کلیک کنید و فهرست به‌روز شده در پایین جعبهٔ ویرایش را مشاهده کنید.
  • برای تعداد و پیچیدگی الگوهایی که یک مقاله می‌تواند در خود داشته‌باشد، محدودیت‌هایی وجود دارد. برای حل این موضوع، بخش «§ محدودیت‌های بسط» را ببینید.
  • اگر می‌خواهید که الگو یک برچسب زمانی یا امضا برجای بگذارد، می‌توانید عبارت <noinclude><nowiki></noinclude>~~~~~<noinclude></nowiki></noinclude> را تایپ کنید، اما این تنها در صورتی کارساز خواهد بود که الگو را جانشانی کنید. اگر آن را تراگنجانش کنید، فقط عبارت ~~~~~ برگردانده خواهد شد.
  • معمولاً برنامه‌نویسان برای خواندنی‌تر کردن کدهای خود عادت دارند که کد را با استفاده از خطوط مجزا خلوت‌تر کنند و به آن دندانه بدهند. متأسفانه نرم‌افزار مدیاویکی امکان چنین کاری را فراهم نمی‌کند؛ در بسیاری از موارد، این خطوط جدید که برای کاربردهایی خاص ایجاد شده‌اند، از سوی نرم‌افزار به‌عنوان محتوا شناسایی می‌شوند. یکی از راه‌کارهای موجود برای انجام این کار، افزودن <!-- پیش از هر یک از نویسه‌های سرخط (return یا enter) و --> پس از آن است که یک کامنت اچ‌تی‌ام‌ال را تولید می‌کند.

ایجاد و ویرایش الگوها

ویرایش

ایجاد و ویرایش الگوها بسیار شبیه به ایجاد ویرایش هر صفحهٔ دیگری در ویکی‌پدیا است: یک نام مناسب را انتخاب کنید، به صفحه بروید، و بر حسب نیاز بر روی «ویرایش» کلیک کنید یا این که صفحه را ایجاد کنید. همان‌طور که در بالا گفته‌شد، الگوها معمولاً در فضای نام الگو قرار می‌گیرند، با این حال، الگوهایی که برای استفادهٔ شخصی خودتان یا برای مقاصد تمرینی و آزمایشی ایجاد می‌کنید را می‌توانید در فضای کاربری خودتان بسازید. هرآنچه که بتواند در یک صفحه یا مقالهٔ معمولی درج شود، می‌تواند در یک الگو نیز قرار گیرد. از جمله الگوهای دیگر (شناخته‌شده با نام زیرالگو). الگوها معمولاً از ویژگی‌ها، پارامترهای برنامه‌نویسی، توابع تجزیه‌گر، و سایر کلمات جادویی استفاده می‌کنند که تنوع محتوای تراگنجانش‌ شده بر پایه موضوع را ممکن می‌سازد.

پیش از ایجاد یک الگوی تازه، جستجوی مختصر برای الگوهای موجود انجام دهید (مثلاً با بررسی رده:الگو:ویکی‌پدیا). ممکن است الگویی از پیش موجود باشد که همان کاری که شما مد نظر دارید را انجام دهد یا الگویی مشابه وجود داشته‌باشد که بتوانید کد آن را کپی کرده و تغییر دهید (یا آن را در همان جای خود باقی بگذارید و فقط آن را گسترش دهید). به‌دنبال الگوهای عمومی باشد که الگوی تازه بتواند بر پایه آن ساخته‌شود؛ برای مثال، الگوهای جعبه ناوبری را می‌توان به راحتی با فراخوانی الگو:Navbox ایجاد کرد.

قاعدهٔ سخت‌گیرانه‌ای برای انتخاب نام یک الگو وجود ندارد، نامی کوتاه انتخاب کنید که در عین حال عملکرد الگو را به خوبی توصیف کند. اگر الگوهایی مشابه موجود هستند، سعی کنید از قالبی مشابه و پایدار برای نام‌گذاری پیروی کنید. نام الگوها را می‌توان با برجای گذاشتن یک تغییرمسیر به نام جدید الگو در زمان انتقال، بدون شکستن تراگنجانش‌های موجود تغییر داد.

در زمان ویرایش الگوهای موجود بسیار محتاط باشید، تغییرات اعمال‌شده در الگوها می‌تواند بر تعداد زیادی صفحه و معمولاً به‌شکلی که انتظارش را ندارید، تأثیر بگذارد. به‌همین دلیل، بسیاری از الگوهای پرکاربرد به‌گونه‌ای در مقابل ویرایش حفاظت شده‌اند که تنها توسط مدیران و ویرایشگران الگو قابل ویرایش باشند؛ سایر ویرایشگران می‌توانند در صفحهٔ بحث الگو درخواست ویرایش دهند. برخی الگوها برای انجام ویرایش‌های آزمایشی و آزمودن ویرایش‌های جدید در صفحه‌ها، دارای یک صفحهٔ تمرین و نمونه‌های آزمایشی هستند.

برای پیشنهاد حذف یا ادغام الگوهای بدون استفاده یا نامناسب، یا الگوهایی که به‌سادگی می‌توانند ادغام شوند، الگو را در نظرخواهی برای حذف نامزد کنید.

کار با پارامترها

ویرایش

مقدارهای پارامترهایی که می‌توانند به یک الگو خورانده شوند، در کد الگو به‌شکل موردهایی قرارگرفته در میان آکولادهای سه‌قلو تعریف می‌شوند:

  • کد {{{فلان}}} با مقداری که به پارامتری با نام فلان داده می‌شود، جایگزین خواهد شد. این پارامترها با نام پارامترهای نام‌گذاری‌شده شناخته می‌شوند.
  • کدهای {{{1}}}، {{{2}}} و سایر پارامترهایی که به‌صورت اعداد لاتین تعریف می‌شوند، با مقدار وارد شده در پارامتر نام‌گذاری‌نشدهٔ اول، دوم و غیره (یا مقدار پارامتر 1، 2، و غیره) جایگزین می‌شوند؛ این پارامترها با نام پارامترهای موضعی شناخته می‌شوند.

اگر یک پارامتر فاقد مقدار باشد، هیچ جایگزینی انجام نخواهد شد؛ به این معنی که اگر مقداری به پارامتر |فلان= فرستاده نشده‌باشد، مقدار عبارت {{{فلان}}} در درون الگو عیناً برابر با {{{فلان}}} خواهد بود و نه آن فضای «خالی» که انتظارش را دارید. رفتار قابل لمس‌تر الگو می‌تواند با تعریف مقدارهای پیش‌فرض برای پارامترها حاصل شود. این کار را می‌توان با نحو لوله‌ای انجام داد: {{{فلان|پیش‌فرض}}} که مقدار پیش‌فرض پیش‌فرض را برای پارامتر نام‌گذاری‌شده |فلان= تعریف می‌کند و {{{1|پیش‌فرض}}} که مقدار پیش‌فرض پیش‌فرض را برای پارامتر نام‌گذاری‌نشده اول تعریف می‌کند. در اغلب اوقات، از این قابلیت برای تعریف‌کردن مقدارهای پیش‌فرض خالی، نظیر {{{1|}}} یا {{{فلان|}}} استفاده می‌شود.

نام‌های مستعار پارامترها حالتی ویژه از مقدارهای پیش‌فرض هستند. برای مثال، اگر پارامتر |۱=، |متن= و |پیام= همگی نامی برای یک پارامتر باشند، ویکی‌متن {{{پیام|{{{متن|{{{1|}}}}}}}}} را می‌توان به‌کار گرفت. اگر بیشتر از یکی از این پارامترها دارای مقدار باشد، آنگاه پارامتر پیام اولویت خواهد داشت و پس از آن متن و در نهایت نخستین پارامتر نام‌گذاری‌نشده دارای اولویت خواهند بود. به این معنی که اگر پارامترهای |پیام=الف|متن=ب به الگوی دارندهٔ این ویکی‌متن فرستاده شود، ویکی‌متن الگو به‌شکل الف بسط خواهد یافت.

به‌دلیل استفاده‌های چندباره از نحو دارای آکولادها دوقلو و سه‌قلو، عبارت‌های بعضی مواقع ممکن است ابهام‌دار باشند. برای حل این ابهام، قرار دادن فاضله میان این آکولادها می‌تواند مفید باشد. برای مثال، {{{{{فلان}}} }} یا {{{ {{فلان}} }}} به‌جای درج پنج آکولاد متوالی، می‌تواند برای انسان بیشتر قابل خواند باشد. با این حال، دقت کنید که فاضلهٔ خالی ناخواسته ممکن است در زمان بسط الگو در خروجی آن نمایش داده شود.

مورد ویژه: پارامترهای درون برچسب‌های گشاینده به‌سبک XML

ویرایش

پارامترها، در صورتی که در ماین برچسب‌های <nowiki> قرار گیرند، بسط نخواهد یافت. به‌طور مشابه، پارامترها در صورت قرار گرفتن در یک برچسب گشایندهٔ واقعی به‌سبک اکس‌ام‌ال نیز بسط نمی‌یابند. ار این روی، عبارت زیر اگر در یک الگو قرار گیرد، کار نخواهد کرد:

  • <ref name={{{param}}}>Smith, Adam (1776)...</ref>

چرا که پارامتر وارد شده در برچسب بسط نخواهد یافت. در عوض، می‌توانید از تابع تجزیه‌گر{{#tag:}}‎ استفاده کنید که برای مثال در {{sfn}} و به‌منظور ایجاد عنصر <ref>...</ref> به‌کار رفته‌است؛ همچنین راهنما:کلمات جادویی § قالب‌بندی را ببینید؛ بنابراین، نمونهٔ زیر به‌خوبی کار خواهد کرد:

  • {{#tag:ref | Smith, Adam (1776)... | name={{{param}}} }}

هشدار: گسترش بیش از حد نشانی‌های اینترنتی

ویرایش

اگر مقدار یک پارامتر یک نشانی اینترنی است (یا به آن ختم می‌شود)، با افزودن یک یا چند نویسه به انتهای نشانی اینترنتی–که باعث می‌شود کلیک‌کردن روی پیوند منجر به خطا یا واماندگی شود–بررسی کنید که آن نشانی با گسترش بیش از اندازهٔ پیوند در ویکی‌پدیا نمایش خواهد یافت یا خیر. اطمینان حاصل کنید که پس از پردازش توسط نرم‌افزار، صرف نظر از این که نشانی از سوی شما یک کاربر دیگر وارد شده یا به‌واسطهٔ پردازش خودکار تولید شده، یک فاصلهٔ نرم (و نه یک فاصلهٔ سخت یا نشکن) به‌دنبال نشانی بیاید. احتمالاً کد مبدأ می‌تواند شامل یا تولیدکنندهٔ فاصله‌ای باشد که در زمان پردازش حذف می‌شود، یا این که ممکن است هیچ فاصله‌ای در این کد موجود نباشد. کد مبدأ را، مثلاً با افزودن یک فاصلهٔ نرم پس از نشانی، به‌صورت دستی تصحیح کنید. الگوی {{فاصله}} می‌تواند برای این کار مفید باشد.

متغیرهای سامانه و منطق شرطی

ویرایش

کد الگوها معمولاً برای وابسته‌کردن رفتار الگو به محیط (نظیر زمان کنونی با فضای نام) یا به مقدارهای پارامترهایی که به آن‌ها فرستاده می‌شوند، از متغیرها و توابع تجزیه‌گری که در راهنما:کلمات جادویی توصیف شده‌اند، استفاده می‌کنند. از این موارد می‌توان در برآوردهای حسابی نیز استفاده کرد، اما ویژگی‌های مهم و استاندارد برنامه‌نویسی مانند حلقه‌ها و انتساب متغیرها در دسترس نیستند. دستکاری کامل رشته‌ها نیز قابل دسترسی نیست؛ برخی الگوهایی که چنین عملکردی را ارائه می‌دهند تاکنون ایجاد شده‌اند، اما به‌صرفه و کامل نیستند.

برخی از پرکاربردترین متغیرها و توابع در زیر فهرست شده‌اند. برای یافتن متغیرها و توابع بیشتر، راهنما:کلمات جادویی و مستندات کامل‌تر در صفحه‌های mw:Help:Magic words و mw:Help:Extension:ParserFunctions در مدیاویکی را ببینید. این توابع و کلمات جادویی دارای نام مستعار فارسی نیز هستند که در جدول زیر به آن‌ها اشاره شده‌است. دقت کنید که در بسیاری از این نام‌های مستعار فارسی، به‌جای استفاده از فاصله، از نیم‌فاصله استفاده شده‌است.

نمونه‌هایی از توابع تجزیه‌گر اصلی
توصیف متن ورودی نتیجه
تبدیل متن به حروف بزرگ (برای حروف لاتین) {{uc: Heavens to BETSY!}}
{{ب: Heavens to BETSY!}}
‎HEAVENS TO BETSY!‎
تبدیل متن به حروف کوچک (برای حروف لاتین) {{lc: Heavens to BETSY!}}
{{ک: Heavens to BETSY!}}
‎heavens to betsy!‎
دریافت نام یک فضای نام {{NS: 1}}
{{فن: 1}}
الگو:فن: ۱
دریافت نشانی اینترنتی در ویکی‌پدیا {{fullurl: pagename}}
{{نشانی‌کامل: pagename}}
//fa.wikipedia.org/wiki/Pagename

افزونهٔ ParserFunctions توابع تجزیه‌گر بیشتری با محوریت برنامه‌نویسی را ارائه می‌دهد.

نمونه‌هایی از توابع تجزیه‌گر افزونه
توصیف متن ورودی نتیجه
آزمودن برابری میان دو رشته (یا پارامتر) {{#اگرمساوی: بله | بله | هورا...! | ای بابا...!}} هورا…!
{{#اگرمساوی: بله | خیر | هورا...! | ای بابا...!}} ای بابا…!
آزمودن این که یک رشته (یا پارامتر) دربردارندهٔ چیزی (به‌جز فاصله خالی) هست یا خیر {{#if: {{{param|}}} | Hooray...! | Darn...! }}
{{#اگر: {{{پارامتر|}}} | هورا...! | ای بابا...! }}
ای بابا…!
انجام یک محاسبه (ریاضی)
[مساحت دایره‌ای به شعاع ۴، تا ۳ رقم اعشار]
[ارقام فارسی نمی‌پذیرد و ارقام باید به لاتین وارد شوند]
[نتیجه با اعداد انگلیسی خواهد بود و برای دریافت ارقام فارسی، باید کل عبارت را به واژه جادویی آرایش‌عدد فرستاد]
{{#expr: ( pi * 4 ^ 2 ) round 3}}
{{#حساب: ( pi * 4 ^ 2 ) round 3}}
{{آرایش‌عدد: {{#حساب: ( pi * 4 ^ 2 ) round 3}} }}
50.265
۵۰٫۲۶۵
آزمودن نتیجهٔ یک محاسبه
[عدد ۱۲۳۰ فرد است یا زوج؟]
{{#ifexpr: 1.23E+3 mod 2 | Odd | Even}}
{{#اگرحساب: 1.23E+3 mod 2 | فرد | زوج}}
Even
زوج
نمونه‌هایی از متغیرهای سامانه
توصیف متن ورودی نتیجه (برای همین صفحهٔ راهنما)
نام صفحه‌ها {{PAGENAME}}
{{نام‌صفحه}}
الگو
{{FULLPAGENAME}}
{{نام‌کامل‌صفحه}}
راهنما:الگو
نام فضای نام کنونی {{NAMESPACE}}
{{فضای‌نام}}
راهنما
تعداد کاربران ثبت‌نام کرده {{NUMBEROFUSERS}}
{{تعدادکاربران}}
۱٬۳۴۳٬۸۱۵
تعداد صفحه‌ها در یک ردهٔ خاص {{PAGESINCATEGORY:آلبوم‌های محمدرضا شجریان}}
{{صفحه‌دررده:آلبوم‌های محمدرضا شجریان}}
۷۴
نسخهٔ کنونی نرم‌افزار {{CURRENTVERSION}}
{{نسخه‌کنونی}}
1.43.0-wmf.26 (a37de05)
برچسب زمانی آخرین نسخهٔ صفحه {{REVISIONTIMESTAMP}}
{{زمان‌نسخه}}
20231126144252

متغیرهای {{نام‌صفحه}} و {{فضای‌نام}} منحصراً مفید هستند و بارها برای تغییر رفتار الگو بر پایه زمینه به‌کار رفته‌اند. برای مثال، اگر الگو برای تراگنجانش پیوند یک رده به‌کار رود (مثلاً رده‌های تمیزکاری که پیوندی را برای رده‌بندی صفحه به‌عنوان یک صفحهٔ نیازمند توجه تراگنجانش می‌کنند)، معمولاً متغیر {{فضای‌نام}} را بررسی می‌کند تا مطمئن شود که صفحه‌های بحث، صفحه‌های کاربری یا هر فضای نام دیگری که ممکن است برچسب به‌طور تصادفی و ناخواسته در آن‌ها قرار گرفته‌باشد، خود به‌عنوان صفحه‌های نیازمند تمیزکاری رده‌بندی نشوند.

الگوهای تودرتویی

ویرایش

الگوها ممکن است الگوهایی دیگر را در خود داشته‌باشند، به این حالت معمولاً ساختار تودرتویی می‌گویند. هرگاه الگو پردازش شود، ویکی‌متن تولیدشده توسط هر الگوی تودرتویی دیگر در داخل الگوی اصلی تراگنجانش می‌شود و در نتیجه پردازش محصول نهایی اساساً از پایین‌ترین سطح از الگوهای تودرتو آغاز می‌شود. اگرچه استفادهٔ این الگوها بسیار ساده است، اما ایجاد آن‌ها نیازمند به‌کارگیری ترفندها و فنون پر جزئیات است.

برای فرستادن یک پارامتر به یک الگوی تودرتو، برچسب پارامتر را به‌عنوان مقداری برای پارامترهای الگوی تودرتو در ویکی‌متن الگو درج کنید.

مثال‌ها:
الگو:الف شامل عبارت «{{ب|{{{3}}} }} قهوه‌ای‌رنگ چابک از روی...»است. این عبارت، مقدار فرستاده‌شده به پارامتر مکانی سومِ الگو:الف را می‌گیرد و آن را به پارامتر مکانی اولِ الگو:ب می‌فرستد؛ سپس متن تولید‌شده توسط الگو:ب را به‌عنوان بخشی از عبارت برمی‌گرداند.
الگو:الف شامل عبارت «{{ب|والدو={{{3}}} }} قهوه‌ای‌رنگ چابک از روی...» است. اینجا هم عملکرد الگو:الف مانند مثال قبلی است، با این تفاوت که پارامتر مکانی سومِ الگو:الف به پارامتر نام‌گذاری‌شدهٔ |والدو= در الگو:ب فرستاده می‌شود.

پارامترهای الگو خود می‌توانند به‌صورت مشروط انتخاب شوند.

مثال‌ها:
الگو:الف شامل عبارت «{{ب|{{{3}}}=روباه }} قهوه‌ای‌رنگ چابک از روی...» است. الگو:الف کلمهٔ «روباه» را به پارامتر نام‌گذاری‌شده‌ای از الگو:ب می‌فرستد که نام آن برابر با پارامتر مکانی سوم الگو:الف است.
{{#اگر: رشته آزمون | مقدار در صورت خالی نبودن رشته آزمون | {{#اگر: رشته آزمون | مقدار در صورت خالی نبودن رشته آزمون | مقدار در صورت خالی بودن رشته آزمون (یا تنها فاصله خالی) }} }}

هر الگو می‌تواند خودش را فراخوانی کند، اما این روند پس از یک بار تکرار متوقف خواهد شد تا از تشکیل یک حلقهٔ بی‌پایان جلوگیری شود.

وقتی یک الگوی تودرتویی دربردارندهٔ آکولادهای نامتناظر باشد مانند آنچه کد {{lb}}} آکولادهای نامتناظر در زمان پردازش به‌عنوان متن در نظر گرفته می‌شوند و بر روی تجزیهٔ آکولادهای الگوی داخلی اثر نخواهند گذاشت. با این حال، اگر الگوی داخلی جانشانی شود، ابتدا عمل جانشانی پردازش می شود و این باعث تغییر نحوهٔ تجزیهٔ آکولادها در الگوی داخلی خواهد شد. این عمل، کاربرد چندانی ندارد، اما بعضی اوقات می‌تواند باعث بروز خطاهایی دور از انتظار شود.

برای اطلاعات بیشتر، صفحه‌های راهنمای الگوهای پیشرفته و راهنمای تبدیل بازگشتی ویکی‌متن| در فراویکی را ببینید. این صفحه‌ها شامل اطلاعاتی پیرامون فراخوانی‌های غیرمعمول نظیر {{الگو {{{پارامتر|}}} }} نیز هستند.

کنترل گنجانش: noinclude و includeonly و onlyinclude

ویرایش

هرگاه یک الگو تراگنجانش یا جانشانی شود، به‌طور پیش‌فرض کل ویکی‌متن (کد) صفحهٔ الگو در ویکی‌متن صفحهٔ مقصد گنجانده می‌شود. با این حال، امکان تغییر این رفتار با استفاده از برچسب‌هایی که برای مشخص‌کردن بخش‌هایی خاص از الگو جهت گنجاندن به‌کار می‌روند، وجود دارد. این برچسب‌ها امکان جلوگیری از تراگنجانش اطلاعاتی مانند {{توضیحات}} الگو، رده‌ها و پیوندهای میان‌ویکی که تنها برای نمایش در صفحهٔ خود الگو ایجاد شده‌اند را فراهم می‌کند. همچنین می‌توان بخش‌هایی از الگو را تراگنجانش کرد، اما از پردازش آن در صفحهٔ خود الگو جلوگیری کرد (برای مثال، رده‌هایی که باید در صفحهٔ مقصد الگو قرار گیرند، اما شامل حال خود الگو نمی‌شوند). این برچسب‌ها به شرح زیر هستند:

  • <noinclude>...</noinclude>‎ – متن موجود در میان این برچسب‌ها در زمان تراگنجانش (یا جانشانی)، در متن خروجی الگو شامل نخواهد شد، اما در صفحهٔ خود الگو پردازش خواهد شد؛ کاربرد معمول این برچسب‌ها اغلب برای مستندات الگوها دیده می‌شود.
  • <onlyinclude>...</onlyinclude>‎ – این برچسب مشخص می‌کند که هیچ‌چیز به‌جز آنچه در میان این برچسب‌ها قرار گرفته، تراگنجانش (یا جانشانی) نخواهد شد.
  • <includeonly>...</includeonly>‎ – متنی که در میان این برچسب‌ها قرار گیرد تراگنجانش (یا جانشانی) خواهد شد، اما در صفحهٔ خود الگو پردازش نخواهد شد.
ویکی‌متن آنچه در همینجا (صفحهٔ مبدأ) ارائه می‌شود آنچه در آنجا (صفحهٔ مقصد) تراگنجانش می‌شود
<noinclude> متن۱ </noinclude> متن۲ متن۱ متن۲ متن۲
<onlyinclude> متن۱ </onlyinclude> متن۲ متن۱ متن۲ متن۱
<includeonly> متن۱ </includeonly> متن۲ متن۲ متن۱ متن۲
<onlyinclude><includeonly> متن۱ </includeonly></onlyinclude> متن۲ متن۲ متن۱

می‌توان گفت که رایج‌ترین مشکل در استفاده از این عبارت‌ها، وجود فاصله‌ها و خطوط جدید ناخواسته است. لازم است به‌یاد داشته‌باشید که تأثیر این برچسب‌ها بلافاصله قبل از نخستین پرانتز شکسته آغاز می‌شود، نه در سطر قبلی یا در نویسهٔ مرئی قبلی؛ همچنین تأثیر آن‌ها بلافاصله پس از آخرین پرانتز شکسته پایان می‌یابد و نه در سطر بعدی یا نویسهٔ مرئی بعدی. برای مثال:

<includeonly>
}}<includeonly>
}}
<includeonly>
<noinclude>
}}<noinclude>
}}
<noinclude>
</includeonly><noinclude>
{{template}}</includeonly><noinclude>
{{template}}</includeonly>
<noinclude>

این برچسب‌ها را می‌توان به‌صورت تودرتویی با یکدیگر به‌کار برد، اگرچه (در یک صفحهٔ مشخص) این قاعده تنها به برچسب‌های <onlyinclude> اعمال می‌شود؛ استفاده از برچسب‌های <includeonly> و <noinclude> به‌صورت تودرتویی نسبتاً بیهوده است. با این حال، سعی کنید از ساختار تودرتویی مناسب برای این برچسب‌ها استفاده کنید. ساختارهایی نظیر <onlyinclude>آب‌پ<includeonly>ت‌ث‌ج</onlyinclude>چ‌ح‌خ</includeonly> مطابق با انتظار کار نخواهند کرد. از قاعدهٔ «اولی باز، آخری بسته» که استانداردی در اچ‌تی‌ام‌ال/اکس‌ام‌ال است، استفاده کنید.

مشکلات و راه‌کارها

ویرایش
  • اگر نخستین نویسهٔ تولیدشده توسط یک الگو یا تابع تجزیه‌گر یکی از نویسه‌های نشانه‌گذاری ویکی :، ;، *، #[ح] باشد، به‌گونه‌ای پردازش خواهد شد که گویی در ابتدای سطر قرار گرفته‌است؛ حتی در صورتی که برچسب الگو چنین نباشد. این قابلیت، امکان ایجاد انواع مختلفی از فهرست‌ها را در الگوهایی که ممکن است همیشه در جای درستی برای ایجاد یک فهرست قرار نگیرند، فراهم می‌کند. برای جلوگیری از چنین چیزی، از <nowiki /> پیش از نشانه‌گذاری یا به‌ترتیب از موجودیت‌های اچ‌تی‌ام‌ال&#58;‎، ‎&#59;‎، ‎&#42;‎ و ‎&#35;‎ استفاده کنید. در برخی موارد، در صورت عدم کارایی برچسب‌های <nowiki />، موجودیت‌های اچ‌تی‌ام‌ال به‌خوبی کار خواهند کرد. این مشکل معمولاً در مواقعی بروز می‌کند که مقدار یک پارامتر در یک فراخوانی الگو با یکی از این چهار نویسه آغاز شود.
  • برای مشکلات مرتبط با جانشانی الگوها مانند چگونگی کنترل شیوهٔ جانشانی زیرالگوها در زمان جانشانی الگوی والد، راهنما جانشانی را ببینید.
  • در صورتی که وجود فاصلهٔ خالی در ابتدا یا انتهای مقدار یک پارامتر نام‌گذاری‌نشده ایجاد مشکل می‌کند، می‌توان از {{برداشتن فاصله خالی}} برای حذف فاصله‌ها از ابتدا و انتهای مقدار استفاده کرد؛ فاصله‌های خالی در ابتدا و انتهای مقدارهای فرستاده‌شده به پارامترهای نام‌گذاری‌شده به‌طور خودکار حذف می‌شوند.
  • برای اشکال‌زدایی از الگوها، تکنیک‌های زیر در بعضی مواقع راه‌گشا هستند:
    • برای جانشانی یک الگو (به‌جای تراگنجانش آن) از جا: استفاده کنید. این کار می‌توان برای درک بهتر این که در زمان تراگنجانش الگو چه اتفاقی می‌افتد، کمک‌کننده خواهد بود؛ راهنما:جانشانی را ببینید.
    • برای تراگنجانش ویکی‌متن صفحهٔ الگو به‌جای محتوای قابل پردازش، از msgnw: (کوتاه‌شدهٔ عبارت «‎message, nowiki‎») یا پیغام‌بی‌بسط: استفاده کنید. این کار نقص‌هایی دارد: فهرست‌ها پردازش می‌شوند، حاشیه‌نویسی‌ها حذف می‌شوند و سطرهای جدید با فاصلهٔ خالی جایگزین می‌شوند (که به‌ویژه در زمان تراگنجانش جدول‌های ویکی‌متنی، گیج‌کننده خواهد بود).
    • برای مشاهدهٔ بسط بازگشتی یک یا چند الگو از ویژه:گسترش الگوها استفاده کنید.
  • برای حفاظت از منابع کارساز (سرور) و اجتناب از حلقه‌های بی‌پایان، تجزیه‌گر محدودیت‌های خاصی را برای عمق تراگنجانش تودرتویی و حجم صفحه با الگوهای بسط داده‌شده اعمال می‌کند. این موضوع می‌تواند در زمان استفادهٔ صفحه‌های از الگوهای بسیار پیچیده، باعث خرابی آن‌ها شود، به‌ویژه در صورت وجود چند مورد از الگوهایی از این دست در یک صفحهٔ واحد. برای کسب اطلاعات بیشتر، ویکی‌پدیا:محدودیت‌های الگو را ببینید. وزن کلی صفحه بر روی سرور را می‌توان به‌واسطهٔ بررسی اچ‌تی‌ام‌ال تولیدشده برای یک صفحه و جستجو برای یافتن حاشیه‌نویسی‌های NewPP limit report بررسی کرد.
  • در الگویی که قرار است در فضای نام مقاله از آن استفاده شود، از نشانهٔ ویکی = برای ایجاد عنوان بخش استفاده نکنید؛ استفاده از این نویسه یک پیوند [ویرایش] تولید می‌کند که در صورت تراگنجانش، به‌طور گیج‌کننده‌ای صفحهٔ الگو را برای ویرایش باز خواهد کرد.
    • می‌توانید با گنجاندن عبارت <includeonly>__بی‌بخش__</includeonly> (یا <includeonly>__NOEDITSECTION__</includeonly>) از ایجاد پیوندهای [ویرایش] به مقصد صفحهٔ الگو جلوگیری کنید.

مستندسازی

ویرایش

رده‌بندی الگو و مستندسازی نحوهٔ صحیح استفاده از آن می‌تواند به سایر ویرایشگران در یافتن و استفاده از الگوی شما کمک کند.

مستندسازی برای کاربران، در کنار رده‌بندی الگو معمولاً پس از کد اصلی الگو و در میان برچسب‌های <noinclude>...</noinclude> قرار می‌گیرد. معمولاً لازم است که برچسب گشایندهٔ <noinclude> را بلافاصله پس از پایان کد الگو قرار دهید و برای اجتناب از تراگنجانش فاصله‌های خالی ناخواسته، هیچ فاصله یا سطر جدیدی نیز پیش از این برچسب درج نکنید.

در الگوهای پیچیده، مستندات به‌همراه رده‌ها معمولاً در یک زیرصفحهٔ جداگانه از صفحهٔ الگو (با عنوان «الگو:فلان/توضیحات») نگهداری می‌شوند. این قاعده بر بسیاری از الگوهای حفاظت‌شده نیز اعمال می‌شود و امکان ویرایش اطلاعات آن‌ها را برای کاربران غیرمدیر نیز فراهم می‌کند. این زیرصفحه را می‌توان با قرار دادن الگوی {{توضیحات}} پس از کد اصلی الگو و درون برچسب‌های <noinclude>...</noinclude> در صفحهٔ اصلی الگو فراخوانی کرد. اگر زیرصفحهٔ «/توضیحات» موجود نباشد، پیوندی برای ایجاد آن در جعبهٔ مستندات الگو نمایش خواهد یافت.

رده‌بندی

ویرایش

رده‌بندی صفحه‌ها با استفاده از الگوها

ویرایش

بعضی الگوها دربردارندهٔ رده‌های تعریف‌شده‌ای در کد قابل تراگنجانش خود هستند تا صفحهٔ مقصد را در یک رده(هایی) خاص قرار دهند. چنین چیزی معمولاً در الگوهای نگهداری دیده می‌شود (قرار دادن مقاله‌ها در رده‌های محتوایی عادی توصیه نمی‌شود). در زمان ایجاد چنین الگوهایی، لازم است که که از برچسب‌های <includeonly>...</includeonly> استفاده کنید تا از قرار گرفتن صفحهٔ خود الگو در ردهٔ مورد نظر جلوگیری شود. در زمان توسعه، آزمودن، تمرین‌کردن یا ارائهٔ الگویی که به‌منظور افزودن یک رده ساخته شده، هر یک از رده‌ها را با یک ردهٔ آزمایشی (مثلاً ت۱ و در صورت نیاز، با تولید نمونه‌هایی با شماره‌های بالاتر) جایگزین کنید یا رده‌بندی را فرونشانی کنید (فرونشانی رده در الگوها را ببینید).

رده‌بندی الگوها

ویرایش

تعریف رده‌بندی به‌شکل [[رده:الگو:موضوع مورد نظر]] باید در صفحهٔ مستندات الگو (یا در صورت نبود صفحهٔ مستندات، درون برچسب‌های <noinclude>...</noinclude>) قرار داده شود تاز از آلوده شدن صفحه‌هایی که الگو را تراگنجانش می‌کنند جلوگیری شود.

نام‌های مستعار

ویرایش

نام‌های مستعار را می‌توان با کمک تغییرمسیرها ایجاد کرد. برای مثال، الگو:مفبا به الگوی الگو:ماه فارسی به انگلیسی تغییر مسیر دارد. در نتیجه می‌توانید برای استفاده از این الگو عبارت {{مفبا|فلان}} را به‌جای {{ماه فارسی به انگلیسی|فلان}} بنویسید.

بد نیست که نام‌های مستعاری که تنها در فاصله‌های خالی یا نحوهٔ نوشتن عنوان با نام اصلی تفاوت دارند را نیز تهیه کنید. برای مثال، الگوی {{رده انبار}} دارای نام‌های مستعار {{انبار رده}} و {{انبار-رده}} نیز هست. چرا که ممکن است کاربران نام این الگو را به شکل‌های مختلفی بنویسند. همچنینی برای الگوهایی که از عنوان انگلیسی استفاده می‌کنند نیز می‌توان چنین نام‌های مستعاری ایجاد کرد. به‌عنوان مثال، الگوی {{See Wiktionary}} را در نظر بگیرید. حرف «W» در عنوان آن به‌صورت بزرگ نوشته‌شده؛ چرا که حرف اول نام «Wiktionary» نیز چنین است. اما تغییرمسیر {{See wiktionary}} با «w» کوچک نیز موجود است. زیرا ممکن است کاربران نام آن را به این شکل نیز بنویسند.

محدودیت‌های الگو

ویرایش

محدودیت «اندازه دربرگیری پس از بسط». هرگاه یک الگو برای مشاهده در مرورگر شما در قالب اچ‌تی‌ام‌ال ارائه یا بسط داده می‌شود از ظرفیت حافظهٔ شما استفاده می‌کند. این را با نام «اندازه دربرگیری پس از بسط» (انگلیسی: Post-expand include size) می‌شناسند و محدودیت آن برابر با ۲٬۰۴۸٬۰۰۰ بایت است. این اندازه به‌شکل حاشیه‌نویسی مخفی در خروجی اچ‌تی‌ام‌ال نمایان می‌شود، برای نمایش اچ‌تی‌ام‌ال خام، از ویژگی مشاهدهٔ مبدأ مرورگر خود استفاده کنید و عبارت «newpp» را جستجو کنید. گزارشی که مشاهده خواهید کرد، مشابه متن زیر است:

<!--
NewPP limit report
Preprocessor node count: 2382/1000000
Post-expand include size: 63476/2048000 bytes
Template argument size: 9517/2048000 bytes
Expensive parser function count: 2/500
-->

این نمونه نشان‌دهندهٔ این است که بسط الگو ۶۳٬۴۷۶ بایت از ۲٬۰۴۸٬۰۰۰ بایت حافظهٔ در دسترس را استفاده کرده‌است.

مشکل نمایش. اگر تعداد بسیار زیادی الگو در یک صفحه گنجانده شوند، اندازه دربرگیری پس از بسط ممکن است از محدودیت عبور کند. هرگاه چنین شود، الگوهای بعد از محدودیت دیگر بسط نخواهند یافت و در عوض به‌شکل یک ویکی‌پیوند نمایش خواهند یافت (برای مثال، الگو:نام الگو). دلیل معمول برای این اتفاق، استفادهٔ بسیار زیاد از الگوهای یادکرد و/یا الگوهای پرچم است. برای رفع این مشکل، الگوها را جانشانی کنید، الگوهایی را حذف کنید، یا صفحه را تفکیک کنید.

تراگنجانش‌های ارائه‌نشده هم بر رسیدن به محدودیت اثرگذارند. برای مثال، صفحه‌ای که تنها شامل {{#اگر:{{:صفحهٔ اصلی}}}} باشد، همچنان دارای اندازهٔ دربرگیری پس از بسط است؛ حتی اگر هیچ‌گونه خروجی نداشته‌باشد.

همین قاعده بر پودمان‌ها اسکریبونتو نیز اعمال می‌شود. برای مثال، ‎{{#invoke:Test|main}}‎ همچنان اندازهٔ دربرگیری پس از بسط را افزایش می‌دهد؛ حتی اگر کد پودمان:Test تنها به‌شکل زیر بوده‌باشد:

mw.getCurrentFrame():preprocess "{{پیغام‌بی‌بسط::صفحهٔ اصلی}}" -- remove this line and post-expand include size becomes zero
return {main = function() end} -- p.main() has no return value

زبان برنامه‌نویسی لوآ

ویرایش

از فوریهٔ ۲۰۱۳، زبان برنامه‌نویسی لوآ برای استفاده به‌واسطهٔ افزونهٔ اسکریبونتوی مدیاویکی در دسترس است. کد لوآ را می‌توان با به‌کارگیری تابع {{#درخواست:}} یا {{#invoke:}} از افزونهٔ اسکریبونتوی مدیاویکی، در الگوها تعبیه کرد. کد منبع لوآ در صفحه‌هایی که پودمان نامیده می‌شوند، ذخیره می‌شود و این پودمان‌ها در صفحه‌های الگوها فراخوانی می‌شوند. برای مثال، پودمان:نمونه را می‌توان با استفاده از کد {{#درخواست:نمونه|hello}} فراخوانی کرد تا متن «سلام دنیا!» را نمایش دهد.

جستجوی الگو

ویرایش

می‌توانید با استفاده از جعبهٔ ویژه:جستجو در پایین، در فضای نام الگو الگوی موردنظرتان را جستجو کنید:

جستارهای وابسته

ویرایش
صفحه‌های راهنما صفحه‌های شیوه‌نامه صفحه‌های ویژه صفحه‌های برای مشاهده غیرمستقیم

پانویس

ویرایش
  1. فضاهای نامی که تراگنجانش از آن‌ها مجاز نیست، در هر ویکی با استفاده از متغیر $wgNonincludableNamespaces مشخص می‌شوند. برای مثال، فضای نام «ویژه» قابل تراگنجانش یا جانشانی نیست.
  2. برخی الگوها مانند {{درخواست انتقال}} دارای کدی برای نمایش |reason= به‌صورت نمایان هستند؛ این که این کار انجام بشود یا خیر، برای هر الگو متفاوت است.
  3. &lambda;نهاد نویسهٔ اچ‌تی‌ام‌ال برای حرف یونانی (λ) است.
  4. از آنجا که خود ویکی‌متن باید بازبینی شود و نمی‌توان همزمان با ویرایش متنی، پیش‌نمایش آن را مشاهده کرد، پیش‌نمایش صفحه نتیجهٔ جانشانی الگو در خود ویکی‌متن را نمایش نخواهد داد.
  5. در صورتی که علامت مساوی در درون فراخوانی یک الگوی دیگر یا مورد دیگری که تجزیه‌گر به‌طور جداگانه به آن رسیدگی می‌کند، آمده‌باشد، این قاعده اعمال نمی‌شود.
  6. باری دیگر، در صورتی که این نویسه در درون یک آیتم تجزیه‌شدهٔ دیگر نظیر ویکی‌پیوندهایی که نام‌پوشی شده‌اند استفاده شود، این قاعده اعمال نمی‌شود.
  7. در نسخه‌های قدیمی، خوشهٔ زیرالگوها مطابق با وضعیت کنونی الگو ساخته خواهد شد.
  8. این نویسه‌ها در تابع doBlockLevels در Parser.php تعریف شده‌اند.