توابع کمکی JavaScript

این صفحه فقط helperهایی را پوشش می‌دهد که برای مصرف‌کننده‌ی Doravel در توسعه‌ی صفحه، فرم، تعاملات UI و تجربه‌ی کاربری مفید هستند. توابع داخلی که بیشتر برای توسعه‌ی خود پکیج یا زیرساخت کامپوننت‌ها استفاده می‌شوند، عمدا در اینجا مستند نشده‌اند.

راه‌اندازی و ابزارهای عمومی

`doravel.ready`

کدی را بعد از آماده‌شدن DOM اجرا می‌کند. اگر zone بدهید، callback فقط وقتی اجرا می‌شود که آن selector داخل context وجود داشته باشد.

پارامترها:

نام	نوع	توضیح
`callback`	`function`	تابعی که بعد از آماده‌شدن DOM اجرا می‌شود
`zone`	`string \| undefined`	selector اختیاری برای محدودکردن محل اجرا

نوع خروجی: void

نمونه خروجی: callback فقط بعد از آماده‌شدن DOM و در صورت وجود .x-panel اجرا می‌شود.

مثال
doravel.ready((context) => {
    $(".x-number-input-component .number-input", context).each((index, input) => {
        new NumberInputController(input);
    });
}, ".x-panel");

`delay`

یک Promise برمی‌گرداند تا بتوانید اجرای بخشی از کد را به تاخیر بیندازید.

پارامترها:

نام	نوع	توضیح
`ms`	`number`	مدت تاخیر بر حسب میلی‌ثانیه

نوع خروجی: Promise<void>

نمونه خروجی: ادامه اجرای کد پس از 500 میلی‌ثانیه انجام می‌شود.

مثال
await delay(500);
showToast("success", "اطلاعات بروزرسانی شد");

`debounce`

برای جلوگیری از اجرای پشت‌سرهم یک تابع در رویدادهایی مثل input یا keyup.

پارامترها:

نام	نوع	توضیح
`func`	`function`	تابع اصلی
`wait`	`number`	فاصله‌ی زمانی بین اجراها

نوع خروجی: function

نمونه خروجی: تابع searchUsers فقط 400ms بعد از توقف تایپ اجرا می‌شود.

مثال
const searchUsers = debounce(() => {
    console.log("search...");
}, 400);

$("#search").on("input", searchUsers);

`generateUUID`

یک شناسه‌ی یکتا برای use-caseهای سمت کاربر مثل ساخت ردیف موقت یا کلید آیتم‌های داینامیک تولید می‌کند.

پارامترها:
ندارد

نوع خروجی: string

نمونه خروجی: f65c57f6-a6aa-4b5d-9f4a-1c5b6e3f8a12

مثال
const rowId = generateUUID();

`mergeRecursive`

دو آبجکت یا آرایه را به صورت بازگشتی با هم ادغام می‌کند.

پارامترها:

نام	نوع	توضیح
`target`	`object \| array`	مقدار پایه
`source`	`object \| array`	مقدار جدید برای ادغام

نوع خروجی: object | array

نمونه خروجی: { modal: { size: "md", centered: true }, tags: ["base", "custom"] }

مثال
const defaults = { modal: { size: "md" }, tags: ["base"] };
const options = { modal: { centered: true }, tags: ["custom"] };

const result = mergeRecursive(defaults, options);

ترجمه و تبدیل داده

`__`

کلید ترجمه را از doravel.translations می‌خواند و placeholderها را جایگزین می‌کند.

پارامترها:

نام	نوع	توضیح
`key`	`string`	کلید ترجمه
`attributes`	`object`	مقادیر placeholderها

نوع خروجی: string

نمونه خروجی: "این فیلد الزامی است" و "12 کاراکتر"

مثال
__("validation.required");
__("text_area.character_count", { count: 12 });

`replacePersianDigits`

اعداد فارسی و عربی را به اعداد انگلیسی تبدیل می‌کند.

پارامترها:

نام	نوع	توضیح
`value`	`string`	متن ورودی

نوع خروجی: string

نمونه خروجی: "12345"

مثال
replacePersianDigits("۱۲۳۴۵"); // "12345"

`convertAmountToText`

