تعریف نمای Model-Driven

شناسهٔ شِما: model-driven-view@2 شِمای قابل‌خواندن توسط ماشین: model-driven-view.schema.json

نسخهٔ جایگزین‌شده: model-driven-view@1 (model-driven-view-v1.schema.json) همچنان منتشر و ثبت‌شده می‌ماند، تا راه‌حلی که پیشاپیش در برابر آن مستقر شده، همچنان در برابر همان شِمایی اعتبارسنجی شود که برایش نوشته شده بود. نسخهٔ ۲ همواره تنها ویژگی‌های اختیاری می‌افزاید — جدول «شکل» در پایین، فهرست کنونی است — پس هر تعریف نسخهٔ ۱ یک تعریف معتبر نسخهٔ ۲ هم هست و چیزی لازم نیست بازنویسی شود.

بازنمایی مرجع یک نما در Model-Driven Apps (بخش 6.7) — فهرستی جدولی از رکوردها با ستون‌ها، فیلترها و مرتب‌سازی‌هایش.

شکل

فیلد	نوع	اجباری	یادداشت‌ها
logicalName	string	بله	پیشوند ناشر در ابتدا، با snake-case کوچک.
displayName	string	بله	نام خوانای نما.
entity	string	بله	نام منطقی موجودیت مالک.
description	string	خیر	خطی که در نوار عنوان نما، زیر عنوان نمایش داده می‌شود.
icon	string	خیر	آیکونی که در نوار عنوان نما نمایش داده می‌شود.
viewType	string	خیر	اینکه نما برای چیست: Public (پیش‌فرض)، Lookup، QuickFind، Associated، QuickView، Card، SeedData.
seedDataKind	string	در نمای SeedData	در نمای SeedData الزامی و در هر نمای دیگر رد می‌شود: Configuration (رکوردهایی که راه‌حل برای کار کردن لازم دارد؛ درون‌ریزی همیشه آن‌ها را می‌آورد، حتی در Production) یا Demonstration (رکوردهای نمونه؛ فقط با تیک همراه با داده‌های نمایشی و هرگز به Production). به‌صورت kind در سند داده‌های اولیهٔ بسته می‌رود.
columns	array	بله	نام منطقی فیلدهایی که به‌عنوان ستون نمایش داده می‌شوند.
filters	array	خیر	بندهای فیلتر تخت (با AND ترکیب می‌شوند): field، operator، و (برای عملگرهای مقداری) value.
filterGroup	object	خیر	یک درخت فیلتر سلسله‌مراتبی AND/OR (به سبک Advanced Find)، که با filters با AND ترکیب می‌شود.
sorts	array	خیر	بندهای مرتب‌سازی: field، descending.
actions	array	خیر	کنش‌های قابل‌طراحی نوار فرمان.
hierarchy	object	خیر	هست وقتی نما همچون درخت رسم می‌شود نه جدول.
calendar	object	no	زمانی حاضر است که نما به‌جای شبکه به شکل تقویم رسم شود. هرگز در کنار hierarchy نمی‌آید.
columnProperties	array	خیر	اینکه ستون‌ها چگونه نمایانده می‌شوند — سرستون، پهنا، قالب، تراز، کنترل. تُنُک.
commandOverrides	array	خیر	آنچه این نما دربارهٔ فرمان‌هایی که سکو مالکشان است تغییر می‌دهد.
commandOrder	array	خیر	یک نوار، یک ترتیب: فرمان‌های درون‌ساخت و سازنده درهم‌بافته، با شناسه.
rowSelection	boolean	خیر	اینکه سطرها جعبهٔ گزینش داشته باشند. پیش‌فرض true.

عملگرها: Equals، NotEquals، Contains، GreaterThan، LessThan، IsNull، IsNotNull. هر فیلد ارجاع‌شده (ستون‌ها، فیلترها، شرط‌های گروه فیلتر، مرتب‌سازی‌ها) باید روی موجودیت وجود داشته باشد.

viewType

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

