معرفی پلاگین تقویم فارسی برای اوراکل اپکس(ای پکس)

پلاگین APEXRAD Persian Date Picker اولین تقویم فارسی حرفه‌ای برای انتخاب تاریخ شمسی/جلالی (و حالت نمایش شاهنشاهی) در Oracle APEX است. این پلاگین ظاهر کاربرپسند، پشتیبانی از ارقام فارسی، محدودسازی تاریخ، تعطیلات، انتخاب ساعت و حالت نمایش Popup یا Inline را در اختیار شما قرار می‌دهد.

• نحوه نصب پلاگین

• ویژگی‌ها و قابلیت‌ها

• مزیت‌ها و کاربردها

• آموزش کامل Attributeها با مثال

• نمونه تنظیم پیشنهادی سریع

نحوه نصب پلاگین

1. در Oracle APEX وارد مسیر Shared Components > Plugins شوید.
2. روی Import کلیک کنید.
3. فایل item_type_plugin_info_apexrad_persiandatepicker.sql را انتخاب و Import کنید.
4. بعد از Import، در صفحه موردنظر یک Page Item جدید بسازید.
5. Type آیتم را روی APEXRAD Persian Date Picker (Jalali) قرار دهید.
6. Attributeهای پلاگین مانند Display Format، Show Time، Minimum Date و Holiday Dates را بر اساس نیاز تنظیم کنید.

نحوه استفاده

تنظیم NLS DATE

برای استفاده صحیح از تاریخ شمسی در سطح Session، در Oracle APEX وارد مسیر
Application / Edit Security Attributes / Database Session
شوید و مقدارهای NLS_CALENDAR و NLS_DATE_FORMAT را تنظیم کنید.

BEGIN
   EXECUTE immediate 'ALTER SESSION SET NLS_CALENDAR=PERSIAN';
   EXECUTE immediate 'ALTER SESSION SET NLS_DATE_FORMAT=''YYYY/MM/DD''';
END;

Page Item

1. یک Page Item جدید ایجاد کنید.
2. Type آیتم را روی APEXRAD Persian Date Picker (Jalali) قرار دهید.
3. Attributeهای پلاگین را از پنل سمت راست تنظیم کنید.

Format Mask: YYYY/MM/DD HH24:MI

Interactive Grid Column

1. یک ستون به Interactive Grid اضافه کنید.
2. Type ستون را روی APEXRAD Persian Date Picker (Jalali) قرار دهید.
3. برای نمایش سال شاهنشاهی در سلول‌های Read Only، کلاس زیر را در بخش CSS Classes ستون وارد کنید:

persianDatepicker-ig-imperial

برای نمایش راست‌به‌چپ در Interactive Grid از کلاس زیر استفاده کنید:

CSS Classes: persianDatepicker-ig-dir
Format Mask: YYYY/MM/DD HH24:MI

Interactive Report / Classic Report Column

برای ستون‌های Interactive Report یا Classic Report، Format Mask را به شکل زیر تنظیم کنید:

Format Mask: YYYY/MM/DD HH24:MI

برای نمایش صحیح جهت متن، یک Static ID برای ستون قرار دهید. نمونه:

Static ID: PERSIAN-DATE

سپس CSS زیر را برای نمایش صحیح جهت مقدار ستون اضافه کنید:

td[headers="PERSIAN-DATE"] {
  direction: ltr;
}

نمایش سال شاهنشاهی

برای نمایش تاریخ به‌صورت شاهنشاهی، در Query گزارش یا Grid از تابع
apexrad_util.jalali_to_imperial
استفاده کنید.

apexrad_util.jalali_to_imperial({FIELD_NAME}, 'YYYY/MM/DD HH24:MI')

نمونه نام آیتم در صفحه:

P10_BIRTH_DATE
P10_START_DATE
P10_END_DATE

نمونه مقدار ذخیره‌شده در Session State:

1405/01/10
1405/01/10 14:30

ویژگی‌ها و قابلیت‌ها

• انتخاب تاریخ شمسی/جلالی در Oracle APEX بدون نیاز به Date Picker خارجی
• پشتیبانی از نمایش ارقام فارسی در تقویم و ورودی نمایشی
• ذخیره Session State با ارقام لاتین برای پردازش ساده‌تر در SQL و PL/SQL
• پشتیبانی از فرمت‌های مختلف نمایش مثل YYYY/MM/DD، نام ماه فارسی و نام روز هفته
• امکان افزودن انتخاب ساعت و دقیقه با فرمت 24 ساعته
• محدودسازی تاریخ مجاز با Static Date یا Page Item
• تعریف تاریخ‌های استثنا و تعطیلات با متن Tooltip
• امکان غیرفعال‌کردن تعطیلات و جمعه‌ها
• حالت نمایش Popup یا Inline
• محدودسازی سال‌ها و ماه‌های قابل انتخاب
• پشتیبانی از تقویم جلالی و نمایش سال شاهنشاهی به‌صورت Display Only
• امکان تایپ دستی تاریخ در صورت فعال‌کردن Allow Manual Input

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

