نمایش یک نما به‌شکل جدول

هدف

فهرستی از رکوردها را در درگاه خود بگذارید بدون آنکه فهرست را بکشید — جدول خودِ پلتفرم، با ستون‌هایی که یک نما تعیین می‌کند.

پیش از شروع

• یک نما روی جدول، با ستون‌هایی که می‌خواهید بازدیدکنندگان ببینند. عنوان‌ها، پهناها و ترتیب از همین‌جا می‌آیند.
• یک Custom API که جدول را فهرست کند، تیک‌خورده در چه چیزی را می‌تواند بخواند. ببینید یک برنامه را به‌عنوان درگاه منتشر کنید.

گام‌ها

1. در طراح برنامه، مؤلفه‌ها ← نمای جدول یا فرم را جایی بیندازید که فهرست باید باشد.
2. در زبانهٔ صفحه، جدول را برگزینید. نما را روی پیش‌فرض جدول بگذارید، یا یکی از نماهای جدول را برگزینید.
3. Custom API (درگاه) ای را برگزینید که ردیف‌ها از آن می‌آیند — مثلاً Notices (api:par_list_notices@1). فقط قراردادهایی پیشنهاد می‌شوند که به GET پاسخ می‌دهند، چون جدول فقط می‌خواند.
4. منتشر کنید و درگاه را باز کنید.

روی صفحه همین است. ستون‌ها را اینجا انتخاب نمی‌کنید — نما پیش‌تر انتخاب کرده است.

یک جدول دو پرسش دارد، و هر جعبه به یکی پاسخ می‌دهد. جدول و نما تعیین می‌کنند چه چیزی نشان داده شود — عنوان‌ها، پهناها، ترتیب — و سکو پیش از سرویس‌دادن صفحه آن‌ها را درمی‌آورد، پس هیچ چیز از شکل جدول شما به مرورگرِ عمومی نمی‌رسد. Custom API تعیین می‌کند کدام ردیف‌ها، چون روی درگاه هر خواندنی از راه قراردادی می‌گذرد که خودتان نوشته‌اید. در فهرست برنامه‌ها جعبهٔ API نادیده گرفته می‌شود و جدول هر دو را تأمین می‌کند.

API چه باید بکند

صفحه‌بندی کند و تعداد کل را بگوید. جدول هر بار یک صفحه می‌خواهد و total را می‌خواند تا بداند صفحهٔ بعدی هست یا نه:

var page = runQuery({
  entity: 'par_notice',
  select: ['par_name', 'par_category', 'par_published_on'],
  order: [{ field: 'par_published_on', descending: true }],
  top: num(getInput('top')),
  skip: num(getInput('skip'))
});

setOutput('rows', page);
setOutput('total', page.length());

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

ستونی که نما دارد و API برنمی‌گرداند

در هر ردیف یک خط تیره نشان می‌دهد. نما سرستون‌ها را تعیین می‌کند؛ API تعیین می‌کند در هر ردیف چه هست، و میدانی که select آن جا انداخته در ردیف نیست. پس افزودن یک ستون دو ویرایش است: ستون در نما، و میدان در select آن API.

این عمدی است، نه غفلت. نما با برنامهٔ درون پلتفرم مشترک است، و افزودن ستونی برای همکاران خودتان نباید آن میدان را برای غریبه‌ها منتشر کند. آنچه از پلتفرم بیرون می‌رود همان است که API برمی‌گزیند.

جدولی بدون API اصلاً ظاهر نمی‌شود

Custom API (درگاه) را خالی بگذارید، یا APIای نام ببرید که به درگاه داده نشده است، و جدول سرویس نمی‌شود — هیچ جدولی نمی‌بینید، نه عنوان‌هایی بالای بدنه‌ای خالی.

این عمدی است و همان قاعده‌ای است که بقیهٔ درگاه از آن پیروی می‌کند: جدول خالی یعنی «رکوردی نیست»، که ادعایی متفاوت از «این درگاه هرگز اجازهٔ نمایش آن‌ها را نداشت» است. بازگشت به خواندن مستقیم از جدول از این هم بدتر بود — همان دری است که §6.11.3 می‌بندد، از راهی دیگر.

ستون‌ها از کجا و کِی می‌آیند

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

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

بازدیدکننده با آن چه می‌تواند بکند و چه نمی‌تواند

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

اگر می‌خواهید بازدیدکننده کاری انجام دهد، دکمه‌ای بکشید و سطر مجاز خودش را به آن بدهید.

آنچه روی درگاه در دسترس نیست

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

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

تأیید کنید که کار کرده

درگاه را همان‌طور که یک غریبه باز می‌کند باز کنید. جدول ستون‌های نمای شما را با عنوان‌هایشان نشان می‌دهد و رکوردهایی را که API برمی‌گرداند صفحه می‌زند. بعد یکی از عنوان‌های ستون در نما را ویرایش کنید و دوباره بارگذاری کنید — درگاه دنبالش می‌آید.