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

پلاگین APEXRAD Persian MoneyBox یک Item Type Plugin کاربردی برای Oracle APEX است که عددهای مبلغی را به شکل مناسب فارسی نمایش می‌دهد؛ یعنی می‌تواند عدد را با جداکننده سه‌رقمی، ارقام فارسی و متن حروفی تومان/ریال زیر فیلد نمایش دهد. این پلاگین برای Page Itemها و ستون‌های Interactive Grid قابل استفاده است.

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

• نحوه استفاده در Page Item و Interactive Grid

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

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

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

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

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

1. فایل پلاگین با نام item_type_plugin_info_apexrad_persianmoneybox.sql را دانلود کنید.
2. در Oracle APEX وارد مسیر Shared Components > Plug-ins شوید.
3. روی Import کلیک کنید.
4. فایل SQL پلاگین را انتخاب و Import کنید.
5. بعد از Import، در صفحه موردنظر یک Page Item یا ستون Interactive Grid بسازید.
6. Type آیتم یا ستون را روی APEXRAD Persian MoneyBox قرار دهید.
7. Attributeهای پلاگین مثل Show Letter، Show Separated، Maximum Digits و Min/Max Value را بر اساس نیاز تنظیم کنید.

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

P10_AMOUNT
P10_PRICE
P10_TOTAL_RIAL

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

1234567
25000000
985000000

نحوه استفاده در Page Item و Interactive Grid

استفاده به‌عنوان Page Item

1. در Page Designer یک آیتم جدید بسازید.
2. در بخش Identification، مقدار Type را روی APEXRAD Persian MoneyBox قرار دهید.
3. برای تجربه بهتر، Placeholder را مثل مبلغ را وارد کنید تنظیم کنید.
4. در بخش Attributes، گزینه‌های نمایش حروفی، جداکننده و محدودیت عددی را تنظیم کنید.

نمونه استفاده در Process یا SQL:

insert into payments (amount_rial)
values (to_number(:P10_AMOUNT));

استفاده در Interactive Grid

1. در ستون مبلغ Interactive Grid، مقدار Type را روی APEXRAD Persian MoneyBox قرار دهید.
2. برای ستون IG بهتر است از Format Mask خود APEX استفاده کنید.
3. پلاگین هنگام ذخیره، مقدار را به عدد خام تبدیل می‌کند تا APEX بتواند مقدار را درست ذخیره و Format Mask را اعمال کند.

نمونه Format Mask برای ستون IG:

999G999G999G990

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

• تبدیل عدد به حروف فارسی با نمایش تومان و ریال
• نمایش عدد ریالی به‌صورت سه‌رقمی جداشده، مثل 1,234,567 ریال
• امکان نمایش عدد جداشده با ارقام فارسی، مثل ۱,۲۳۴,۵۶۷ ریال
• پشتیبانی از Page Itemهای معمولی در فرم‌های APEX
• پشتیبانی کامل از ستون‌های Interactive Grid
• امکان استفاده هم‌زمان با Format Mask در Interactive Grid
• امکان محدودکردن تعداد رقم‌های مجاز
• امکان تعریف Minimum Value و Maximum Value
• امکان نمایش همیشگی متن حروفی بعد از خروج کاربر از فیلد
• کنترل چینش عدد در فیلد با گزینه‌های Start، Center و End
• جلوگیری از ورود کاراکترهای غیرعددی در سمت کاربر

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

مزیت‌ها

• افزایش خوانایی مبلغ‌های بزرگ در فرم‌های مالی
• کاهش خطای کاربر هنگام واردکردن مبلغ‌های ریالی
• نمایش هم‌زمان عدد و متن حروفی برای کنترل بهتر مبلغ
• تجربه کاربری فارسی‌تر و حرفه‌ای‌تر در برنامه‌های Oracle APEX
• کاهش نیاز به کدنویسی JavaScript و CSS اختصاصی برای فیلدهای مبلغ
• هماهنگی بهتر با فرم‌های حسابداری، فروش، خزانه‌داری و ثبت پرداخت

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

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

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

