dovodi
/
Dovodi_Backend
3
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
73 Commits
1 Branch
0 Tags
70 MiB
 
 
Tree: 0a556b0fd1
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '0a556b0fd1'
${ noResults }
Dovodi_Backend/docs/MultiLanguageJSONWidget.md

5.2 KiB
Raw Blame History

MultiLanguageJSONWidget – توضیحات توصیفی (بدون کد)

هدف

  • ساخت یک ویجت سفارشی سازگار با Django Unfold برای مدیریت فیلدهای JSON چندزبانه در ادمین.
  • مدل داده: لیستی از آبجکت‌ها با کلیدهای language_code و title.
  • تجربه کاربری روان، هماهنگ با پالت رنگی و تم‌های Unfold (لایت/دارک)، و قابل استفاده در تمام اپ‌ها.

خلاصه‌ی کارهایی که انجام شد

  • ایجاد ویجت چندزبانه‌ای که:
    • کدهای زبان فعال را از مدل dj_language.models.Language (فقط status=True) می‌خواند و در صورت نبود، از settings.LANGUAGES استفاده می‌کند.
    • کدهای زبان را به‌صورت افقی نمایش می‌دهد؛ با اسکرول افقی که فقط روی hover ظاهر می‌شود (مانند سایدبار Unfold).
    • برای زبان‌های دارای مقدار، دکمه‌ی زبان را «پررنگ‌تر» نشان می‌دهد و این زبان‌ها را در ابتدای نوار قرار می‌دهد.
    • حالت فعال (Active) را با رنگ‌های primary مطابق پالت UNFOLD نمایش می‌دهد تا فعال بودن زبان واضح باشد.
    • برای هر زبان یک ورودی رندر می‌کند که «نوع ورودی» آن قابل تنظیم است: TextInput/Textarea/Wysiwyg (همگی نسخه‌های Unfold).
    • مقادیر موجود را شناسایی و در ورودی‌های مربوطه پیش‌نمایش می‌دهد.

ذخیره‌سازی و سازگاری با JSONField

  • برای سازگاری کامل با JSONField، مقدار نهایی در یک input پنهان به‌صورت «رشته‌ی JSON» نگه‌داری و ارسال می‌شود.
  • value_from_datadict رشته‌ی JSON معتبر تولید می‌کند تا خطای «نوع لیست» در پردازش فرم رخ ندهد.
  • ورودی اولیه می‌تواند یکی از حالت‌های زیر باشد و نرمال‌سازی می‌شود:
    • list[dict] مانند: [{'language_code': 'fa', 'title': '...'}]
    • dict تکی یا نگاشت کدزبان→مقدار
    • str شامل JSON که ابتدا parse می‌شود.

هماهنگی کامل با Unfold

  • استفاده از کلاس‌های استایل Unfold برای ورودی‌ها و وضعیت‌ها.
  • احترام به متغیرهای رنگی UNFOLD (base/primary/secondary/font) و تغییر خودکار استایل در لایت/دارک.
  • اسکرول‌بار با استایل هماهنگ و نمایش فقط هنگام hover.

قابل استفاده در تمام اپ‌ها (ماژولار)

  • کلاس ویجت به ماژول utils منتقل شد تا در هر اپی فقط با import قابل استفاده باشد.
  • تمپلیت ویجت به مسیر سراسری templates/ منتقل شد تا وابستگی به اپ خاصی نداشته باشد.
  • اسکریپت‌های موردنیاز در همان تمپلیت اینلاین شده‌اند؛ نیازی به فایل JS جدا نیست.

نحوه‌ی استفاده (مفهومی – بدون کد)

  • کلاس ویجت را از ماژول ابزارها ایمپورت کنید.
  • در فرم ادمین (Meta.widgets)، برای هر فیلد JSON موردنظر، ویجت را تنظیم کنید و «نوع ورودی» دلخواه را مشخص کنید (TextInput/Textarea/Wysiwyg نسخه Unfold).
  • پس از ذخیره، مقدار فیلد JSON به‌صورت list[{'language_code', 'title'}] تولید/به‌روزرسانی می‌شود.

نکات UX و رفتار

  • نمایش افقی کدهای زبان با اسکرول افقی روی hover.
  • حالت فعال با بوردر/پس‌زمینه‌ی primary مطابق پالت رنگی پروژه.
  • وقتی زبانِ خاصی مقدار دارد، دکمه‌ی آن پررنگ‌تر نمایش داده و به ابتدای لیست منتقل می‌شود.
  • فوکوس خودکار ورودی پس از فعال‌سازی زبان برای سرعت در ویرایش.

سناریوهای پشتیبانی‌شده

  • تعداد زیاد زبان‌ها (اسکرول افقی و بدون شکستن چیدمان).
  • مقداردهی اولیه از انواع مختلف (list/dict/string JSON).
  • تم تیره/روشن و تغییر خودکار رنگ‌ها.

محدودیت‌ها و ملاحظات

  • فرض بر این است که ساختار داده‌ی هدف، لیست آبجکت‌های {'language_code', 'title'} است.
  • برای ورودی‌های WYSIWYG، سیاست پاک‌سازی/اعتبارسنجی محتوای HTML به لایه‌های دیگر سپرده شده است.

نتیجه

  • یک ویجت چندبارمصرف، سازگار با Unfold، با UX دوستانه برای مدیریت محتوای چندزبانه در ادمین.
  • پیاده‌سازی به‌گونه‌ای است که بدون وابستگی به اپ خاص، در کل پروژه قابل استفاده باشد.