بلوک‌های سازنده¶

بلوک‌های سازنده که با نام snippets نیز شناخته می‌شوند، روشی هستند که کاربران با آن صفحات را طراحی و چیدمان می‌کنند. آن‌ها عناصر XML مهمی در طراحی شما هستند.

بلوک‌های سازنده به دو نوع طبقه‌بندی می‌شوند:

بلوک‌های ساختاری: به‌صورت بصری به‌عنوان «ردیف‌های کامل» استفاده می‌شوند و در چند دسته توزیع شده‌اند (Intro، Columns، Content، Images، People و غیره)
بلوک‌های محتوای داخلی: داخل سایر بلوک‌های سازنده استفاده می‌شوند

در پایان این فصل، قادر خواهید بود اسنیپت‌های سفارشی ایجاد کنید و آن‌ها را به یک دستهٔ اختصاصی اضافه کنید.

ساختار فایل¶

قالب‌های نما در views/snippets/ قرار دارند:

views
└── snippets
    ├── snippets.xml
    └── s_snippet_name.xml

assets سمت کلاینت در static/src/ قرار دارند و بر اساس هدف گروه‌بندی شده‌اند:

static
└── src
   ├── snippets
   │   └── s_snippet_name
   │       ├── snippet_name.js
   │       ├── snippet_name.edit.js
   │       ├── 000.scss
   │       └── 000.xml
   └── website_builder
       ├── snippet_name_option.js
       ├── snippet_name_option.xml
       └── snippet_name_option_plugin.js

همچنین ببینید

رجیستری snippets و groups در XML

نکته

فایل‌های JS در زیر /snippets تعاملات هستند: مثال با snippet s_floating_blocks و کلاس پایهٔ Interaction.

صفحهٔ دمو

برای دسترسی به این صفحه باید داده‌های دمو نصب شوند:

https://your-database.com/website/demo/snippets

چیدمان¶

snippetها توسط کاربر با استفاده از ابزار ساخت وب‌سایت قابل ویرایش هستند. برخی کلاس‌های Bootstrap مهم‌اند زیرا برخی گزینه‌های ابزار ساخت وب‌سایت را فعال می‌کنند.

Wrapper¶

ظرف اصلی استاندارد هر snippet یک section است. هر عنصر section مانند یک بلوک محتوا قابل ویرایش است که می‌توانید جابه‌جا یا کپی کنید.

<section class="s_snippet_name" data-name="..." data-snippet="...">
   <!-- Content -->
</section>

برای snippetهای محتوای داخلی، هر تگ HTML دیگری قابل استفاده است.

<div class="s_snippet_name" data-name="..." data-snippet="...">
   <!-- Content -->
</div>

صفت	توضیحات
class	نام کلاس یکتا برای این snippet
data-name	در پنل سمت راست به‌عنوان نام snippet نمایش داده می‌شود. اگر یافت نشود، به Block بازخواهد گشت.
data-snippet	توسط سیستم برای شناسایی snippet استفاده می‌شود

سیستم به‌طور خودکار ویژگی‌های data-name و data-snippet را در طول drag and drop بر اساس نام قالب اضافه می‌کند.

هشدار

آن ویژگی‌ها باید به‌طور خاص هنگامی که یک snippet در یک صفحهٔ قالب اعلان می‌شود، اضافه شوند.

هشدار

از افزودن یک تگ section داخل یک تگ section دیگر بپرهیزید: این کار، گزینه‌های ابزار ساخت وب‌سایت را دو بار فعال خواهد کرد. به جای آن می‌توانید از snippetهای محتوای داخلی استفاده کنید.

نکته

برای نوشتن محتوای یک صفحهٔ ایستا با snippetهای استاندارد، دو رویکرد ممکن وجود دارد:

پیش‌ساخت صفحات ایستای سفارشی با ابزار ساخت وب‌سایت: snippetها را drag & drop کنید، سپس
کد را در فایل خود copy/paste کنید و آن را تمیز کنید.

یا

همه چیز را مستقیماً کدنویسی کنید: اما مراقب سازگاری با ابزار ساخت وب‌سایت باشید. این
نیازمند کلاس‌ها، نام‌ها، id، data و غیره خاصی است تا به‌درستی کار کند. رویه‌ای خوب این است که کد snippetهای ایجادشده در کد استاندارد را در فایل‌های منبع Odoo جستجو کنید. توجه کنید که ابزار ساخت وب‌سایت گاهی پس از drop کردن snippet در صفحه، کلاس‌هایی به آن اضافه می‌کند.

عناصر¶

فهرستی از «ویژگی‌ها» وجود دارد که می‌توانیم با استفاده از کلاس‌های CSS خاص آن‌ها را فعال/غیرفعال کنیم.

اندازه‌گذاری¶

هر ستون بزرگ Bootstrap که مستقیماً از یک عنصر .row نازل شده (با رعایت ساختار Bootstrap)، توسط ابزار ساخت وب‌سایت فعال خواهد شد تا قابل تغییر اندازه باشد.

.row > .col-lg-*

افزودن padding به ستون‌ها و <section>.

class="pt80 pb80"

توجه

pb* و pt* کلاس‌های Odoo هستند که برای کنترل handlerها استفاده می‌شوند. مقادیر آن‌ها با مضارب ۸ افزایش می‌یابند، تا حداکثر ۲۵۶ (۰، ۸، ۱۶، ۲۴، ۳۲، ۴۰، ۴۸، ...).

selector ستون‌ها را فعال کنید.

<div class="container s_allow_columns">

گزینهٔ تعداد ستون‌ها را غیرفعال کنید.

<div class="row s_nb_column_fixed">

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

<div class="row s_col_no_resize">

گزینهٔ اندازه را برای یک ستون خاص غیرفعال کنید.

<div class="col-lg-* s_col_no_resize">

رنگ‌ها¶

افزودن پس‌زمینه بر اساس پالت رنگ برای ستون‌ها و <section>.

class="o_cc o_cc*"

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

<div class="row s_col_no_bgcolor">

گزینهٔ رنگ پس‌زمینه را برای یک ستون خاص غیرفعال کنید.

<div class="col-lg-* s_col_no_bgcolor">