عدد را به متن فارسی تبدیل می‌کند. برای نمایش مبلغ کنار فیلدهای عددی مناسب است.

پارامترها:

نام	نوع	توضیح
`amount`	`number`	مبلغ عددی
`suffix`	`string`	پسوند پولی مثل تومان

نوع خروجی: string | false

نمونه خروجی: "یک میلیون و دویست و پنجاه هزار تومان"

مثال
convertAmountToText(1250000); // "یک میلیون و دویست و پنجاه هزار تومان"

`getFormElementValueText`

متن نمایشی یک مقدار را از روی input/select/radio/checkbox پیدا می‌کند؛ مثلا وقتی لازم دارید به جای value، label را نمایش دهید.

پارامترها:

نام	نوع	توضیح
`name`	`string`	نام فیلد
`value`	`string \| number`	مقدار فیلد
`form`	`string \| jQuery \| null`	فرم هدف برای جستجوی محدود

نوع خروجی: string

نمونه خروجی: "ایران"

مثال
getFormElementValueText("country", "ir", "#profile-form");

پیام‌ها و بازخورد کاربر

`showAlert`

یک alert مبتنی بر SweetAlert2 نمایش می‌دهد.

پارامترها:

نام	نوع	توضیح
`type`	`string`	نوع پیام مثل `success` یا `error`
`message`	`string`	متن پیام
`title`	`string \| null`	عنوان اختیاری
`options`	`object`	تنظیمات اضافی SweetAlert2

نوع خروجی: Promise

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

مثال
showAlert("success", "اطلاعات با موفقیت ذخیره شد", "ثبت موفق");

`showToast`

برای اعلان‌های کوتاه و غیرمزاحم.

پارامترها:

نام	نوع	توضیح
`type`	`string`	نوع اعلان
`message`	`string`	متن اعلان
`title`	`string \| null`	عنوان اختیاری
`options`	`object`	تنظیمات toastr

نوع خروجی: void

نمونه خروجی: یک toast هشدار با متن مقدار این فیلد تغییر کرد نمایش داده می‌شود.

مثال
showToast("warning", "مقدار این فیلد تغییر کرد");

`showConfirmationMessage`

یک دیالوگ تایید نمایش می‌دهد و callbackهای onConfirm و onCancel می‌گیرد.

پارامترها:

نام	نوع	توضیح
`config`	`object`	تنظیمات پنجره تایید شامل title، text، type و callbackها

نوع خروجی: Promise

نمونه خروجی: یک دیالوگ تایید حذف باز می‌شود و در صورت تایید، فرم #delete-form submit می‌شود.

مثال
showConfirmationMessage({
    title: "حذف رکورد",
    text: "این عملیات قابل بازگشت نیست.",
    type: "danger",
    onConfirm: () => $("#delete-form").submit(),
});

`showComponentMessage`

برای نمایش پیام روی یک کامپوننت فرم. بسته به style می‌تواند پیام را به صورت inline، tooltip، toast یا alert نشان دهد.

پارامترها:

نام	نوع	توضیح
`config`	`object`	شامل `type`, `style`, `targetElement`, `message`, `title`, `formValidation`

نوع خروجی: void

نمونه خروجی: پیام خطای شماره موبایل نامعتبر است. کنار فیلد mobile نمایش داده می‌شود.

مثال
showComponentMessage({
    type: "error",
    style: "message",
    targetElement: "mobile",
    message: "شماره موبایل نامعتبر است.",
    formValidation: true,
});

`clearComponentMessage`

پیام قبلی یک فیلد را پاک می‌کند.

پارامترها:

نام	نوع	توضیح
`targetElement`	`string \| HTMLElement \| jQuery`	فیلد یا selector هدف
`formValidation`	`boolean \| null`	محدودکردن پاک‌سازی به پیام‌های validation

نوع خروجی: void

نمونه خروجی: پیام خطا یا راهنمای قبلی از فیلد #mobile حذف می‌شود.

مثال
clearComponentMessage("#mobile");

`clearFormMessages`

تمام پیام‌های فرم را پاک می‌کند.

پارامترها:

نام	نوع	توضیح
`form`	`string \| HTMLElement \| jQuery`	فرم هدف

نوع خروجی: void