مزیت‌ها

• افزایش سرعت توسعه فرم‌های فارسی در APEX
• کاهش خطای ورود تاریخ به دلیل کنترل فرمت، بازه مجاز و تعطیلات
• تجربه کاربری بهتر برای کاربران فارسی‌زبان با DATE Type
• هماهنگی بهتر با فرم‌های سازمانی، منابع انسانی، مالی و اتوماسیون اداری
• امکان نگهداری داده‌ها در قالب استاندارد جلالی و قابل پردازش

کاربردهای رایج

• تاریخ تولد، تاریخ استخدام، تاریخ شروع و پایان قرارداد
• فیلتر تاریخ در گزارش‌ها و داشبوردها
• فرم‌های رزرو، نوبت‌دهی و ثبت درخواست
• فرم‌های مالی و اداری که نیاز به تاریخ شمسی دارند
• سناریوهایی که باید تعطیلات رسمی یا تاریخ‌های بسته بودن سیستم کنترل شوند

آموزش کامل Attributeها با مثال

Display Format

فرمتی که کاربر در فیلد نمایشی می‌بیند. این Attribute روی ظاهر مقدار در صفحه اثر دارد. نمونه‌ها:

نمونه کاربرد: اگر می‌خواهید کاربر مقدار 1405/01/10 14:30 را ببیند، Display Format را روی YYYY/MM/DD HH:MI قرار دهید.

Show Persian Digits

نمایش ارقام فارسی در تقویم و مقدار نمایشی. مقدار پیش‌فرض Yes است. اگر فعال باشد، کاربر عددها را مثل ۱۴۰۵/۰۱/۱۰ می‌بیند؛ اما Session State همچنان با ارقام لاتین ذخیره می‌شود.

Display: ۱۴۰۵/۰۱/۱۰
Session State: 1405/01/10

Show Today Button

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

Show Clear Button

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

Placeholder Text

متنی که وقتی هنوز تاریخی انتخاب نشده در فیلد نمایش داده می‌شود.

Minimum Date

نوع محدودیت حداقل تاریخ را مشخص می‌کند. گزینه‌ها:

• None: بدون محدودیت حداقل
• Item: خواندن حداقل تاریخ از یک Page Item
• Static: وارد کردن یک مقدار ثابت

نمونه: برای جلوگیری از انتخاب تاریخ قبل از سال 1400، مقدار را روی Static بگذارید و Minimum Static را تنظیم کنید.

Minimum Item

وقتی Minimum Date روی Item باشد استفاده می‌شود. این Attribute نام Page Itemای را می‌گیرد که مقدار حداقل تاریخ را نگه می‌دارد.

P10_MIN_DATE

نمونه کاربرد: در فرم بازه تاریخ، مقدار P10_END_DATE نباید قبل از P10_START_DATE باشد.

Minimum Static

وقتی Minimum Date روی Static باشد استفاده می‌شود. مقدار باید با فرمت تاریخ برگشتی پلاگین هماهنگ باشد.

1400/01/01
&P10_MIN_DATE.

Maximum Date

نوع محدودیت حداکثر تاریخ را مشخص می‌کند. گزینه‌ها:

• None: بدون محدودیت حداکثر
• Item: خواندن حداکثر تاریخ از یک Page Item
• Static: وارد کردن یک مقدار ثابت

نمونه: برای اینکه کاربر فقط تا پایان سال 1410 بتواند تاریخ انتخاب کند، مقدار را روی Static قرار دهید.

Maximum Item

وقتی Maximum Date روی Item باشد استفاده می‌شود. نمونه:

P10_MAX_DATE
P10_END_DATE

Maximum Static

وقتی Maximum Date روی Static باشد استفاده می‌شود. نمونه:

1410/12/29
&P10_MAX_DATE.

Show Time

انتخاب ساعت و دقیقه را به Date Picker اضافه می‌کند. مقدار پیش‌فرض No است. وقتی فعال باشد، مقدار Session State به شکل تاریخ + ساعت ذخیره می‌شود.