افزودن یک فیلتر رنگ مشکی با opacity 50%.

<section>
   <div class="o_we_bg_filter bg-black-50" />
   <div class="container">
      <!-- Content -->
   </div>
</section>

افزودن یک فیلتر رنگ سفید با opacity 85%.

<section>
   <div class="o_we_bg_filter bg-white-85" />
   <div class="container">
      <!-- Content -->
   </div>
</section>

افزودن یک فیلتر رنگ سفارشی.

<section>
   <div class="o_we_bg_filter" style="background-color: rgba(39, 110, 114, 0.54) !important;" />
   <div class="container">
      <!-- Content -->
   </div>
</section>

افزودن یک فیلتر گرادیان سفارشی.

<section>
   <div class="o_we_bg_filter" style="background-image: linear-gradient(135deg, rgba(255, 204, 51, 0.5) 0%, rgba(226, 51, 255, 0.5) 100%) !important;" />
   <div class="container">
      <!-- Content -->
   </div>
</section>

ویژگی‌ها¶

مناطق غیرقابل ویرایش¶

یک عنصر را غیرقابل ویرایش کنید.

<div class="o_not_editable">

یک عنصر را غیرقابل حذف کنید.

<div class="oe_unremovable">

پس‌زمینه‌ها¶

افزودن یک تصویر پس‌زمینه و وسط‌چین کردن آن.

<div class="oe_img_bg o_bg_img_center" style="background-image: url('...')">

افزودن افکت parallax.

<section
   class="parallax s_parallax_is_fixed s_parallax_no_overflow_hidden"
   data-scroll-background-ratio="1">
   <span
      class="s_parallax_bg oe_img_bg o_bg_img_center"
      style="background-image: url('...'); background-position: 50% 75%;" />
   <div class="container">
      <!-- Content -->
   </div>
</section>

توجه

یک پس‌زمینهٔ ویدئویی را می‌توان روی یک section تنظیم کرد. به فصل Media این اسناد مراجعه کنید.

هایلایت متن¶

هایلایت‌های متن، فایل‌های SVG هستند که می‌توان آن‌ها را روی کلمات یا عبارات خاص ادغام کرد تا بر آن‌ها تأکید شود. هایلایت‌های متن گزینه‌های قابل سفارشی‌سازی برای رنگ و ضخامت ارائه می‌دهند.

<h2>
   Title with
   <span
      class="o_text_highlight o_text_highlight_fill"
      style="--text-highlight-width: 10px !important; --text-highlight-color: #FFFF00;">
      <span class="o_text_highlight_item">
         highlighted text
         <svg fill="none" class="o_text_highlight_svg o_content_no_merge position-absolute overflow-visible top-0 start-0 w-100 h-100 pe-none">
            <!-- SVG path -->
         </svg>
      </span>
   </span>
</h2>

ویژگی سفارشی CSS	توضیحات
`--text-highlight-width`	ضخامت لبه‌های SVG
`--text-highlight-color`	رنگ شیء SVG

چیدمان Grid¶

Grid Layout سیستمی قدرتمند و انعطاف‌پذیر در CSS است که به کاربران امکان می‌دهد چیدمان‌های پیچیدهٔ بلوک سازنده را به آسانی طراحی کنند.

استفاده¶

Grid Layout را با افزودن کلاس CSS o_grid_mode به row فعال کنید. تعداد ردیف‌ها در grid شما با ویژگی data-row-count تعریف می‌شود. grid همیشه شامل ۱۲ ستون است. grid gap که در ویژگی style مشخص می‌شود، فاصله‌ها (یا gutterها) بین ردیف‌ها و ستون‌ها را تعیین می‌کند.

<div class="row o_grid_mode" data-row-count="13" style="gap: 20px 10px">
   <!-- Content -->
</div>

آیتم‌ها در یک grid¶

آیتم‌ها را با کلاس o_grid_item به grid اضافه کنید. اگر آیتم grid حاوی یک تصویر باشد، از کلاس o_grid_item_image استفاده کنید.

<div class="row o_grid_mode" data-row-count="13">
   <div class="o_grid_item g-height-* g-col-lg-*" style="grid-area: 2 / 1 / 7 / 8; z-index: 3;">
      <!-- Content -->
   </div>
   <div class="o_grid_item o_grid_item_image g-height-* g-col-lg-*" style="grid-area: 1 / 6 / 9 / 13; z-index: 2;">
      <img src="..." alt="..." >
   </div>
</div>

ابعاد و موقعیت یک آیتم grid با grid-area تعریف می‌شوند که می‌تواند به‌صراحت در ویژگی style به همراه z-index تنظیم شود.

کلاس‌های g-height-* و g-col-lg-* توسط ابزار ساخت وب‌سایت برای اهداف ویرایش تولید می‌شوند.

padding آیتم grid¶

<div class="row o_grid_mode" data-row-count="13" style="gap: 20px 10px;">
   <div class="o_grid_item g-height-* g-col-lg-*" style="--grid-item-padding-y: 20px; --grid-item-padding-x: 15px; grid-area: 2 / 1 / 7 / 8; z-index: 3;">
      <!-- Content -->
   </div>
</div>

ویژگی سفارشی CSS	توضیحات
`--grid-item-padding-y`	paddingهای عمودی (محور Y)
`--grid-item-padding-x`	paddingهای افقی (محور X)

سیستم سازگاری¶

وقتی یک snippet دارای ویژگی data-vcss، data-vjs و/یا data-vxml است، به این معنی است که این یک نسخهٔ به‌روزرسانی‌شده: است، نه نسخهٔ اصلی.

<section class="s_snippet_name" data-vcss="001" data-vxml="001" data-vjs="001">
   <!-- Content -->
</section>

این ویژگی‌های data به سیستم نشان می‌دهند که کدام نسخهٔ فایل را برای آن snippet بارگذاری کند (مثلاً 001.js، 002.scss).

snippet سفارشی¶

برخی نیازهای خاص‌تر نیازمند ایجاد snippetهای سفارشی هستند. در ادامه چگونگی ایجاد یک snippet سفارشی آمده است/

قالب¶