نمونه خروجی: همه پیام‌های نمایش‌داده‌شده در فرم #profile-form پاک می‌شوند.

مثال
clearFormMessages("#profile-form");

لودینگ، وضعیت فرم و اعتبارسنجی

`toggleButtonLoading`

وضعیت loading دکمه‌های Doravel را روشن یا خاموش می‌کند.

پارامترها:

نام	نوع	توضیح
`targetElement`	`string \| HTMLElement \| jQuery`	دکمه هدف
`isLoading`	`boolean \| null`	روشن یا خاموش‌کردن loading
`text`	`string`	متن نمایش‌داده‌شده هنگام loading

نوع خروجی: void

نمونه خروجی: دکمه #submit-button غیرفعال می‌شود، loader نمایش داده می‌شود و متن آن به حالت پردازش تغییر می‌کند.

مثال
toggleButtonLoading("#submit-button", true);

`toggleFormElementLoading`

روی یک فیلد فرم spinner می‌گذارد و آن را موقتا غیرفعال می‌کند.

پارامترها:

نام	نوع	توضیح
`targetElement`	`string \| HTMLElement \| jQuery`	فیلد هدف
`isLoading`	`boolean \| null`	روشن یا خاموش‌کردن loading

نوع خروجی: void

نمونه خروجی: روی فیلد #city_id اسپینر نمایش داده می‌شود و فیلد موقتا غیرفعال می‌شود.

مثال
toggleFormElementLoading("#city_id", true);

`toggleLoading`

برای نمایش loading روی یک container یا section کامل.

پارامترها:

نام	نوع	توضیح
`targetElement`	`string \| HTMLElement \| jQuery`	ناحیه هدف
`isLoading`	`boolean \| null`	روشن یا خاموش‌کردن loading

نوع خروجی: void

نمونه خروجی: روی ناحیه #users-table-wrapper overlay لودینگ نمایش داده می‌شود.

مثال
toggleLoading("#users-table-wrapper", true);

`validateForm`

اعتبارسنجی کل فرم با jQuery Validate.

پارامترها:

نام	نوع	توضیح
`formSelector`	`string \| jQuery`	فرم هدف

نوع خروجی: void

نمونه خروجی: فرم validate می‌شود و خطاهای فیلدهای نامعتبر نمایش داده می‌شوند.

مثال
validateForm("#create-user-form");

`validateField`

فقط یک فیلد را validate می‌کند.

پارامترها:

نام	نوع	توضیح
`fieldSelector`	`string \| jQuery`	فیلد هدف

نوع خروجی: void

نمونه خروجی: فقط فیلد #email بررسی می‌شود و در صورت خطا پیام آن نمایش داده می‌شود.

مثال
validateField("#email");

`triggerOnChange`

وقتی یک فیلد تغییر می‌کند، فیلدهای وابسته را دوباره trigger و در صورت نیاز validate می‌کند. برای فرم‌های وابسته بسیار کاربردی است.

پارامترها:

نام	نوع	توضیح
`elementId`	`string`	شناسه فیلد اصلی
`dependentElementIds`	`string \| array`	شناسه یا لیست شناسه‌های وابسته
`callback`	`function \| undefined`	callback اختیاری بعد از trigger

نوع خروجی: void

نمونه خروجی: با تغییر province_id، فیلدهای city_id و district_id دوباره change می‌خورند و در صورت نیاز validate می‌شوند.

مثال
triggerOnChange("province_id", ["city_id", "district_id"]);

فرم، لینک و فایل

`addHiddenInputs`

چند input hidden را به صورت داینامیک به فرم اضافه می‌کند.

پارامترها:

نام	نوع	توضیح
`form`	`string \| HTMLElement \| jQuery`	فرم هدف
`inputs`	`object`	کلید و مقدار hidden inputها

نوع خروجی: void

نمونه خروجی: دو input hidden با نام‌های report_type و user_id به فرم #export-form اضافه می‌شود.

مثال
addHiddenInputs("#export-form", {
    report_type: "summary",
    user_id: 15,
});

`appendFilterQueryParamsToLinks`

پارامترهای فیلتر فعلی را به لینک‌های داخلی یک ناحیه اضافه می‌کند تا کاربر با حفظ فیلتر بین صفحات جابه‌جا شود.