مقدار	برای چیست
Public	صفحهٔ فهرست عادی موجودیت. این پیش‌فرض است، و تعریفی که viewType ندارد همین است.
Lookup	ستون‌هایی که درون پنل نتایج یک کنترل جستجوی رکورد نمایش داده می‌شوند — معمولاً دو تا چهار ستون.
QuickFind	ستون‌های کاوش: ستون‌هایی که یک جستجوی تایپ‌شده در برابرشان تطبیق داده می‌شود. columns آن مجموعهٔ کاویده‌شده است؛ فیلترها و مرتب‌سازی‌هایش خوانده نمی‌شوند.
SeedData	رکوردها و ستون‌هایی که همراه راه‌حل سفر می‌کنند (PF22). هرگز نمایش داده نمی‌شود: خروجی گرفتن از راه‌حل آن را اجرا می‌کند — filters آن رکوردها را تعیین می‌کند و columns آن فیلدها را — و نتیجه را به‌صورت یک سند seed-data@1 بسته‌بندی می‌کند که درون‌ریزی بر اساس شناسه درج یا به‌روز می‌کند. جدولی که چند نمای این‌چنینی دارد از نمای پیش‌فرض استفاده می‌کند، وگرنه از اولین نما به ترتیب نام منطقی.
Associated	زیرشبکهٔ رکوردهای مرتبط. رزرو شده — هنوز چیزی آن را رسم نمی‌کند.

کنترل جستجوی رکوردی که هیچ نمایی را نام نبرد، به‌طور خودکار یکی را رفع می‌کند: نمای Lookup پیش‌فرض موجودیت مقصد، وگرنه نمای Public پیش‌فرض آن که به سه ستون نخستش بریده شده، وگرنه تنها فیلد اصلی موجودیت. جستجویی بدون نمای QuickFind تنها فیلد اصلی را تطبیق می‌دهد. ستون‌های کاوش باید فیلدهای متنی باشند، چون تطبیق یک «contains» بی‌اعتنا به بزرگی و کوچکی حروف است.

calendar (نمایی که به شکل تقویم رسم می‌شود)

نمایی که بلوک calendar دارد، رکوردهایش را بر پایهٔ دو فیلد تاریخ خودش روی برگهٔ روز، هفته یا ماه می‌چیند، نه در یک شبکه. نبودِ این بلوک یعنی همان شبکه — درست مانند hierarchy — پس هر نمای ذخیره‌شده معتبر می‌ماند. نمایی که هر دو بلوک را داشته باشد رد می‌شود: یک نما تنها به یک شکل رسم می‌شود.

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

فیلد	نوع	الزامی	توضیح
start	string	بله	فیلد تاریخ و زمانی که بلوک در آن جای می‌گیرد. تنها نقش الزامی: رکوردی بدون شروع اصلاً روی برگه جای نمی‌گیرد، پس چیزی برای بازگشت نیست. فیلد سامانه‌ای هم مجاز است — created_at_utc رکوردها را بر پایهٔ زمان ورودشان می‌چیند.
end	string	خیر	فیلد تاریخ و زمانی که بلوک در آن پایان می‌یابد. نبودنش برای جدولی است که یک لحظه را ثبت می‌کند نه یک بازه، و آنگاه هر بلوک به اندازهٔ defaultDurationMinutes است — نه صفر، چون بلوکی بدون ارتفاع را نمی‌توان کلیک کرد.
title	string	خیر	فیلدی که سطر نخست بلوک از آن خوانده می‌شود. نبودنش یعنی فیلد اصلی جدول، همان که شبکه، پنل ارجاع و مسیر راهنما هم نشان می‌دهند.
category	string	خیر	فیلدی از نوع فهرست گزینه، وضعیت یا دلیل که گزینه‌هایش رنگ بلوک‌ها و راهنمای رنگ‌ها را تعیین می‌کنند.
bookedFor	string	خیر	فیلدی که می‌گوید این بازه برای چه کسی است و زیر عنوان به‌آرامی نمایش می‌یابد. هر نوعی: یک ارجاع به نام رکورد مقصد تبدیل می‌شود.
note	string	خیر	فیلدی که روی بلوکِ به‌اندازه‌کافی بلند در سطر سوم و در غیر این صورت در راهنمای ابزار نمایش می‌یابد.
defaultScale	string	خیر	نما با کدام برگه باز می‌شود: Day، Week (پیش‌فرض) یا Month.
startHour	integer	خیر	نخستین ساعتی که برگه‌های روز و هفته نشان می‌دهند، ۰ تا ۲۳. پیش‌فرض 0.
endHour	integer	خیر	ساعتی که آن برگه‌ها در آن پایان می‌یابند، ۱ تا ۲۴، و بزرگ‌تر از startHour. پیش‌فرض 24.
defaultDurationMinutes	integer	خیر	طول یک بازه وقتی خواننده روی جای خالی کلیک می‌کند — همان چیزی که رکورد تازه با آن ساخته می‌شود — و ارتفاع هر بلوک در نمایی که end ندارد. دست‌کم ۱؛ پیش‌فرض 60.