ابتدا قالب snippet را ایجاد کنید. سپس آن را به فهرست اضافه کنید و آن را از طریق ابزار ساخت وب‌سایت در دسترس قرار دهید.

۱. اعلان¶

ابتدا قالب snippet سفارشی را ایجاد کنید:

/website_airproof/views/snippets/s_airproof_snippet.xml¶

<?xml version="1.0" encoding="utf-8"?>
<odoo>

   <template id="s_airproof_snippet" name="...">
      <section class="s_airproof_snippet">
         <!-- Content -->
      </section>
   </template>

</odoo>

هشدار

ویژگی‌های data-name و data-snippet باید هنگامی که یک snippet در یک صفحهٔ قالب اعلان می‌شود، مشخص شوند. در غیر این صورت، snippet توسط ابزار ساخت وب‌سایت شناسایی نخواهد شد و هرگاه ارتقای پایگاه‌داده انجام شود، ممکن است مشکلاتی رخ دهد. علاوه بر این، به یاد داشته باشید که ویژگی name به‌عنوان نام snippet سفارشی شما در بخش Blocks پنل گزینه‌ها نمایش داده می‌شود.

نکته

تا حد ممکن از کلاس‌های بومی Bootstrap استفاده کنید.
همهٔ کلاس‌های سفارشی خود را پیشوند بدهید.
برای نام‌گذاری کلاس‌ها از نوتیشن lowercase با underscore استفاده کنید، مثلاً .x_nav، .x_nav_item.
از استفاده از ویژگی ID درون section خود پرهیز کنید زیرا چندین نمونه از یک snippet ممکن است در سراسر صفحه ظاهر شود (ویژگی ID باید در یک صفحه یکتا باشد).

snippet سفارشی را به فهرست snippetهای استاندارد اضافه کنید، تا کاربر بتواند آن را مستقیماً از پنل ویرایش، روی صفحه drag and drop کند.

۲. ایجاد گروه¶

یک گروه را در بالای فهرست اضافه کنید (در صورت نیاز در این فهرست در هر جا قرار دهید).

/website_airproof/views/snippets/snippets.xml¶

<template id="snippets" inherit_id="website.snippets" name="Airproof - Snippets">
   <!-- Create the group -->
   <xpath expr="//snippets[@id='snippet_groups']/*[1]" position="before">
      <t snippet-group="airproof"
         t-snippet="website.s_snippet_group"
         string="Airproof"
         t-thumbnail="/website_airproof/static/src/img/wbuilder/s_airproof_group_thumbnail.svg" />
   </xpath>
</template>

صفت	توضیحات
snippet-group	ID گروه
t-snippet	ID قالب ارث‌برده شده
string	نام گروه که به کاربران نمایش داده می‌شود
t-thumbnail	مسیر به thumbnail گروه

۱. افزودن snippet¶

سپس snippet سفارشی را به <snippets id="snippet_structure"> اضافه کنید که حاوی همهٔ موارد موجود در همان سطح است. ابزار ساخت وب‌سایت با خواندن ویژگی group در <t t-snippet=""> آن‌ها را به‌طور خودکار به دسته‌ها تقسیم خواهد کرد

/website_airproof/views/snippets/snippets.xml¶

<template id="snippets" inherit_id="website.snippets" name="Airproof - Snippets">
   <!-- Create the group -->
   <xpath expr="//snippets[@id='snippet_groups']/*[1]" position="before">
      <t snippet-group="airproof"
         t-snippet="website.s_snippet_group"
         string="Airproof" t-thumbnail="/website_airproof/static/src/img/wbuilder/s_airproof_group_thumbnail.svg" />
   </xpath>

   <!-- Add the custom snippet to the group -->
   <xpath expr="//snippets[@id='snippet_structure']/*[1]" position="before">
      <t t-snippet="website_airproof.s_airproof_snippet" string="Custom snippet" group="airproof">
         <keywords>Snippet</keywords>
      </t>
   </xpath>
</template>

صفت	توضیحات
t-snippet	قالب snippet برای استفاده
group	گروهی که snippet در آن اضافه می‌شود.
<keywords>	کلمات کلیدی که کاربر در فیلد جستجو در پنل Snippets وارد می‌کند

snippet محتوای داخلی¶

برای اینکه یک snippet سفارشی در فهرست Inner content ظاهر شود، آن را به‌جای آن به snippet_content اضافه کنید:

/website_airproof/views/snippets/snippets.xml¶

<template id="snippets" inherit_id="website.snippets" name="Airproof - Snippets">
   <!-- Add the custom snippet to the group -->
   <xpath expr="//snippets[@id='snippet_content']/*[1]" position="before">
      <t t-snippet="website_airproof.s_airproof_snippet"
         string="Custom snippet"
         t-thumbnail="/website_airproof/static/src/img/wbuilder/s_airproof_snippet.svg" />
   </xpath>
</template>

selectorهای محتوای داخلی¶

برای تبدیل یک snippet سفارشی به «محتوای داخلی» (قابل drop در بلوک سازنده دیگر)، selector آن را به منبع so_content_addition_selector اضافه کنید که حاوی همهٔ selectorها برای بلوک‌های سازندهٔ محتوای داخلی موجود است.

/website_airproof/static/src/website_builder/airproof_snippet_option_plugin.js¶

export class AirproofSnippetOptionPlugin extends Plugin {
   static id = "airproofSnippetOption";
   resources = {
      so_content_addition_selector: [".s_airproof_snippet"],
   };
}

مهم

فراموش نکنید یک t-thumbnail اضافه کنید و ویژگی group را حذف کنید، زیرا این نوع از بلوک‌های سازنده مستقیماً در پنل گزینه‌های سمت راست ابزار ساخت وب‌سایت در دسترس است.
فراموش نکنید snippet را به فهرست همهٔ snippetهای «محتوای داخلی» موجود اضافه کنید.

گزینه‌ها¶

گزینه‌ها به کاربران اجازه می‌دهند ظاهر و رفتار snippet را با استفاده از ابزار ساخت وب‌سایت ویرایش کنند. گزینه‌ها کامپوننت‌های OWL هستند که در JavaScript تعریف و با قالب‌های XML رندر می‌شوند. هر گزینه از طریق یک builder plugin ثبت می‌شود و در assets ویرایشگر بارگذاری می‌شود.