پارامترها:

نام	نوع	توضیح
`hashKey`	`string \| undefined`	کلید فیلتر در query string
`containerSelector`	`string`	selector ناحیه‌ی شامل لینک‌ها

نوع خروجی: void

نمونه خروجی: لینک‌های داخلی #theme_app_content با query string فعلی مثل ?xfg=users-filter بروزرسانی می‌شوند.

مثال
appendFilterQueryParamsToLinks("xfg", "#theme_app_content");

`downloadFile`

فایل را از یک URL دانلود می‌کند و در صورت خطا toast نمایش می‌دهد.

پارامترها:

نام	نوع	توضیح
`url`	`string`	آدرس فایل
`filename`	`string`	نام فایل دانلودی

نوع خروجی: void

نمونه خروجی: فایل monthly-report.xlsx از آدرس مشخص‌شده دانلود می‌شود.

مثال
downloadFile("/reports/monthly", "monthly-report.xlsx");

افزونه‌های jQuery مرتبط با فرم

این helperها روی آبجکت jQuery اضافه شده‌اند و برای کار با کامپوننت‌های Doravel مفیدند.

`$(element).updateHint`

متن hint یک کامپوننت فرم را تغییر می‌دهد.

پارامترها:

نام	نوع	توضیح
`text`	`string`	متن جدید hint

نوع خروجی: jQuery

نمونه خروجی: hint فیلد به کد ملی باید 10 رقم باشد تغییر می‌کند.

مثال
$("#national_code").updateHint("کد ملی باید 10 رقم باشد");

`$(element).updateLabel`

لیبل فیلد را بروزرسانی می‌کند.

پارامترها:

نام	نوع	توضیح
`text`	`string`	متن جدید label

نوع خروجی: jQuery

نمونه خروجی: label فیلد به شماره موبایل اصلی تغییر می‌کند.

مثال
$("#mobile").updateLabel("شماره موبایل اصلی");

`$(element).disable`

دکمه‌ی Doravel را غیرفعال می‌کند و state داخلی آن را هم بروزرسانی می‌کند.

پارامترها:
ندارد

نوع خروجی: jQuery

نمونه خروجی: دکمه #save-button غیرفعال می‌شود و data-force-disabled="true" می‌گیرد.

مثال
$("#save-button").disable();

`$(element).enable`

دکمه‌ی Doravel را دوباره فعال می‌کند و state داخلی آن را هم بروزرسانی می‌کند.

پارامترها:
ندارد

نوع خروجی: jQuery

نمونه خروجی: دکمه #save-button دوباره فعال می‌شود و attribute غیرفعال‌سازی حذف می‌شود.

مثال
$("#save-button").enable();

`$(element).getInstance`

instance جاوااسکریپتی متصل به یک کامپوننت را برمی‌گرداند.

پارامترها:
ندارد

نوع خروجی: any

نمونه خروجی: یک instance جاوااسکریپتی مثل ButtonController {...} برگردانده می‌شود.

مثال
const instance = $("#save-button").getInstance();

`$(element).toggleConfirmation`

رفتار confirmation روی دکمه را روشن یا خاموش می‌کند.

پارامترها:

نام	نوع	توضیح
`state`	`boolean`	وضعیت فعال یا غیرفعال confirmation

نوع خروجی: jQuery | undefined

نمونه خروجی: کلیک روی #delete-button از این به بعد مودال تایید را فعال می‌کند.

مثال
$("#delete-button").toggleConfirmation(true);

`$(element).refreshComponent`

کامپوننت Livewire متصل به عنصر را refresh می‌کند.

پارامترها:

نام	نوع	توضیح
`resetParams`	`boolean`	اگر `true` باشد، پارامترها reset می‌شوند

نوع خروجی: jQuery

نمونه خروجی: component لایووایر مرتبط دوباره رندر می‌شود.

مثال
$("#users-table").refreshComponent();

`$(element).setComponentParams`

پارامترهای Livewire component را از سمت فرانت‌اند بروزرسانی می‌کند.

پارامترها:

نام	نوع	توضیح
`params`	`object`	پارامترهای جدید component

نوع خروجی: jQuery