Show Mask

اگر روی Yes باشد، هنگام تایپ در Page Item عدد با جداکننده سه‌رقمی نمایش داده می‌شود. این گزینه برای Page Itemها مناسب است؛ در Interactive Grid بهتر است از Format Mask ستون استفاده کنید.

Show Mask = Yes
User types: 1234567
Displayed while typing: 1,234,567

Maximum Digits

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

Maximum Digits = 12
Allowed:     999999999999
Not allowed: 1000000000000

Show Letter

اگر روی Yes باشد، پلاگین مقدار عددی را زیر فیلد به حروف فارسی نمایش می‌دهد. این نمایش بر اساس تومان و ریال ساخته می‌شود؛ یعنی هر 10 ریال برابر 1 تومان در نظر گرفته می‌شود.

Show Letter = Yes
Input value = 1234567

 صد و بیست و سه هزار و چهارصد و پنجاه و شش تومان و هفت ریال

Always Displayed

این Attribute فقط وقتی نمایش داده می‌شود که Show Letter = Yes باشد. اگر روی Yes باشد، متن حروفی بعد از خروج کاربر از فیلد هم قابل مشاهده می‌ماند.

Show Letter = Yes
Always Displayed = Yes
Result: letter text remains visible after blur

Show Separated

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

Show Separated = Yes
Input value = 25000000
Separated text = 25,000,000 ریال

Show Persian Digits

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

Show Separated = Yes
Show Persian Digits = Yes
Input value = 25000000
Displayed text = ۲۵,۰۰۰,۰۰۰ ریال

Number Alignment

چینش متن عددی داخل فیلد را کنترل می‌کند. گزینه‌های قابل استفاده: Start، Center و End. برای فیلدهای مبلغ معمولا End انتخاب مناسبی است.

Number Alignment = End
Result: 1234567 is aligned at the end of the input

Number Alignment = Center
Result: 1234567 is centered in the input

Minimum Value

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

Minimum Value = 10000
Empty item default = 10000
User value 5000 is below the allowed minimum

Maximum Value

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

Maximum Value = 500000000
Allowed:     499999999
Not allowed: 500000001

نمونه تنظیم کامل یک Page Item

Item Name = P10_AMOUNT
Type = APEXRAD Persian MoneyBox
Show Mask = Yes
Maximum Digits = 12
Show Letter = Yes
Always Displayed = Yes
Show Separated = Yes
Show Persian Digits = Yes
Number Alignment = End
Minimum Value = 10000
Maximum Value = 500000000

نمونه تنظیم کامل یک ستون Interactive Grid

Column Name = AMOUNT_RIAL
Type = APEXRAD Persian MoneyBox
Format Mask = 999G999G999G990
Show Mask = No
Show Letter = Yes
Show Separated = Yes
Number Alignment = End

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

• Show Mask = Yes برای Page Itemها
• Show Mask = No برای Interactive Grid و استفاده از Format Mask ستون
• Maximum Digits = 12 یا 16 بسته به سقف مبلغ‌های سیستم
• Show Letter = Yes برای فرم‌های مالی حساس
• Always Displayed = Yes وقتی کنترل مبلغ بعد از خروج از فیلد هم مهم است
• Show Separated = Yes برای خوانایی بهتر مبلغ ریالی
• Show Persian Digits = Yes برای رابط کاربری کاملا فارسی
• Number Alignment = End برای فیلدهای مبلغ
• Minimum Value = 0 یا حداقل مبلغ مجاز کسب‌وکار
• Maximum Value = سقف مبلغ مجاز در سیستم شما

نمونه نهایی برای یک فرم پرداخت:

P20_PAYMENT_AMOUNT:
  Type = APEXRAD Persian MoneyBox
  Show Mask = Yes
  Maximum Digits = 12
  Show Letter = Yes
  Always Displayed = Yes
  Show Separated = Yes
  Show Persian Digits = Yes
  Number Alignment = End
  Minimum Value = 10000
  Maximum Value = 999999999999