توجه

فایل‌های JavaScript و XML را به باندل website.website_builder_assets در ماژول خود اضافه کنید.

همچنین ببینید

کامپوننت و قالب¶

کامپوننت گزینه را تعریف کنید و آن را در یک builder plugin ثبت کنید.

/website_airproof/static/src/website_builder/airproof_snippet_option_plugin.js¶

import { BaseOptionComponent } from "@html_builder/core/utils";
import { Plugin } from "@html_editor/plugin";
import { registry } from "@web/core/registry";

export class AirproofSnippetOption extends BaseOptionComponent {
   static template = "website_airproof.AirproofSnippetOption";
   static selector = ".s_airproof_snippet";
   static applyTo = ":scope > .row";
}

export class AirproofSnippetOptionPlugin extends Plugin {
   static id = "airproofSnippetOption";
   resources = {
      builder_options: [AirproofSnippetOption],
   };
}

registry.category("website-plugins").add(
   AirproofSnippetOptionPlugin.id,
   AirproofSnippetOptionPlugin
);

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

/website_airproof/static/src/website_builder/airproof_snippet_option.xml¶

<templates xml:space="preserve">
   <t t-name="website_airproof.AirproofSnippetOption">
      <BuilderRow label.translate="Layout">
         <BuilderSelect>
            <BuilderSelectItem classAction="''">Default</BuilderSelectItem>
            <BuilderSelectItem classAction="'s_airproof_snippet_portrait'">Portrait</BuilderSelectItem>
            <BuilderSelectItem classAction="'s_airproof_snippet_square'">Square</BuilderSelectItem>
            <BuilderSelectItem classAction="'s_airproof_snippet_landscape'">Landscape</BuilderSelectItem>
         </BuilderSelect>
      </BuilderRow>
      <BuilderRow label.translate="Space">
         <BuilderButtonGroup>
            <BuilderButton classAction="'mt-0'">1</BuilderButton>
            <BuilderButton classAction="'mt-3'">2</BuilderButton>
            <BuilderButton classAction="'mt-5'">3</BuilderButton>
         </BuilderButtonGroup>
      </BuilderRow>
   </t>
</templates>

منطق گزینه¶

رفتار گزینه را در JavaScript روی کلاس BaseOptionComponent تعریف کنید و هر BuilderAction استفاده‌شده توسط قالب را در منابع builder plugin ثبت کنید.

Plugin API¶

builder pluginها کامپوننت‌های گزینه، اکشن‌ها و hookهای ویرایشگر را از طریق شیء resources ثبت می‌کنند. آن‌ها به دستهٔ رجیستری website-plugins اضافه می‌شوند تا توسط ویرایشگر قابل دسترسی باشند. نمونه‌های plugin هنگام شروع ویرایشگر ایجاد می‌شوند و هنگام بسته شدن ویرایشگر از بین می‌روند؛ آن‌ها برای کل جلسهٔ ویرایشگر زنده هستند.

ویژگی	هدف
`static dependencies`	pluginهای موردنیاز را پیش از اجرای setup اعلان کنید.
`static shared`	متدهای مشترک را برای سایر pluginها در دسترس قرار دهید.
`setup()`	حالت plugin را مقداردهی اولیه کنید.

منابع	هدف
`builder_options`	کلاس‌های `BaseOptionComponent` را برای پنل گزینه‌ها ثبت کنید.
`builder_actions`	کلاس‌های `BuilderAction` که توسط قالب‌های گزینه ارجاع داده شده‌اند را ثبت کنید.
`dropzone_selector`	قواعد drop snippet را تعریف کنید (`selector`، `dropIn`، `dropNear`، `exclude`، `excludeNearParent`).
`so_content_addition_selector`	فهرست selectorهای محتوای داخلی را گسترش دهید.
هندلرها	hookهای چرخهٔ عمر ویرایشگر که روی plugin ثبت می‌شوند.
`on_snippet_dropped_handlers`	پس از drop شدن یک snippet و درج در DOM فراخوانی می‌شود.
`on_cloned_handlers`	پس از کلون شدن یک عنصر و درج آن در DOM فراخوانی می‌شود.
`on_will_remove_handlers`	درست قبل از حذف یک عنصر فراخوانی می‌شود.
`on_removed_handlers`	پس از حذف یک عنصر فراخوانی می‌شود.
`clean_for_save_handlers`	روی یک کلون تمیز شده از DOM قبل از ذخیره فراخوانی می‌شود.
`before_save_handlers`	در ابتدای فرآیند ذخیره فراخوانی می‌شود.
`after_save_handlers`	پس از تکمیل فرآیند ذخیره فراخوانی می‌شود.

همچنین ببینید

فهرست کامل منابع

BaseOptionComponent API¶

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

ویژگی	توضیحات
`static template`	نام قالب OWL که در پنل گزینه‌ها رندر می‌شود.
`static selector`	CSS selectorی که گزینه را به عناصر متصل می‌کند.
`static exclude`	CSS selector عناصری که باید از مطابقت استثنا شوند.
`static applyTo`	CSS selectorی که عنصر فرزند snippet مطابقت‌یافته را هدف می‌گیرد.
`static components`	کامپوننت‌های builder فرزند که در قالب استفاده می‌شوند.
`setup()`	حالت کامپوننت را مقداردهی اولیه کنید.

اتصال¶

selector¶

کامپوننت‌های گزینه یک ویژگی selector اعلان می‌کنند که زمان ظاهر شدن آن‌ها را کنترل می‌کند.

selector کامپوننت گزینه را به عناصری که با یک CSS selector (کلاس، ID و غیره) مطابقت دارند متصل می‌کند. این گزینه وقتی یک عنصر مطابقت‌یافته انتخاب شود، ظاهر می‌شود.

export class AirproofSnippetOption extends BaseOptionComponent {
   static selector = "section, h1, .custom_class, #custom_id";
}

می‌توان آن را در ترکیب با exclude یا applyTo استفاده کرد.

applyTo¶

applyTo به گزینه اجازه می‌دهد بر روی یک عنصر فرزند selectorِ مطابقت‌یافته اعمال شود.