نمونه خروجی: پارامترهای component به مقداری مثل { status: "active", search: "ali" } بروزرسانی می‌شوند.

مثال
$("#users-table").setComponentParams({
    status: "active",
    search: "ali",
});

موقعیت جغرافیایی و نقشه

`getDistanceBetweenPoints`

فاصله بین دو نقطه بر حسب متر را برمیگرداند

پارامترها:

نام	نوع	توضیح
`point1`	`{lat:number,lng:number}`	موقعیت جغرافیایی نقطه اول
`point2`	`{lat:number,lng:number}`	موقعیت جغرافیایی نقطه دوم

نوع خروجی: number

مثال
const point1 = {lat:53.5511,lng:9.9937}
const point2 = {lat:53.5436,lng:9.9882}
const distance = getDistanceBetweenPoints(point1,point2) // 909.68

`convertUtmToLatLng`

تبدیل موقعیت جغرافیایی بر حسب UTM به موقعیت جغرافیایی بر حسب longitude و latitude

پارامترها:

نام	نوع	توضیح
`point`	`{x:number,y:number,z:number}`	موقعیت جغرافیایی (x=Easting, y=Northing, z=zoneNumber)

نوع خروجی: {lat:number, lng:number}

مثال
const point = {x:565834.364,y:5934037.9516,z:32}
const latLngPoint = convertUtmToLatLng(point) // {lat: 53.5511, lng: 9.9936}

`convertLatLngToUtm`

تبدیل موقعیت جغرافیایی بر حسب longitude و latitude به موقعیت جغرافیایی بر حسب UTM

پارامترها:

نام	نوع	توضیح
`point`	`{lat:number,lng:number}`	موقعیت جغرافیایی (lat=latitude, lng=longitude)

نوع خروجی: {x:number,y:number,z:number}

مثال
const point = {lat:53.5511,lng:9.9937}
const utmPoint = convertLatLngToUtm(point) // {x: 565834.364, y: 5934037.9516, z: 32}

`calculateArea`

محاسبه مساحت منطقه محصور شده با آرایه ای از نقاط جغرافیایی بر حسب متر مربع

پارامترها:

نام	نوع	توضیح
`polygon`	`{lat:number,lng:number}[]`	آرایه ای از موقعیت های جغرافیایی (lat=latitude, lng=longitude)

نوع خروجی: number

مثال
const polygon = [
    {lng:9.9937, lat:53.5511},
    {lng:9.9950, lat:53.5511},
    {lng:9.9950, lat:53.5520},
    {lng:9.9937, lat:53.5520},
    {lng:9.9937, lat:53.5511},
]
const utmPoint = calculateArea(polygon) // 8594

`calculateCentroid`

محاسبه centroid آرایه ای از نقاط جغرافیایی

پارامترها:

نام	نوع	توضیح
`polygon`	`{lat:number,lng:number}[]`	آرایه ای از موقعیت های جغرافیایی (lat=latitude, lng=longitude)

نوع خروجی: {lat:number,lng:number}

مثال
const polygon = [
    {lng:9.9937, lat:53.5511},
    {lng:9.9950,lat:53.5511},
    {lng:9.9950, lat:53.5520},
    {lng:9.9937, lat:53.5520},
    {lng:9.9937, lat:53.5511},
]
const utmPoint = calculateCentroid(polygon) // {lng: 9.99435, lat: 53.55155}

`calculateCenterOfMath`

محاسبه centerOfMath آرایه ای از نقاط جغرافیایی

پارامترها:

نام	نوع	توضیح
`polygon`	`{lat:number,lng:number}[]`	آرایه ای از موقعیت های جغرافیایی (lat=latitude, lng=longitude)

نوع خروجی: {lat:number,lng:number}

مثال
const polygon = [
    {lng:9.9937, lat:53.5511},
    {lng:9.9950,lat:53.5511},
    {lng:9.9950, lat:53.5520},
    {lng:9.9937, lat:53.5520},
    {lng:9.9937, lat:53.5511},
]
const utmPoint = calculateCenterOfMath(polygon) // {lng: 9.99435, lat: 53.55155}

رسانه

`getVideoThumbnail`

از فایل یا URL ویدیو thumbnail می‌سازد و به صورت data URL برمی‌گرداند.