🔴 start و end باید فیلد تاریخ و زمان باشند و category باید رنگ داشته باشد. هر دو هنگام ذخیره رد می‌شوند، چون هر دو روی صفحه بی‌صدا شکست می‌خورند: startی که ستون متنی باشد یک برگهٔ خالی می‌کشد، که خوانده می‌شود «این هفته چیزی رزرو نشده» — تنها نتیجه‌ای که خواننده بر پایهٔ آن عمل می‌کند و نمی‌تواند وارسی‌اش کند. رنگ روی گزینه‌های خودِ فهرست گزینه می‌نشیند؛ همین است که «آزمون کهرباییست» را یک‌بار می‌گوید و تقویم، خانهٔ شبکه و نمودار همه آن را می‌خوانند.

startHour و endHour تفاوت میان یک برگهٔ رزرو کارامد و برگه‌ای است که دوسومش خالی باز می‌شود: درمانگاهی که از ۸ تا ۱۹ کار می‌کند شانزده سطر نیمه‌شب نمی‌خواهد. این‌ها می‌گویند برگه با چه چیزی باز می‌شود — خواننده همچنان از سربرگ خودِ برگه مقیاس را عوض می‌کند و ساعت‌ها را محدود می‌کند، چون این پنجره از آنِ اوست نه از آنِ سازنده.

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

hierarchy (نمایی که همچون درخت رسم می‌شود)

نمایی که بلوک hierarchy دارد، رکوردهایش را آشیانه‌شده بر پایهٔ یک جستجو (Lookup) رسم می‌کند — یک چارت سازمانی با افراد هر واحد، یک درخت دسته‌بندی، یک صورت‌ریز مواد — به‌جای یک جدول. نبودِ آن همان جدولی است که هر نما همیشه بوده، و برای همین هر نمای ذخیره‌شده معتبر می‌ماند.

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

فیلد	نوع	الزامی	یادداشت
nodeTypes	array	بله	هر گونه گرهی که درخت می‌تواند بکشد. دست‌کم یکی.
order	array	خیر	ترتیب رسم بخش‌های زیر یک گره، بر پایهٔ شناسهٔ گونهٔ گره. نبودش یعنی ترتیب اعلام.
rootPicker	boolean	خیر	اینکه خواننده بتواند درخت را روی یک گره متمرکز کند — باز کردن روی یک شهر به‌جای کل سازمان.
expandRoots	boolean	خیر	اینکه نخستین سطح هنگام بارگذاری باز باشد. به‌صورت پیش‌فرض true.

هر درایهٔ nodeTypes:

فیلد	نوع	الزامی	یادداشت
id	string	بله	نام این گونه درون بلوک — unit، person. اینجا یکتاست و همان چیزی است که order و هر childOf.of به آن ارجاع می‌دهند. یک جدول می‌تواند دو بار در یک چارت بیاید، و به همین دلیل این واژهٔ خودِ سازنده است نه نام جدول.
entity	string	بله	جدولی که این گره‌ها رکوردهای آن‌اند.
childOf	object	بله	اینکه این گونه چگونه زیر والدش می‌آویزد — پایین‌تر ببینید.
label	string	خیر	فیلدی که مقدارش سطر گره است. نبودش یعنی فیلد اصلی جدول.
secondary	string	خیر	فیلدی که آرام پس از برچسب نشان داده می‌شود. نبودش یعنی فیلد ثانویهٔ خود جدول؛ رشتهٔ تهی یعنی هیچ — روی یک واحد، نام والد همان سطر بالای آن است، پس چارت یکی از جاهایی است که خط دوم پیش‌فرض یک جدول نادرست است.
icon	string	خیر	نگارهٔ روی سطر. نبودش یعنی نگارهٔ خود جدول.
image	boolean	خیر	اینکه سطر تصویر رکورد را همراه داشته باشد.
detail	object	خیر	آنچه هنگام گزینش یکی، تابلوی کنار چارت را پر می‌کند. نبودش یعنی فرم اصلی جدول.

childOf یک field می‌گیرد — جستجوی روی جدول این گونه که رکورد والد را نگه می‌دارد — و یک of اختیاری، یعنی گونهٔ گرهی که زیر آن می‌آویزد، با شناسه.

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