export class AirproofSnippetOption extends BaseOptionComponent {
   static selector = ".s_airproof_snippet";
   static applyTo = ".row";
}

exclude¶

exclude selectorهای خاص را از مطابقت حذف می‌کند.

اگر یک تگ <ul> (بدون کلاس .navbar-nav) انتخاب شده باشد، گزینه ظاهر می‌شود¶

export class AirproofSnippetOption extends BaseOptionComponent {
   static selector = "ul";
   static exclude = ".navbar-nav";
}

dropzone_selector (dropIn)¶

dropIn عناصری را تعریف می‌کند که snippet می‌تواند داخل آن‌ها drop شود.

export class AirproofSnippetOptionPlugin extends Plugin {
   static id = "airproofSnippetOption";
   resources = {
      dropzone_selector: {
         selector: ".s_airproof_snippet",
         dropIn: ".x_custom_location",
      },
   };
}

dropzone_selector (dropNear)¶

dropNear عناصری را تعریف می‌کند که snippet می‌تواند کنار آن‌ها drop شود.

export class AirproofSnippetOptionPlugin extends Plugin {
   static id = "airproofSnippetOption";
   resources = {
      dropzone_selector: {
         selector: ".s_airproof_snippet_card",
         dropNear: ".card",
      },
   };
}

چیدمان و فیلدها¶

از کامپوننت‌های builder برای ساختن UI پنل گزینه‌ها استفاده کنید.

`<BuilderRow>`¶

یک ردیف برچسب‌دار برای گروه‌بندی فیلدهای گزینه ایجاد کنید. از label.translate برای عنوان ردیف و level برای تورفتگی ردیف‌های تو در تو استفاده کنید.

<BuilderRow label.translate="My option">
   <BuilderSelect>...</BuilderSelect>
   <BuilderButtonGroup>...</BuilderButtonGroup>
</BuilderRow>

مثال عالی برای این مورد، ردیف Animation است:

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

`<BuilderButton>`¶

این تگ داخل <BuilderButtonGroup> یا به‌تنهایی استفاده می‌شود.

<BuilderButtonGroup>
   <BuilderButton classAction="'mt-0'">1</BuilderButton>
   <BuilderButton classAction="'mt-3'">2</BuilderButton>
   <BuilderButton classAction="'mt-5'">3</BuilderButton>
</BuilderButtonGroup>

classAction را اضافه کنید تا مشخص شود کدام کلاس روی عنصر هدف، هنگامی که این انتخاب انجام می‌شود، اعمال شود. مانند هر گرهٔ XML، سایر ویژگی‌ها را برای بهبود سبک و/یا تجربهٔ کاربری اضافه کنید.

<BuilderButton
   icon="'fa-align-right'"
   title.translate="Align right"
   classAction="'ms-auto'" />

`<BuilderSelect>`¶

گزینه را به‌صورت یک فهرست dropdown قالب‌بندی می‌کند.

<BuilderSelect>
   <BuilderSelectItem classAction="''">Default</BuilderSelectItem>
   <BuilderSelectItem classAction="'s_layout_variant'">Variant</BuilderSelectItem>
</BuilderSelect>

`<BuilderButtonGroup>`¶

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

<BuilderButtonGroup>...</BuilderButtonGroup>

`<BuilderCheckbox>`¶

گزینه را به‌صورت یک toggle switch قالب‌بندی می‌کند.

<BuilderCheckbox
   classAction="'s_airproof_snippet_tooltip'" />

`<BuilderRange>`¶

گزینه را به‌صورت یک slider قالب‌بندی می‌کند.

از <BuilderRange> می‌توان برای تنظیم یک مقدار عددی استفاده کرد:

<BuilderRange
   action="'setSpeed'"
   min="0"
   max="10"
   step="1"
   displayRangeValue="true" />

همچنین می‌توان از آن برای نگاشت هر گام به یک ورودی در actionParam استفاده کرد:

<BuilderRange
   action="'setClassRange'"
   actionParam="['o_spc-none', 'o_spc-small', 'o_spc-medium', 'o_spc-big']"
   max="3" />

`<BuilderNumberInput>` و `<BuilderTextInput>`¶

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

unit، saveUnit و step اختیاری هستند¶

<BuilderNumberInput
   styleAction="'animation-duration'"
   unit="'s'"
   saveUnit="'ms'"
   step="0.1" />

<BuilderNumberInput> با propهای اختیاری ارائه می‌شود:

صفت	توضیحات
`unit`	واحد اندازه‌گیری مورد انتظار را نشان می‌دهد.
`saveUnit`	واحد اندازه‌گیری‌ای را تنظیم کنید که مقدار وارد شده توسط کاربر به آن تبدیل و ذخیره می‌شود.
`step`	مقدار عددی‌ای که فیلد می‌تواند با آن افزایش یابد را تنظیم کنید.

`<BuilderList>`¶

یک فهرست از آیتم‌ها (افزودن، حذف، مرتب‌سازی مجدد) را در پنل گزینه‌ها رندر و ویرایش کنید. برای مقادیر از پیش پُرشده، گزینه‌های سفارشی یا تنظیماتی که به فهرستی از اشیاء نگاشت می‌شوند، مفید است.

فهرست ساده با دو فیلد¶

<BuilderList
   action="'setPrefilledOptions'"
   addItemTitle.translate="Add"
   itemShape="{ value: 'number', description: 'text' }"
   default="{ value: '50', description: 'Add a description here' }"
   columnWidth="{ value: 'w-25' }"
   sortable="true" />

Prop	توضیحات
`itemShape`	انواع فیلد به ازای هر ستون. انواع پشتیبانی‌شده: `text`، `number`، `boolean`، `exclusive_boolean`.
`default`	مقادیر پیش‌فرض برای آیتم‌های جدید. کلیدها باید با `itemShape` مطابقت داشته باشند.
`records`	فهرست اختیاری از رکوردهای در دسترس (فهرست JSON). وقتی تنظیم شود، دکمهٔ افزودن به dropdown تبدیل می‌شود.
`defaultNewValue`	مقادیر اضافی که هنگام ایجاد یک آیتم جدید تزریق می‌شوند (مثلاً ID رکورد).
`sortable`	اجازهٔ مرتب‌سازی مجدد drag-and-drop (پیش‌فرض: true).
`hiddenProperties`	ستون‌های خاص را با نام پنهان کنید.
`columnWidth`	کلاس‌های CSS اعمال‌شده به ازای هر ستون (مثلاً `w-25`).
`forbidLastItemRemoval`	از حذف آخرین آیتم باقی‌مانده جلوگیری کنید.