پارامترها:

نام	نوع	توضیح
`videoSource`	`string \| File`	فایل یا URL ویدیو
`options`	`object`	تنظیمات خروجی مثل `time`, `width`, `height`

نوع خروجی: Promise<string>

نمونه خروجی: رشته‌ای شبیه data:image/jpeg;base64,/9j/4AAQSkZJRg...

مثال
const thumbnail = await getVideoThumbnail(fileInput.files[0], {
    time: 2,
    width: 640,
    height: 360,
});

مودال

`setModalTitle`

عنوان (Title) یک مودال را با استفاده از شناسه المنت والد و مقدار جدید تغییر می‌دهد.

پارامترها:

نام	نوع	توضیح
`id`	`string`	شناسه (ID) المنت والد مودال
`newTitle`	`string`	عنوان جدیدی که باید در المنت دارای `data-modal-title` قرار گیرد

نوع خروجی: void

اگر المنت والد یا المنت دارای data-modal-title پیدا نشود، تابع بدون انجام عملیاتی خاتمه می‌یابد.

مثال
setModalTitle("userModal", "ویرایش اطلاعات کاربر");

راه‌اندازی و ابزارهای عمومی
ترجمه و تبدیل داده
پیام‌ها و بازخورد کاربر
لودینگ، وضعیت فرم و اعتبارسنجی
فرم، لینک و فایل
افزونه‌های jQuery مرتبط با فرم
موقعیت جغرافیایی و نقشه
رسانه
- getVideoThumbnail
مودال
- setModalTitle

راه‌اندازی و ابزارهای عمومی​

doravel.ready​

delay​

debounce​

generateUUID​

mergeRecursive​

ترجمه و تبدیل داده​

__​

replacePersianDigits​

convertAmountToText​

getFormElementValueText​

پیام‌ها و بازخورد کاربر​

showAlert​

showToast​

showConfirmationMessage​

showComponentMessage​

clearComponentMessage​

clearFormMessages​

لودینگ، وضعیت فرم و اعتبارسنجی​

toggleButtonLoading​

toggleFormElementLoading​

toggleLoading​

validateForm​

validateField​

triggerOnChange​

فرم، لینک و فایل​

addHiddenInputs​

appendFilterQueryParamsToLinks​

downloadFile​

افزونه‌های jQuery مرتبط با فرم​

$(element).updateHint​

$(element).updateLabel​

$(element).disable​

$(element).enable​

$(element).getInstance​

$(element).toggleConfirmation​

$(element).refreshComponent​

$(element).setComponentParams​

موقعیت جغرافیایی و نقشه​

getDistanceBetweenPoints​

convertUtmToLatLng​

convertLatLngToUtm​

calculateArea​

calculateCentroid​

calculateCenterOfMath​

رسانه​

getVideoThumbnail​

مودال​

setModalTitle​

راه‌اندازی و ابزارهای عمومی

`doravel.ready`

`delay`

`debounce`

`generateUUID`

`mergeRecursive`

ترجمه و تبدیل داده

`__`

`replacePersianDigits`

`convertAmountToText`

`getFormElementValueText`

پیام‌ها و بازخورد کاربر

`showAlert`

`showToast`

`showConfirmationMessage`

`showComponentMessage`

`clearComponentMessage`

`clearFormMessages`

لودینگ، وضعیت فرم و اعتبارسنجی

`toggleButtonLoading`

`toggleFormElementLoading`

`toggleLoading`

`validateForm`

`validateField`

`triggerOnChange`

فرم، لینک و فایل

`addHiddenInputs`

`appendFilterQueryParamsToLinks`

`downloadFile`

افزونه‌های jQuery مرتبط با فرم

`$(element).updateHint`

`$(element).updateLabel`

`$(element).disable`

`$(element).enable`

`$(element).getInstance`

`$(element).toggleConfirmation`

`$(element).refreshComponent`

`$(element).setComponentParams`

موقعیت جغرافیایی و نقشه

`getDistanceBetweenPoints`

`convertUtmToLatLng`

`convertLatLngToUtm`

`calculateArea`

`calculateCentroid`

`calculateCenterOfMath`

رسانه

`getVideoThumbnail`

مودال

`setModalTitle`