1405/01/10 14:30

نمونه کاربرد: فرم رزرو، زمان جلسه، نوبت‌دهی و ثبت رخداد.

Allow Manual Input

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

1405/07/03
1405/07/03 09:15

اگر کاربر تاریخ نامعتبر وارد کند، پلاگین مقدار را معتبر نمی‌داند.

Show On

مشخص می‌کند تقویم چگونه باز شود.

• Icon Click: فقط با کلیک روی آیکن تقویم باز می‌شود.
• Item Focus: با فوکوس یا کلیک روی فیلد هم باز می‌شود.

نمونه پیشنهادی: برای فرم‌های ساده Item Focus تجربه کاربری روان‌تری دارد؛ برای فرم‌های شلوغ Icon Click کنترل بیشتری می‌دهد.

Exception Dates

لیست تاریخ‌های استثنا، تعطیلی یا بسته بودن سیستم به‌صورت Comma Separated. این تاریخ‌ها در تقویم با رنگ متفاوت نمایش داده می‌شوند و ارقام فارسی هم پذیرفته می‌شود.

1405-05-01,1405-05-02,1405-07-03

Disable Holiday

اگر روی Yes باشد، تاریخ‌های تعطیل، Exception Dates و جمعه‌ها قابل انتخاب نیستند. نمونه کاربرد: سیستم نوبت‌دهی که در تعطیلات نباید وقت جدید ثبت شود.

Show Year

نمایش یا عدم نمایش کنترل سال در Header تقویم. مقدار پیش‌فرض Yes است. اگر تاریخ فقط در یک سال خاص استفاده می‌شود، می‌توانید سال را محدود کنید یا نمایش آن را ساده‌تر کنید.

Show Month

نمایش یا عدم نمایش ماه در Header تقویم. مقدار پیش‌فرض Yes است. با فعال بودن این گزینه، ماه به‌صورت Dropdown قابل انتخاب است.

Display As

نحوه نمایش تقویم را مشخص می‌کند.

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

نمونه کاربرد: برای فرم‌های معمولی Popup مناسب‌تر است؛ برای صفحه رزرو یا انتخاب تاریخ مهم، Inline می‌تواند بهتر باشد.

Year Range

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

1404,1405,1406,1407

نکته: وقتی Year Range تنظیم شود، فلش‌های قبلی/بعدی سال مخفی می‌شوند و انتخاب سال از Dropdown انجام می‌شود.

Month Range

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

01,03,06,07

نمونه کاربرد: اگر ثبت درخواست فقط در ماه‌های خاص مجاز است، از این Attribute استفاده کنید.

Holiday Dates

تعطیلات همراه با نام، به‌صورت JSON Array. تاریخ‌ها در تقویم مشخص می‌شوند و نام تعطیلی در Tooltip نمایش داده می‌شود.

[
  {
    "date": "1405-01-01",
    "name": "نوروز"
  },
  {
    "date": "1405-01-13",
    "name": "سیزده بدر"
  }
]

اگر Disable Holiday = Yes باشد، این تاریخ‌ها قابل انتخاب نیستند.

نمونه دریافت تعطیلات از API:

https://service.apexrad.info/iran/holidays?year=1405&token=MY_SECRET_TOKEN

برای دریافت توکن API با آدرس info@apexrad.info تماس بگیرید.

Calendar Year

نوع نمایش سال در تقویم، Dropdown سال و مقدار قابل مشاهده برای کاربر را کنترل می‌کند.

• Jalali: نمایش سال جلالی، مانند 1405/01/01
• Imperial: نمایش سال شاهنشاهی، یعنی سال جلالی + 1180

Jalali:   1405/01/01
Imperial: 2585/01/01

نکته مهم: این تنظیم فقط برای نمایش است. مقدار ذخیره‌شده و منطق داخلی همیشه بر اساس سال جلالی کار می‌کند.

تنظیم پیشنهادی سریع

• Display As = Popup
• Calendar Year = Jalali
• Display Format = YYYY/MM/DD
• Show Persian Digits = Yes
• Show Today Button = Yes
• Show Clear Button = Yes
• Show Time = No برای تاریخ ساده، یا Yes برای رزرو و نوبت‌دهی
• Allow Manual Input = No برای کنترل بیشتر، یا Yes برای کاربران حرفه‌ای

نمونه تنظیم برای فیلد تاریخ شروع و پایان:

P10_START_DATE:
  Minimum Date = Static
  Minimum Static = 1400/01/01

P10_END_DATE:
  Minimum Date = Item
  Minimum Item = P10_START_DATE