`<BuilderColorPicker>`¶

گزینه را به‌صورت یک رنگ/گرادیان برای انتخاب قالب‌بندی می‌کند.

<BuilderColorPicker
   action="'selectFilterColor'"
   defaultOpacity="50"
   enabledTabs="['custom', 'gradient']" />

صفت	توضیحات
`enabledTabs`	زبانه‌های picker در دسترس را محدود کنید (مثلاً `['theme', 'gradient', 'custom']`).
`defaultColor`	رنگ پیش‌فرض که وقتی هیچ انتخابی اعمال نشده باشد نمایش داده می‌شود.
`defaultOpacity`	مقدار آلفای پیش‌فرض برای picker.

اقدامات¶

کامپوننت‌های builder کلاس‌های BuilderAction را فعال می‌کنند. از propهای میانبر اکشن استفاده کنید یا اکشن‌های سفارشی اعلان کنید و آن‌ها را با id action در قالب ارجاع دهید.

اکشن‌های اصلی¶

اکشن‌های اصلی به‌عنوان propهای میانبر روی کامپوننت‌های builder در دسترس هستند.

Action/prop	توضیحات
`classAction`	افزودن/حذف کلاس‌های CSS روی عنصر هدف.
`styleAction`	تنظیم یک ویژگی style inline روی عنصر هدف.
`attributeAction`	تنظیم یا حذف یک ویژگی DOM.
`dataAttributeAction`	تنظیم یا حذف یک کلید dataset (بدون پیشوند `data-`).
`setClassRange`	اعمال یک کلاس از فهرست از پیش تعریف‌شده بر اساس مقدار range انتخاب‌شده.
`action` + `actionParam`	یک اکشن سفارشی ثبت‌شده در builder plugin را فراخوانی کنید.

چرخهٔ عمر اکشن¶

کلاس‌های BuilderAction می‌توانند چرخهٔ عمری را پیاده‌سازی کنند که builder بسته به widget فراخوانی می‌کند:

متد	توضیحات
`prepare`	داده‌های asynchronous را پیش از استفاده از یک کامپوننت آماده کنید.
`load`	داده‌ها را پیش از `apply` هنگامی که اکشن‌ها پیش‌نمایش می‌شوند بارگذاری کنید.
`apply`	اکشن را روی عنصر هدف اعمال کنید.
`clean`	وقتی یک انتخاب جدید جایگزین آن می‌شود، اکشن را بازنشانی کنید.
`getValue`	مقدار کنونی را برای widgetهای ورودی بازگردانید.
`isApplied`	بازگرداندن اینکه آیا اکشن برای widgetهای قابل انتخاب فعال است یا نه.
`getPriority`	تصمیم بگیرید کدام آیتم قابل انتخاب وقتی چندین مورد معتبر باشد برنده می‌شود.

اکشن‌های سفارشی¶

برای ایجاد رفتارهای سفارشی، یک BuilderAction تعریف کنید و آن را در builder plugin خود ثبت کنید.

/website_airproof/static/src/website_builder/airproof_snippet_option_plugin.js¶

import { BuilderAction } from "@html_builder/core/builder_action";
import { Plugin } from "@html_editor/plugin";
import { registry } from "@web/core/registry";

export class AirproofLayoutAction extends BuilderAction {
   static id = "airproofLayout";
   apply({ editingElement, params: { mainParam } }) {
      editingElement.classList.toggle("s_airproof_snippet_portrait", mainParam === "portrait");
      editingElement.classList.toggle("s_airproof_snippet_square", mainParam === "square");
   }
   isApplied({ editingElement, params: { mainParam } }) {
      return editingElement.classList.contains(`s_airproof_snippet_${mainParam}`);
   }
}

export class AirproofSnippetOptionPlugin extends Plugin {
   static id = "airproofSnippetOption";
   resources = {
      builder_actions: { AirproofLayoutAction },
   };
}

registry.category("website-plugins").add(
   AirproofSnippetOptionPlugin.id,
   AirproofSnippetOptionPlugin
);

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

<t t-name="website_airproof.AirproofSnippetOption">
   <BuilderRow label.translate="Layout">
      <BuilderButtonGroup action="'airproofLayout'">
         <BuilderButton actionParam="'portrait'">Portrait</BuilderButton>
         <BuilderButton actionParam="'square'">Square</BuilderButton>
      </BuilderButtonGroup>
   </BuilderRow>
</t>

همچنین ببینید

API اکشن‌های Builder

قالب‌های Dynamic Content¶

به‌صورت پیش‌فرض، بلوک‌های Dynamic Content مجموعه‌ای از قالب‌های در دسترس در ابزار ساخت وب‌سایت دارند. قالب‌های سفارشی نیز می‌توانند با استفاده از همان قاعدهٔ نام‌گذاری برای ویژگی id قالب، به‌طور خودکار به فهرست اضافه شوند.

فراخوانی قالب¶

snippet پویایِ انتخاب‌شده، placeholder <div class="dynamic_snippet_template"/> را با قالب مناسب بر اساس data-template-key و کلاس CSS سفارشی جایگزین می‌کند:

<section
   data-snippet="s_blog_posts"
   data-name="Blog Posts"
   class="s_blog_post_airproof s_dynamic_snippet_blog_posts s_blog_posts_post_picture_size_default s_dynamic pt64 pb64 s_blog_post_card o_colored_level o_dynamic_snippet_loading"
   data-template-key="website_airproof.dynamic_filter_template_blog_post_airproof"
   data-custom-template-data="{
      blog_posts_post_author_active:true,
      blog_posts_post_teaser_active:true,
      blog_posts_post_date_active:true,
      blog_posts_post_category_active:true,
      blog_posts_post_new_active:true
   }"
   data-number-of-records="16"
   data-filter-by-blog-id="-1"
   data-filter-id="1"
   data-extra-classes="g-3"
   data-column-classes="col-12 col-sm-6 col-lg-4 col-xxl-3">
   <div class="s_dynamic_snippet_container container">
      <div class="row s_nb_column_fixed">
            <section class="s_dynamic_snippet_holder d-none px-4 placeholder-glow o_colored_level">
               <div class="row">
                  <span class="placeholder col-3 rounded" />
                  <span class="placeholder col-2 offset-7 rounded" />
                  <span class="placeholder mt-3 col-6 rounded" />
               </div>
               <div class="row mt-4">
                  <span class="placeholder col-12 rounded" style="height: 250px;" />
               </div>
            </section>
            <section class="s_dynamic_snippet_title oe_unremovable oe_unmovable flex-column flex-md-row mb-lg-0 pb-3 pb-md-0 s_col_no_resize o_colored_level d-flex justify-content-between">
               <div>
                  <h2 class="h3">Our latest content</h2>
                  <p class="lead">Check out what's new in our company!</p>
               </div>
               <div>
                  <a title="See All" href="/blog">
                     See all<span class="fa fa-long-arrow-right ms-2" />
                  </a>
               </div>
            </section>
            <section class="s_dynamic_snippet_content oe_unremovable oe_unmovable o_not_editable col s_col_no_resize o_colored_level">
               <div class="css_non_editable_mode_hidden">
                  <div class="missing_option_warning alert alert-info fade show d-none d-print-none rounded-0">
                        Your Dynamic Snippet will be displayed here... This message is displayed because you did not provide enough options to retrieve its content.<br/>
                  </div>
               </div>
               <div class="dynamic_snippet_template" />
            </section>
      </div>
   </div>
</section>

data-custom-template-data می‌تواند هر دادهٔ سفارشی موردنیاز برای رندر قالب را به‌صورت یک رشتهٔ JSON دریافت کند. این به شما اجازه می‌دهد متغیرهایی را که در قالب برای نمایش/پنهان کردن عناصر استفاده می‌شوند (نویسنده، تاریخ انتشار و ...) تنظیم کنید یا هر اطلاعات خاصی را که برای رندر محتوا لازم است منتقل کنید.

مثال‌ها¶

/website_airproof/views/snippets/s_snippet_name.xml¶

<template id="dynamic_filter_template_blog_post_airproof" name="...">
   <div t-foreach="records"
        t-as="data"
        class="s_blog_posts_post"
        data-extra-classes="g-3"
        data-column-classes="col-12 col-sm-6 col-lg-4 col-xxl-3">
      <t t-set="record" t-value="data['_record']" />
      <!-- Content -->
   </div>
</template>

صفت	توضیحات
id	ID قالب. باید با `dynamic_filter_template_blog_post_` شروع شود
name	نام خوانا برای انسان از قالب
data-extra-classes	کلاس‌های CSS اضافه‌شده روی `.row` والد ستون‌های پست وبلاگ.
data-column-classes	کلاس‌های CSS اضافه‌شده روی ستون والد کارت‌های پست وبلاگ.

/website_airproof/views/snippets/s_snippet_name.xml¶

<template id="dynamic_filter_template_product_product_airproof" name="...">
   <t t-foreach="records"
      t-as="data"
      data-number-of-elements="4"
      data-number-of-elements-small-devices="1"
      data-number-of-records="8">
      <t t-set="record" t-value="data['_record']" />
      <!-- Content -->
   </t>
</template>

صفت	توضیحات
id	ID قالب. باید با `dynamic_filter_template_product_product_` شروع شود
name	نام خوانا برای انسان از قالب
data-number-of-elements	تعداد محصولات در هر slide در desktop
data-number-of-elements-small-devices	تعداد محصولات در هر slide در موبایل
data-number-of-records	تعداد کل محصولات دریافت‌شده

/website_airproof/views/snippets/s_snippet_name.xml¶

<template id="dynamic_filter_template_event_event_airproof" name="...">
   <t t-foreach="records"
      t-as="data"
      data-extra-classes="g-3"
      data-column-classes="col-12 col-sm-6 col-lg-4 col-xxl-3"
      data-number-of-records="16">
      <t t-set="record" t-value="data['_record']._set_tz_context()" />
      <!-- Content -->
   </t>
</template>

صفت	توضیحات
id	ID قالب. باید با `dynamic_filter_template_event_event_` شروع شود
name	نام خوانا برای انسان از قالب
data-extra-classes	کلاس‌های CSS اضافه‌شده روی `.row` والد ستون‌های رویداد.
data-column-classes	کلاس‌های CSS اضافه‌شده روی ستون والد کارت‌های رویداد.
data-number-of-records	تعداد کل رویدادهای دریافت‌شده

محصولات پویا¶

snippet محصولات پویا، مجموعه‌ای از گزینه‌های micro-styling را تحت Cards Design معرفی می‌کند. برای تنظیم یکی از این گزینه‌ها، کلاس CSS مربوط را در section درج کنید. به‌جز چند استثنا که به متغیرهای CSS متکی هستند، افزودن کلاس، گزینه را روی مقدار صحیح تنظیم می‌کند.

گزینه‌های در دسترس برای طراحی کارت‌های محصول

گزینه‌های کارت¶

در اینجا فهرستی ناقص از این گزینه‌های در دسترس آورده می‌شود:

گزینه	توضیحات	کلاس‌ها / مقادیر CSS
Hover Effect	رنگ Background هنگام hover	`o_wsale_products_opt_hover_background`
Hover Effect	Background Zoom هنگام hover	`o_wsale_products_opt_hover_background o_wsale_products_opt_hover_background_zoom`
Gap	فاصلهٔ بین کارت‌های محصول (از ۰ تا ۲۸ پیکسل)	برای مثال: `style="--o-wsale-products-grid-gap: 16px;"`
Roundness	border radius کارت‌های محصول	`o_wsale_products_opt_rounded_0`
		`o_wsale_products_opt_rounded_1`
		`o_wsale_products_opt_rounded_2`
		`o_wsale_products_opt_rounded_3`
		`o_wsale_products_opt_rounded_4`
		`o_wsale_products_opt_rounded_5`
