نمایش یک فهرست، صفحه‌به‌صفحه

هدف

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

چرا چنین چیزی هست

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

پس پرس‌وجو دو چیز تازه گرفت: یک صفحه (skip) و جایی برای شمار (countInto).

یک پرس‌وجو همهٔ این‌ها را می‌کند

loadRecords("par_case", "cases", {
  top: num(getState("pageSize")),
  skip: getState("page") * num(getState("pageSize")),
  contains: { par_name: getState("query") },
  orderBy: "par_name",
  countInto: "caseTotal"
});

num(…) از آن روست که اندازهٔ صفحه از یک فهرست بازشو می‌آید، و هر کنترلی که گزینه پیش می‌گذارد واژه‌ها را برمی‌گرداند نه عدد را — «اندازهٔ صفحه» در پایین را ببینید.

بخش	یعنی
top	این صفحه چند ردیف دارد
skip	چند ردیف را اول رد کند — ردیف، نه صفحه
where	جفت‌های میدان/مقدار که باید دقیق برابر باشند، همه با هم
contains	جفت‌های میدان/زیررشته — آنچه یک جعبهٔ جست‌وجو می‌خواهد
orderBy / descending	ترتیب
countInto	میدان حالتی برای شمار همهٔ ردیف‌های همخوان، بی‌توجه به صفحه

skip ردیف است نه شمارهٔ صفحه، چون top هم ردیف است. صفحه‌ای که هر دو را نگه دارد باید هماهنگشان کند، و خرابیِ این کار خاموش است: کسی اندازهٔ صفحه را عوض می‌کند، بازنشاندن صفحه را از یاد می‌برد، و روی صفحهٔ ۷ از فهرستی می‌ایستد که حالا ۳ صفحه دارد.

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

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

گام‌ها

1. حالتی را که فهرست نیاز دارد اعلام کنید: cases ([])، caseTotal (0)، page (0)، pageSize ("20" — مقدار خودِ فهرست بازشو، پس واژه است)، query ("").

2. پرس‌وجوی بالا را در دست‌گیرهٔ بارگذاری صفحه بگذارید.

3. پیشین و بعدی را بکشید و فعال آن‌ها را ببندید:

   • پیشین — state.page > 0
   • بعدی — (state.page + 1) * num(state.pageSize) < state.caseTotal

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

   setState("page", getState("page") + 1);
   loadRecords( … همان پرس‌وجو … );

5. نوشته را بکشید. یک عدد را نمی‌شود مستقیم به جمله افزود — BS Lang آمیختن رشته و عدد را رد می‌کند و می‌گوید Only number or string — پس بپیچیدش:

   "Showing " + text(state.cases.length()) + " of " + text(state.caseTotal)

6. جعبهٔ جست‌وجو را جعبهٔ متنی بکشید که به state.query بسته است، و دست‌گیرهٔ تغییر آن را بگذارید که به صفحهٔ صفر برگردد و پرس‌وجو را دوباره بدواند. جعبهٔ متن وقتی ترکش می‌کنید یا Enter می‌زنید تأیید می‌شود، پس این یک پرس‌وجو برای هر جست‌وجوست، نه یکی برای هر حرف.

اندازهٔ صفحه

یک فهرست بازشو، در انتهای سمت مقابلِ ردیف، با ۱۰، ۲۰، ۳۰، ۴۰، ۵۰، ۱۰۰ و ۲۰۰:

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

واژه‌ها را برمی‌گرداند، نه عدد را. هر کنترلی که گزینه پیش می‌گذارد چنین می‌کند — پس state.pageSize مقدار "20" را نگه می‌دارد و به‌کاربردنش در حساب به num(…) نیاز دارد:

num(state.pageSize) * state.page

بدون آن BS Lang این جفت را رد می‌کند و می‌گوید Only number or string — همان قاعده‌ای که نوشته را به text(…) نیازمند می‌کند؛ این دو، دو سویِ یک تبدیل‌اند. num(…) برای هرچه عدد نباشد ۰ پاسخ می‌دهد، پس گزینگری که کسی دستش نزده نمی‌تواند صفحه را بشکند.

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

جست‌وجو در یک گزینگر

همین contains است که یک lookup را به‌کاربردنی می‌کند. در نمونهٔ میز پشتیبانی کارتِ گزینگرِ مخاطب جعبهٔ متن خودش را دارد و دست‌گیرهٔ تغییرش این را دوباره می‌دواند:

loadRecords("contact", "contacts", { top: 8, orderBy: "fullname",
  contains: { fullname: getState("contactQuery") } });

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

آنچه اینجا نیست

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

عیب‌یابی

• نوشته می‌گوید Only number or string. — عددی به جمله افزوده می‌شود. در text(…) بپیچیدش. همین پیام روی یک محاسبه مشکل وارونه است: واژه‌های یک کنترل به‌جای عدد به کار رفته‌اند، پس آن را در num(…) بپیچید.
• اندازهٔ صفحه کاری نمی‌کند، یا با تغییر آن فهرست خالی می‌شود. — state.pageSize واژه‌های فهرست بازشو را نگه می‌دارد. top و skip به num(…) دور آن نیاز دارند.
• بعدی هرگز غیرفعال نمی‌شود. — چیزی شمار را نمی‌نویسد. countInto را به پرس‌وجو بیفزایید.
• جست‌وجو پس از صفحهٔ نخست چیزی نمی‌یابد. — دست‌گیرهٔ جست‌وجو page را بازنشانی نمی‌کند.
• فهرست با هر کلید دوباره پرس‌وجو می‌کند. — دست‌گیره روی چیزی است که با هر حرف می‌دود. آن را روی تغییرِ جعبه بگذارید، که هنگام ترک‌کردن می‌دود.

سناریوهای مرتبط

• واکنشی‌کردن یک صفحه.
• کشیدن یک صفحهٔ استودیو.