جستجویی که childOf.field نام می‌برد باید جدول گونهٔ والد را هدف بگیرد — برای گونهٔ ریشه، جدول خودش. جستجویی که جای دیگری را نشان دهد آشیانه‌شدنی را توصیف نمی‌کند و هنگام ذخیره رد می‌شود، به‌جای آنکه سطحی را با هیچ‌چیز زیرش رسم کند.

detail یک kind می‌گیرد: Form (فرم خود جدول، که از راه نوشتن خود فرم رکورد ذخیره می‌شود)، Card (یک نمای کارت که برای خوانده‌شدن چیده شده نه برای تایپ‌کردن، که معمولاً همان چیزی است که یک فرد زیر یک واحد می‌خواهد) یا None (برای گونه‌ای که تنها ساختار است)، به‌همراه یک name اختیاری برای اینکه کدام فرم یا نمای کارت.

columnProperties (اینکه یک ستون چگونه نمایانده می‌شود)

فهرستی تُنُک: تنها ستون‌هایی که سازنده پیکربندی کرده می‌آیند، و ستونی که درایه‌ای ندارد تنها از فراداده‌های فیلد خودش رسم می‌شود. کنار columns می‌نشیند به‌جای آنکه آن را به فهرستی از شیءها تبدیل کند، تا هر تعریف نسخهٔ ۱ معتبر بماند و هر خواننده‌ای که تنها می‌خواهد بداند نما کدام ستون‌ها را دارد، دست‌نخورده بماند.

فیلد	نوع	الزامی	یادداشت
field	string	بله	ستونی که این درایه پیکربندی‌اش می‌کند. باید یکی از columns نما باشد.
label	string | null	خیر	جایگزینی سرستون. نبودش یعنی نام نمایشی فیلد.
width	integer | null	خیر	پهنا به پیکسل، از ۴۰ تا ۱۲۰۰. نبودش یعنی ستون خودش را اندازه می‌کند.
format	string | null	خیر	قالب مقدار. برای ستون تاریخ‌وزمان، همان مجموعه نشانه‌هایی که کنترل‌های تاریخ فرم می‌پذیرند (yyyy، yy، MM، dd، HH، mm، ss) — یک واژگان قالب‌بندی در سراسر محصول.
align	string | null	خیر	start، center یا end. منطقی، نه چپ/راست، پس از جهت خواندن پیروی می‌کند (§۶٫۱۳٫۶).
controlType	string | null	خیر	کنترلی که ستون با آن رسم می‌شود — نگارهٔ کلید برای یک بولی، تاریخ شمسی برای یک تاریخ.

controlType این‌ها را می‌گیرد: Text، TextArea، Check، Toggle، Date، DateTime، Time، PersianDate، PersianDateTime، PersianTime، Lookup، PolymorphicLookup، Dropdown یا Label. نبودش یعنی نخست پیش‌فرض خود فیلد و سپس پیش‌فرض نوع داده.

🔴 همیشه فقط‌خواندنی رسم می‌شود. جدول ویرایش درجا ندارد، پس یک کلید اینجا وضعیت را نشان می‌دهد نه اینکه کلیک بگیرد. همچنین تنها راهی است که یک ستون می‌تواند در یک مستأجر میلادی، جلالی نشان دهد، چون format الگویی است که هیچ گاه‌شماری به آن پیوست نیست.

commandOverrides (تغییر فرمانی که سکو مالک آن است)

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

فیلد	نوع	الزامی	یادداشت
command	string	بله	شناسهٔ پایدارِ فرمانی که بازنویسی می‌شود.
label	string	خیر	جایگزین برچسب سکو. نبودش آن را نگه می‌دارد — همراه با ترجمه‌هایش، که یک بازنویسیِ تایپ‌شده ناگزیر از دست می‌دهد.
icon	string	خیر	جایگزین نگارهٔ سکو.
initiallyHidden	boolean	خیر	اینکه فرمان در آغاز پنهان باشد.
initiallyDisabled	boolean	خیر	اینکه فرمان در آغاز ازکارافتاده باشد.

🔴 کلیدش شناسهٔ پایدار فرمان است، نه برچسب و نه جایگاه. شناسه نام خود سکوست و با تغییر برچسب عوض نمی‌شود، پس یک بازنویسی نمی‌تواند همان لحظه که کسی برچسب را ویرایش می‌کند از آنچه بازنویسی‌اش می‌کند جدا شود — و یک فرمان درون‌ساخت می‌تواند بعدها نام عوض کند یا بازنشسته شود بی‌آنکه هر سند ذخیره‌شده نیاز به آشتی‌دادن داشته باشد، چون بازنویسی‌ای که فرمانی دیگر ناموجود را نام می‌برد به‌سادگی نادیده گرفته می‌شود.