Colors	ترکیبات رنگی تعریف‌شده در زبانهٔ Theme را اعمال می‌کند	`.o_wsale_products_opt_cc o_wsale_products_opt_cc1`
		`o_wsale_products_opt_cc o_wsale_products_opt_cc2`
		`o_wsale_products_opt_cc o_wsale_products_opt_cc3`
		`o_wsale_products_opt_cc o_wsale_products_opt_cc4`
		`o_wsale_products_opt_cc o_wsale_products_opt_cc5`

گزینه	توضیحات	کلاس‌های CSS
Alignement	Regular: تراز چپ	نیازی به کلاس نیست
Alignement	Center: وسط‌چین	`o_wsale_products_opt_text_align_center`
Title Style	عنوان محصول از Link Color استفاده می‌کند	نیازی به کلاس نیست
Title Style	عنوان محصول از Default Color استفاده می‌کند	`o_wsale_products_opt_name_color_regular`
Bold	عنوان محصول از وزن فونت Bold استفاده می‌کند	`o_wsale_products_opt_name_weight_bold`
Font Size	عنوان محصول از اندازهٔ فونت Responsive استفاده می‌کند	نیازی به کلاس نیست
Font Size	عنوان محصول از اندازهٔ فونت Theme Default استفاده می‌کند	`o_wsale_products_opt_name_size_body`
Description	توضیحات محصول را نمایش می‌دهد	`o_wsale_products_opt_has_description`
Ratings	امتیازات محصول را نمایش می‌دهد	`o_wsale_products_opt_has_rating`

گزینه	توضیحات	کلاس‌های CSS
Image Ratio	Default (1/1)	نیازی به کلاس نیست
	Landscape (4/3)	`o_wsale_products_opt_thumb_4_3`
	Horizontal (6/5)	`o_wsale_products_opt_thumb_6_5`
	WideScreen (16/9)	`o_wsale_products_opt_thumb_16_9`
	Portrait (4/5)	`o_wsale_products_opt_thumb_4_5`
	Vertical (2/3)	`o_wsale_products_opt_thumb_2_3`
Auto-crop	تصاویر را به‌طور خودکار برش می‌دهد	`o_wsale_products_opt_thumb_cover`
Hover Effect	None	نیازی به کلاس نیست
	Zoom-In	`o_wsale_products_opt_img_hover_zoom_in`
	Zoom-In Light	`o_wsale_products_opt_img_hover_zoom_in_light`
	Zoom-Out	`o_wsale_products_opt_img_hover_zoom_out`
	Zoom-Out Light	`o_wsale_products_opt_img_hover_zoom_out_light`
	Image Shadow	`o_wsale_products_opt_img_hover_shadow`

گزینه	توضیحات	کلاس‌های CSS
Buttons	: یک دکمهٔ Add to Cart نمایش می‌دهد	`o_wsale_products_opt_has_cta`
	همیشه دکمهٔ اکشن Inline را نمایش می‌دهد	`o_wsale_products_opt_actions_inline`
	دکمه‌های اکشن را On Hover نمایش می‌دهد	`o_wsale_products_opt_actions_onhover o_wsale_products_opt_wishlist_fixed`
Style	Subtle	`o_wsale_products_opt_actions_subtle`
	Promote	`o_wsale_products_opt_actions_promote`
	Theme colors	`o_wsale_products_opt_actions_theme`

presetهای کارت¶

به‌جای تنظیم جداگانه، می‌توان یک Preset نیز انتخاب کرد. این دارای یک کلاس چیدمان (Catalog یا List)، یک کلاس استایلینگ خاص و همهٔ گزینه‌های کلاس (نگاه کنید به بالا) است. این snippet پویا مجبور به نمایش catalog (o_wsale_products_opt_layout_catalog) و یکی از presetهای زیر است:

Preset	کلاس CSS
Thumbnails	`o_wsale_products_opt_design_thumbs`
Chips	`o_wsale_products_opt_design_chips`
کارت‌ها	`o_wsale_products_opt_design_cards`
Grid	`o_wsale_products_opt_design_grid`

بلوک‌های سازنده¶

ساختار فایل¶

چیدمان¶

Wrapper¶

عناصر¶

اندازه‌گذاری¶

رنگ‌ها¶

ویژگی‌ها¶

مناطق غیرقابل ویرایش¶

پس‌زمینه‌ها¶

هایلایت متن¶

چیدمان Grid¶

استفاده¶

آیتم‌ها در یک grid¶

padding آیتم grid¶

سیستم سازگاری¶

snippet سفارشی¶

قالب¶

۱. اعلان¶

۲. ایجاد گروه¶

۱. افزودن snippet¶

snippet محتوای داخلی¶

selectorهای محتوای داخلی¶

گزینه‌ها¶

کامپوننت و قالب¶

منطق گزینه¶

Plugin API¶

BaseOptionComponent API¶

اتصال¶

selector¶

applyTo¶

exclude¶

dropzone_selector (dropIn)¶

dropzone_selector (dropNear)¶

چیدمان و فیلدها¶

<BuilderRow>¶

<BuilderButton>¶

<BuilderSelect>¶

<BuilderButtonGroup>¶

<BuilderCheckbox>¶

<BuilderRange>¶

<BuilderNumberInput> و <BuilderTextInput>¶

<BuilderList>¶

<BuilderColorPicker>¶

اقدامات¶

اکشن‌های اصلی¶

چرخهٔ عمر اکشن¶

اکشن‌های سفارشی¶

قالب‌های Dynamic Content¶

فراخوانی قالب¶

مثال‌ها¶

محصولات پویا¶

گزینه‌های کارت¶

presetهای کارت¶

`<BuilderRow>`¶

`<BuilderButton>`¶

`<BuilderSelect>`¶

`<BuilderButtonGroup>`¶

`<BuilderCheckbox>`¶

`<BuilderRange>`¶

`<BuilderNumberInput>` و `<BuilderTextInput>`¶

`<BuilderList>`¶

`<BuilderColorPicker>`¶