🔴 سازنده می‌تواند پنهان و ازکار بیندازد، هرگز نمایان یا فعال نکند. پخش‌کننده «جدید» را از کسی که نمی‌تواند بسازد پنهان می‌کند و «حذف» را وقتی چیزی برگزیده نیست ازکار می‌اندازد؛ بازنویسی‌ای که بتواند آن را واگرداند، نواری می‌سازد که چیزی را پیشنهاد می‌دهد که کارساز آن را رد خواهد کرد.

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

commandOrder (یک نوار، یک ترتیب)

فرمان‌های درون‌ساخت و فرمان‌های خود سازنده، درهم‌بافته همان‌گونه که سازنده چیده، با شناسه.

فهرستی صریح، نه رتبه‌ای روی هر فرمان — چون رتبه باید با هر جابه‌جایی روی همهٔ فرمان‌ها بازنویسی شود، و دو فرمان می‌توانند یک رتبه داشته باشند؛ گرهی که آن‌گاه رسم‌کننده جور دیگری بازش می‌کند تا آنچه طراح کرده بود.

🔴 هر چه این فهرست نامش را نبرد، جای طبیعی خود را نگه می‌دارد، در پایان. همین است که قاعده را در گذر زمان زنده نگه می‌دارد: فرمانی درون‌ساخت که سال آینده به سکو افزوده شود، یا فرمانی که یک ارتقا می‌آورد، پیدا می‌شود نه اینکه ناپدید شود چون ترتیبی ذخیره‌شده پیش از آن بوده. شناسه‌ای که چیزی دیگر ناموجود را نام ببرد نادیده گرفته می‌شود.

rowSelection (اینکه سطرها جعبهٔ گزینش داشته باشند)

به‌صورت پیش‌فرض true، و معنای هر نمایی که پیش از پیدایش این نوشته شده: جدول سرستون «گزینش همه» و جعبه‌های هر سطر را می‌گیرد، که همان چیزی است که نوار فرمان بر آن کار می‌کند.

false برای نمایی است که تنها خوانده می‌شود — فهرستی که کسی از آن حذف یا واگذار نمی‌کند — جایی که جعبهٔ گزینش، چندگزینی‌ای پیشنهاد می‌دهد که آن سطح کاربردی برایش ندارد و یک ستون پهنا هزینه دارد.

filterGroup (سلسله‌مراتبی AND/OR)

یک filterGroup گرهی بازگشتی است که اعضایش را با یک connector ترکیب می‌کند:

فیلد	نوع	اجباری	یادداشت‌ها
connector	string	بله	And (همهٔ اعضا تطبیق یابند) یا Or (هر عضوی تطبیق یابد).
conditions	array	خیر	شرط‌های برگ (field، operator، value) در این گروه.
groups	array	خیر	زیرگروه‌های تودرتو (با همان شکل)، برای تودرتویی دلخواه AND/OR.

نمونه

{
  "logicalName": "par_invoice_active",
  "displayName": "Active Invoices",
  "entity": "par_invoice",
  "viewType": "Public",
  "columns": ["par_name", "par_total"],
  "filters": [ { "field": "par_total", "operator": "GreaterThan", "value": 0 } ],
  "filterGroup": {
    "connector": "And",
    "conditions": [ { "field": "par_name", "operator": "Contains", "value": "INV" } ],
    "groups": [
      {
        "connector": "Or",
        "conditions": [
          { "field": "par_total", "operator": "GreaterThan", "value": 1000 },
          { "field": "par_total", "operator": "IsNull" }
        ]
      }
    ]
  },
  "sorts": [ { "field": "par_name", "descending": false } ]
}

نمونه — یک نمای جستجوی رکورد

{
  "logicalName": "par_contact_pick",
  "displayName": "Contact Lookup",
  "entity": "par_contact",
  "viewType": "Lookup",
  "columns": ["par_name", "par_email", "par_city"],
  "sorts": [ { "field": "par_name", "descending": false } ]
}

نمونه — یک نمای کاوش سریع

تنها columns خوانده می‌شود: این‌ها ستون‌هایی هستند که یک جستجوی تایپ‌شده در برابرشان تطبیق داده می‌شود.

{
  "logicalName": "par_contact_find",
  "displayName": "Contact Quick Find",
  "entity": "par_contact",
  "viewType": "QuickFind",
  "columns": ["par_name", "par_email", "par_accountnumber"]
}