آموزش برنامه نویسی بخش سفارشی سازی وردپرس – سطح متوسط

سلام دوستان خوب سئو 90 به دوره آموزش برنامه نویسی بخش سفارشی سازی وردپرس (wp_customize$) خوش آمدید . این دوره هم شامل آموزش ویدئویی و هم شامل آموزش متنی است . توصیه می کنیم قبل از اقدام به مشاهده ویدئو های آموزشی یکبار به شکل گذرا مطالب نگارش شده در این صفحه را مطالعه نموده و با ذهنیت بهتری در دوره شرکت کنید .

اگر در چند سال اخیر از وردپرس استفاده کرده باشید بدون شک یک بار با بخش سفارشی سازی قالب سروکار داشتید و یا حداقل اسم آن را شنیدید. سفارشی سازی قالب وردپرس به کاربر امکان میدهد در حالی که نمایش زنده از سایت نمایش میدهد تنظیمات قالب و سایت را پیکربندی کند و یا تغییر دهد .  قسمت سفارشی سازی قالب یک رابط استاندارد برای توسعه دهندگان قالب ارائه میدهد تا قالب خود را سفارشی سازی کنند .

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

اضافه کردن تنظیمات به بخش سفارشی سازی

برای اضافه کردن تنظیمات به بخش سفارشی سازی قالب باید 4 بخش و المان اصلی را شناخته و وظایف هر کدام را بدانیم ، نهایتا جز به جز با بخش های مختلف هر المان کار کنیم تا بخوبی دانش لازم برای اضافه کردن تنظیمات مختلف به قالب را داشته باشیم ، چرا که در ادامه خواهید دید وردپرس برای قسمت سفارشی سازی ، انواع مختلفی را در نظر گرفته است . اما این 4 بخش اصلی چه مواردی هستند ؟!

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

گام اول ثبت سفارشی سازی

اولین قدم برای اضافه کردن تنظیمات به بخش سفارشی سازی قالب استفاده از هوک customize_register میباشد که وظیفه آن کنترل قسمت سفارشی سازی قالب است . زمانی که بخواهیم پنل و سکشن و کنترل ها را به این بخش اضافه کنیم باید از تابع ثبت شده در هوک customize_register استفاده کنیم . این هوک به ما دسترسی به متغییر wp_customize$ را میدهد که شی از نوع WP_Customize_Manager  میباشد . این متغییر صفحه سفارشی سازی را کنترل میکند و ما هم همه تنظیمات را به آن متغییر اضافه خواهیم کرد . پس تمام تنظیمات در داخل این متغیر اصلی هستند .

<?php
function seo90_customize_register( $wp_customize ) {
    // همه تنظیمات در اینجا قرار خواهد گرفت
 };
 add_action( 'customize_register', 'seo90_customize_register' );

با افزودن این قسمت ، اولین خروجی را در بخش سفارشی سازی قالب مشاهده خواهید نمود ، این قسمت شامل تمامی تنظیماتی خواهد بود که کم کم به قالب ما اضافه خواهند شد . در تصاویر ارائه شده نیز گام به گام مراحل اضافه شدن پنل ها ، سکشن ها ، کنترل و … را مشاهده می کنید .

وارد قسمت پنل ها می شویم

پنل ها

توجه   :   ” پنل ها به ما کمک می کنند تا چندین سکش را گروه بندی کنیم برای مثال در بخش سفارشی سازی ، ابزارک یک پنل است ، که داخل آن چندین سکشن قرار دارد و هر کدام مربوط به محل قرار گیری ابزارک های خاصی میباشند . البته استفاده از پنل ها اجباری نیست فقط زمانی که نیاز به استفاده از چندین سکشن مختلف داریم بهتر است سکشن های مرتبط به هم را داخل یک پنل قرار دهیم . پس از افزودن پنل برای نمایش آن در قسمت سفارشی سازی باید پنل ما حاوی حداقل یک سکشن و آن سکشن دارای حداقل یک کنترل باشد . پس حتما به این نکته دقت فرمائید . ” برای افزودن پنل کافیست از تابع add_panel متغییر wp_customize$ استفاده کنیم . add_panel( $id, $args )

این تابع دو پارامتر ورودی دارد اولین پارامتر آیدی از نوع رشته و منحصر بفرد برای این پنل میباشد که برای اتصال سکشن ها به پنل مربوطه از این آیدی استفاده میکنیم . و دومین پارامتر یک آرایه از تنظیمات مربوط به پنل میباشد که در زیر تنظیمات موجود برای پنل را معرفی میکنیم . پارامتر های این آرایه شامل

• title – عنوان پنل که در قسمت سفارشی سازی نمایش داده میشود .
• description  – متن توضیحات پنل که در بالای پنل با کلیک روی آیکون help نمایش داده میشود – اختیاری
• priority  – اولویت ترتیب نمایش پنل ها در بخش سفارشی سازی قالب – اختیاری
• capability  – نمایش یا عدم نمایش براساس دسترسی کاربر مقدار پیش فرض (edit_theme_options) – اختیاری
• theme_supports  – نمایش یا عدم نمایش با استفاده ازاینکه قالب از این ویژگی پشتیبانی میکند یا نه (با استفاده از add_theme_support) – اختیاری
• active_callback  – نمایش یا عدم نمایش براساس مقدار بازگشتی یک تابع خاص – برای مثال ( ‘active_callback' => 'is_front_page') – اختیاری

به قطعه کد ارائه شده در این بخش دقت فرمائید

    $wp_customize->add_panel(
        'seo90_panel',
        array(
            'title' => __('تنظیمات seo90'),
            'description' => esc_html__('تنظیمات قالب seo90'),
            'priority' => 50,
            'capability' => 'edit_theme_options',
            'theme_supports' => '',
            'active_callback' => '',
        )
    );

اگر میخواهید اولویت نمایش پنل یا سکشن را تغییر دهید میتوانید از جدول زیر استفاده کنید . برای مثال اگر بخواهید پنل شما بعد از قسمت رنگ ها نمایش داده شود کافیست اولویت پنل را عددی بیشتر از 40 و کمتر از 60 قرار دهید تا پنل شما در بین پنل رنگ ها و تصویر سربرگ قرار گیرد . اگر مقداری برای اولویت قرار ندهید به صورت پیش فرض مقدار 160 در نظر گرفته میشود و در بین پنل هایی با اولویت یکسان ترتیب نمایش براساس اولویت افزوده شدن با استفاده کد نمایش داده خواهند شد یعنی پنلی که زودتر افزوده شده باشد از اولویت بالاتری برخوردار میباشد .

اما در ادامه به سراغ سکشن ها خواهیم رفت

سکشن ها

سکشن ها محل قرار گیری کنترل ها میباشد به هر سکشن میتوان چندین کنترل اضافه کرد . هر سکشن را میتوان با استفاده از آیدی پنل مورد نظر به آن پنل اضافه کرد تا در آن بخش نمایش داده شود . البته قرار دادن پنل والد برای سکشن اختیاری است و ضروری نیست . برای افزودن سکشن کافیست از تابع add_section متغییر wp_customize$ استفاده کنیم .add_section( $id, $args )

این تابع دو پارامتر ورودی دارد اولین پارامتر آیدی از نوع رشته و منحصر بفرد برای این سکشن میباشد که برای اتصال کنترل ها به سکشن مربوطه از این آیدی استفاده میکنیم . و دومین پارامتر ، یک آرایه از تنظیمات مربوط به سکشن میباشد که در زیر پارامتر های قابل قبول برای آن را قرار دادیم .

• title – عنوان سکشن که در بخش سفارشی سازی نمایش داده میشود
• description  – متن توضیحات سکشن که در بالای سکشن با کلیک روی آیکون help نمایش داده میشود – اختیاری
• panel  – آیدی پنلی که میخواهیم این سکشن در آن بخش قرار گیرد – اختیاری
• priority  – اولویت ترتیب نمایش سکشن ها در بخش سفارشی سازی قالب – اختیاری
• capability  – نمایش یا عدم نمایش براساس دسترسی کاربر مقدار پیش فرض (edit_theme_options) – اختیاری
• theme_supports  – نمایش یا عدم نمایش با استفاده ازاینکه قالب از این ویژگی پشتیبانی میکند یا نه (با استفاده از add_theme_support) – اختیاری
• active_callback  – نمایش یا عدم نمایش براساس مقدار بازگشتی یک تابع خاص – برای مثال ( 'active_callback' => 'is_front_page') – اختیاری
• description_hidden  – برای نمایش یا مخفی کردن توضیحات سکشن در پشت آیکون help – اختیاری

با توجه به این توضیحات به کد زیر میرسیم

$wp_customize->add_section( 'sample_custom_controls_section',
   array(
      'title' => __( 'سکشن ساده نمونه' ),
      'description' => esc_html__( 'نمونه ای از کنترل های سفارشی در اینجا قرار میگیرد' ),
      'panel' => 'header_panel', 
      'priority' => 160,
      'capability' => 'edit_theme_options', 
      'theme_supports' => '', 
      'active_callback' => '',
      'description_hidden' => 'false', 
   )
);

اما پس از این بخش ، به یک قسمت بسیار مهم به نام تنظیمات خواهیم رسید که تنظیمات و کنترل ها در ادامه ، دو بخش بسیار مهم برای کنترل و نمایش خروجی ها در قالب خواهند بود .

تنظیمات

تظیمات و کنترل ها با یکدیگر کار میکنند به عبارتی میتوان گفت تنظیمات بخش بک اند و کنترل بخش فرانت میباشد هر کنترل باید به یک تنظیمات متصل شود . برای افزودن تظیمات کافیست از تابع add_setting متغییر wp_customize$ استفاده کنیم .add_setting( $id, $args )

این تابع دو پارامتر ورودی دارد اولین پارامتر آیدی از نوع رشته و منحصر بفرد برای این تنظیمات میباشد که برای اتصال کنترل ها به تنظیمات مربوطه از این آیدی استفاده میکنیم و دومین پارامتر یک آرایه از تنظیمات مربوط به تنظیمات میباشد که در زیر پارامتر های قابل قبول برای آن را قرار دادیم .

• default –  زمانی که مقداری برای کنترل در دیتابیس موجود نباشداین مقدار به عنوان پیش فرضبرگرداننده میشود (پیش فرض Blank)- اختیاری
• transport  – چگونگی به روز رسانی در حالت پیش نمایش سفارشی سازی را تعیین میکند (پیشفرض refresh) – اختیاری
• type – زوش ذحیره سازی را تعیین میکند که میتواند به صورت قالب و یا به صورت آپشن ذخیره شود (پیش فرض  theme_mod )- اختیاری
• capability  – نمایش یا عدم نمایش براساس دسترسی کاربر مقدار پیش فرض (edit_theme_options) – اختیاری
• theme_supports  – نمایش یا عدم نمایش با استفاده ازاینکه قالب از این ویژگی پشتیبانی میکند یا نه (با استفاده از add_theme_support) – اختیاری
• validate_callback – تابعی که برای اعتبار سنجی مقدار کنترل فراخوانده میشود – احتیاری
• sanitize_callback – تابعی که برای پاکسازی و کد گذاری ورودی قبل از ذخیره کردن در دیتابیس استفاده میشود – اختیاری
• sanitize_js_callback – تابعی که قبل از وارد کردن داده به جاوا اسکریپت فرا خوانده میشود – اختیاری
• dirty – آیا تنظیمات  در هنگام راه اندازی ایجاد شوند یا نه (پیش فرض false) – اختیاری

پس با توجه به این توضیحات ، ادامه کد نویسی ما به این شکل خواهد بود

    $wp_customize->add_setting(
        'sample_default_text', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => '',
            'transport' => 'refresh',
            'type' => 'theme_mod',
            'capability' => 'edit_theme_options',
            'theme_supports' => '',
            'validate_callback' => '',
            'sanitize_callback' => '',
            'sanitize_js_callback' => '',
            'dirty' => false,
        )
    );

بیایید کمی بیشتر در مورد type صحبت کنیم . دو نوع تنظیمات وجود دارد . گزینه ها ('type' => 'option') و تغییرات قالب ('type' => 'theme_mod') ، معمولا از گزینه ها ، بیشتر برای تنظیمات سایت استفاده میشود که همیشه بر روی قالب فعال اثر میگذارد و به نوعی بر روی همه قالب ها تاثیر دارد و از تغییرات قالب ، بیشتر برای تنظیمات خاص استفاده میشود که فقط بر روی یک قالب اثر میگذارد . به صورت عمومی بیشتر برای تنظیمات قالب از نوع گزینه ها استفاده میکنیم .

پس حتما به این نکته نیز توجه داشته باشید . اما نهایتا به قسمتی رسیدیم که توسط آنها باید مقادیر را در داخل سایت جهت نمایش هندل کنیم ، یعنی قسمت کنترل ها .

کنترل ها

همان طور که پیش تر گفتیم کنترل ها در واقع ظاهر تنظیمات شما هستند که با کاربر تعامل دارند به صورت پیش فرض در وردپرس چندین کنترل وجود دارد برای مثال ( سلکت ها ، ورودی متن ،دکمه های رادیویی ، چک باکس ها و … )  و برای سایر انواعی که وردپرس پشتیبانی نمی کند باید با استفاده از کلاس WP_Customize_Control یک کنترل جدید ایجاد کنیم که در آموزش های آینده ساخت کنترل کاستوم را آموزش خواهیم داد . برای افزودن یک کنترل کافیست از تابع add_control متغییر wp_customize$ استفاده کنیم .add_control( $id, $args )

این تابع دو پارامتر ورودی دارد اولین پارامتر آیدی تنظیمات مورد نظر از نوع رشته و برای اتصال کنترل به تنظیمات میباشد و دومین پارامتر یک آرایه از تنظیمات مربوط به کنترل است که در زیر پارامتر های قابل قبول برای آن را قرار دادیم

• lable – برچسب عنوان کنترل میباشد که در داخل سکشن نمایش داده میشود – اختیاری
• description  – توضیحات کنترل که زیر برچسب عنوان نمایش داده میشود – اختیاری
• section – ایدی سکشن مورد نظر که میخواهید این کنترل در آن نمایش داده شود – الزامی
• priority  – اولویت ترتیب نمایش کنترل در سکشن والد (به صورت پیش فرض مقدار 10 ) – الزامی
• type – نوع کنترل را مشخص میکند
• برای مثال (Select Control,Input Control,Checkbox Control , ...) – الزامی
• capability  – نمایش یا عدم نمایش کنترل در تنظیمات براساس دسترسی کاربر مقدار پیش فرض (edit_theme_options) – اختیاری

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

• Input Control
• Checkbox Control
• Select Control
• Radio Button Control
• Dropdown Pages Control
• Textarea Control
• Color Control
• Media Control
• Image Control
• Cropped Image Control
• Date Time Control

برای مثال تصویر زیر یک کنترل از نوع ورودی متن یا همان input می باشد که از این طریق می توانیم مقداری را در آن ذخیره نموده و داخل سایت در محل مورد نظر نمایش دهیم .

در ادامه تمامی این کتترل ها را با مثال های عملی خدمت شما عزیزان آموزش دادیم . اول از همه از انواع متنی شروع می کنیم چرا که ساده تر هستند .

نوع کنترل Input

ورودی متن یکی از متداول ترین کنترل های استفاده شده در تنظیمات میباشد که انواع مختلفی دارد مثل متن و تاریخ و عدد و … برای استفاده از این نوع کنترل  باید type را به درستی وارد کنید

• type – نوع میتواند text, email, url, number, hidden, یا date باشد. (مقدار پیش فرض text) – الزامی
• input_attrs – لیستی از وِیژگی های سفارشی برای کنترل ها مثل نام کلاس یا استایل و یا متن جایگزین و … – فقط برای ورودی از نوع (text,textarea) – اختیاری

پس حتما به این دو مورد دقت داشته باشید چرا که انتخاب صحیح کنترلر برای ما بسیار مهم است . نمونه کد این بخش به شکل زیر می تواند باشد

 $wp_customize->add_setting(
        'sample_default_text', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => '',
            'transport' => 'refresh',
            'sanitize_callback' => ''
        )
    );

    $wp_customize->add_control(
        'sample_default_text', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('عنوان کنترل'),
            'description' => esc_html__('نوع این کنترل میتواند متن ،لینک،تاریخ،ایمیل و غیره باشد'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 10,
            'type' => 'text',
            'capability' => 'edit_theme_options',
            'input_attrs' => array( // اختیاری.
                'class' => 'my-custom-class',
                'style' => 'border: 1px solid rebeccapurple',
                'placeholder' => __('نام خود را وارد کنید'),
            ),
        )
    );

برای پاکسازی  ورودی متن میتوانید از توابع از پیش تعریف شده وردپرس استفاده کنید و یا خودتان تابعی تعریف کنید . برای این کار کافیست نام تابع را در پارامتر sanitize_callback وارد کنید برای مثال برای ورودی متن از نوع text میتوان از تابع wp_filter_nohtml_kses استفاده کنید این تابع متن را گرفته و همه تگ های اچ تی ام ال آن را جدا میکند .

برای ورودی از نوع ایمیل میتوانید از تابع sanitize_email استفاده کنید . این تابع همه کاراکتر های که در یک آدرس ایمیل معتبر غیر مجاز هستند را از بین میبرد .

برای ورودی از نوع آدرس URL از تابع پیش تعریف شده esc_url_raw استفاده کنید این تابع همانند تابع  esc_url عمل میکند و در واقع از این تابع استفاده میکند اما برخلاف تلابع  esc_url آدرس را برای نمایش پاکسازی نمی کند بلکه آدرس URL را برای ذخیره سازی در دیتابیس ، ریدایرکت کردن و درخواست های HTTP پاکسازی میکند .

برای ورودی از نوع number میتوانید از تابع absint استفاده کنید . این تابع مقدار ورودی را به عدد مثبت تبدیل میکند . اگر عددی منفی وارد کنید این تابع تبدیل به عدد مثبت خواهد کرد در حقیقت قدرمطلق مقدار ورودی را برمیگرداند و اگر مقدار رشته یا غیر مجاز دیگری وارد کنید مقدار 0 را برمیگرداند . اما اگر بخواهید عدد منفی نیز استفاده کنید میتوانید به صورت زیر از تابع intval کمک بگیرید و یا برای اعداد اعشاری از تابع floatval استفاده کنید .

    function sample_sanitize_number($input){
        return intval($input);
    }

توجه به این نکته ضروری میباشد که باید در sanitize_callback تنظیمات مربوطه sample_sanitize_number را وارد کنید

نوع Checkbox

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

• type -برای استفاده از چک باکس مقدار نوع باید checkbox باشد – الزامی

یک نمونه از کد چک باکس می تواند به این شکل باشد

 $wp_customize->add_setting(
        'sample_default_checkbox', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => 0,
            'transport' => 'refresh',
            'sanitize_callback' => 'seo90_chkbox_sanitization'
        )
    );

    $wp_customize->add_control(
        'sample_default_checkbox', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل چک باکس'),
            'description' => esc_html__('این یک چک باکس است'),
            'section'  => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 10,
            'type' => 'checkbox',
            'capability' => 'edit_theme_options',
        )
    );

اما برای پاکسازی چک باکس کافیست تابعی تعریف کنید که مقدار چک باکس را برررسی کند از آنجا که مقدار چک باکس true یا false میباشد میتوانید با یک شرط ساده آن را بررسی کنید و در صورت true بودن مقدار 1 و در غیر اینصورت مقدار 0 را باز گردانید .

   function seo90_chkbox_sanitization( $input ) {
        if ( true === $input ) {
           return 1;
        } else {
           return 0;
        }
     }

نوع بعدی که آن را بررسی خواهیم کرد نوع انتخاب گر یا همان select می باشد

نوع Select

برای ایجاد لیست کشویی ( باز شونده ) از سلکت استفاده میشود . برای ایجاد آیتم های آن از تگ option استفاده میکنیم اما در اینجا برای افزودن آیتم ها از آرایه choices استفاده میکنیم

• type – برای استفاده از لیست مقدار نوع باید select باشد – الزامی
• choices – یک آرایه که آیتم های لیست را در آن تعیین میکنیم – اختیاری

یک نمونه کد برای بخش سلکت به این شکل است

 $wp_customize->add_control(
        'sample_default_select', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل سلکت'),
            'description' => esc_html__('لطفا یک گزینه از لیست انتخاب کنید'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 3,
            'type' => 'select',
            'capability' => 'edit_theme_options',
            'choices' => array( // آیتم های لیست.
                'wordpress' => __('وردپرس'),
                'nuclear-energy' => __('انرژی هسته ای')
            )
        )
    );

    function sample_sanitize_select($input,$setting){
        $input = sanitize_key($input);
        $choice = $setting->manager->get_control($setting->id)->choices;
        return (array_key_exists($input,$choice)?$input:$setting->default);
    }

برای پاکسازی اطلاعات سلکت تابعی نوشتیم به اسم sample_sanitize_select که این تابع موقع ذخیره سازی به این صورت عمل می نماید که دو ورودی گرفته ، و پارامتر اول مقداری است که توسط کاربر انتخاب شده است ، پارامتر دوم متغییر setting میباشد که شامل همه تنظیمات سفارشی سازی است .

در این تابع ابتدا مقدار ارسال شده از طریق فرم که همان مقدار گزینه انتخاب شده توسط کاربر است را با استفاده از تابع sanitize_key پاکسازی میکنیم این تابع فقط حروف کوچک ، خط تیره و زیرخط ( آندرلاین ) مجاز هستند پس اگر در مقدار گزینه انتخاب شده کاراکتر هایی به غیر از حروف کوچک ، – و _ استفاده کنید این تابع  مقادیر غیر مجاز را حذف میکند .

سپس با استفاده از متغییر setting مقادیر مجاز سلکت را که در آرایه choices قبلا مشخص کردیم دوباره دریافت میکنیم و سپس با استفاده از تابع array_key_exists موجود بودن مقدار انتخاب شده توسط کاربر در داخل این آرایه را بررسی میکنیم اگر این مقدار موجود باشد همان مقدار برگشت داده میشود در غیر اینصورت مقداری که به صورت پیش فرض توسط default در add_setting مشخص کردیم برگشت داده خواهد شد . پس از این بخش به قسمت دکمه های رادیویی میرسیم .

نوع Radio Button

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

• type – برای استفاده از دکمه رادیویی مقدار نوع باید radio  باشد – الزامی
• choices – آرایه ای که ایتم های دکمه های رادیویی را در آن تعیین میکنیم – اختیاری

یک نمونه کد برای دکمه های رادیویی به این شکل است

$wp_customize->add_setting(
        'sample_default_radio', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => 'spider-man',
            'transport' => 'refresh',
            'sanitize_callback' => 'sample_sanitize_radio'
        )
    );

    $wp_customize->add_control(
        'sample_default_radio', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل دکمه رادیویی'),
            'description' => esc_html__('این یک کنترل دکمه رادیویی است'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 4,
            'type' => 'radio',
            'capability' => 'edit_theme_options',
            'choices' => array( // گزینه ها.
                'captain-america' => __('کاپیتان آمریکایی'),
                'iron-man' => __('مرد آهنی'),
                'spider-man' => __('مرد عنکبوتی'),

            )
        )
    );

    function sample_sanitize_radio($input,$setting){
        $input = sanitize_key($input);
        $choice = $setting->manager->get_control($setting->id)->choices;
        return (array_key_exists($input,$choice)?$input:$setting->default);
    }

برای پاکسازی اطلاعات دکمه رادیویی تابعی نوشتیم به اسم sample_sanitize_radio  که این تابع موقع ذخیره سازی به این صورت عمل میکند ، دو ورودی میگیرد ، پارامتر اول مقداری است که توسط کاربر انتخاب شده و پارامتر دوم متغییر setting میباشد که شامل همه تنظیمات سفارشی سازی است .

در این تابع ابتدا مقدار ارسال شده از طریق فرم که همان مقدار دکمه رادیویی انتخاب شده است را با استفاده از تابع sanitize_key پاکسازی میکنیم در این تابع فقط حروف کوچک ، خط تیره و زیرخط( آندرلاین ) مجاز هستند پس اگر در مقدار دکمه های رادیویی کاراکترهایی به غیر از حروف کوچک ، – و _ استفاده کنید این تابع مقادیر غیر مجاز را حذف میکند .

سپس با استفاده از متغییر setting مقادیر مجاز دکمه های رادیویی که در آرایه choices قبلا مشخص کردیم را دوباره دریافت میکنیم و سپس با استفاده از تابع array_key_exists موجود بودن مقدار انتخاب شده توسط کاربر در داخل این آرایه را بررسی میکنیم اگر این مقدار موجود باشد همان مقدار برگشت داده میشود در غیر اینصورت مقداری که به صورت پیش فرض توسط default در add_setting مشخص کردیم برگشت داده میشود . پس از بررسی این موارد به یکی دیگر از انواع جذاب در تنظیمات میرسیم .

Dropdown Pages Control

این نوع ، لیستی را برای ما نشان میدهد که حاوی برگه ها میباشد . البته پس از انتخاب فقط آیدی آن برگه در دیتا بیس ذخیره میشود که میتوانید با استفاده از کد get_permalink(get_theme_mod( 'sample_default_dropdownpages', '' )) لینک آن برگه را دریافت و در جای مناسب استفاده کنید

• type – برای استفاده از لیست صفحات مقدار نوع باید dropdown-pages باشد – الزامی

یک کد نمونه به شکل زیر مشاهده کنید

$wp_customize->add_setting(
        'sample_default_dropdownpages', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => '1548',
            'transport' => 'refresh',
            'sanitize_callback' => ''
        )
    );

    $wp_customize->add_control(
        'sample_default_dropdownpages', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل دراپ داون'),
            'description' => esc_html__('یکی از برگه ها را انتخاب کنید'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 5,
            'type' => 'dropdown-pages',
            'capability' => 'edit_theme_options',
        )
    );

حال به سراغ پاکسازی گزینه انتخاب شده توسط کاربر میرویم . از آنجایی که آیدی صفحه باید مقداری مثبت باشد میتوانیم به راحتی از تابع absint که پیش تر معرفی کردیم استفاده کنیم . اما بیایید پا را کمی فراتر بگذاریم اگر کاربر عدد مثبتی را وارد کند و ما برگه با این شماره نداشته باشیم چه اتفاقی می افتد ؟ یک نکته که در اینجا وجود دارد چون قرار است صفحه مورد نظر را با استفاده از آیدی صفحه دریافت کنیم ، در صورت عدم وجود صفحه میتوانیم خروجی را به کاربر نمایش ندهیم و یا کاربر را به صفحه 404 هدایت کنیم .

نوع Textarea

برای دریافت متن چند خطی از کاربر باید از این نوع استفاده شود این نوع همانند نوع متن ورودی است اما فضای بسیار بیشتری جهت نوشتن و ذخیره داریم

• type – برای استفاده از وردی متن چند خطی مقدار نوع باید textarea باشد – الزامی
• input_attrs – لیستی از وِیژگی های سفارشی برای کنترل ها مثل نام کلاس یا استایل و یا متن جایگزین و … – فقط برای ورودی از نوع (text,textarea) – اختیاری

یک نمونه کد برای این نوع را مشاهده می کنید

    $wp_customize->add_setting(
        'sample_default_textarea', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => '',
            'transport' => 'refresh',
            'sanitize_callback' => ''
        )
    );

    $wp_customize->add_control(
        'sample_default_textarea', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل متن چند خطی'),
            'description' => esc_html__('توضیحات برای کنترل'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 6,
            'type' => 'textarea',
            'capability' => 'edit_theme_options',
            'input_attrs' => array( // گزینه های سفارشی.
                'class' => 'my-custom-class',
                'style' => 'border: 1px solid #999',
                'placeholder' => __('لطفا پیام خود را وارد کنید...'),
            ),
        )
    );

برای پاکسازی textarea اگر فقط میخواهید متن را پاکسازی کنید کافیست از تابع  از پیش تعریف شده wp_filter_nohtml_kses به صورت مستقیم در sanitize_callback استفاده کنید . این تابع همه تگ های html را از داخل متن حذف میکند .

اما به یکی از انواع جذاب میرسیم که البته تصویر آن را در بالا مشاهده کردید . نوع انتخاب کننده رنگ که با یک برنامه نویسی جذاب می توانیم از ان بسیار استفاده کنیم .

نوع Color

این کنترل یک جعبه رنگ را نمایش میدهد که کاربر به راحتی میتواند رنگ مورد نظر را انتخاب کند و کد رنگ انتخاب شده ذخیره میشود

• type – برای استفاده از جعبه رنگ مقدار نوع باید  color  باشد – الزامی

یک نمونه کد برای رنگ را مشاهده می کنید

   $wp_customize->add_setting(
        'sample_default_color', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => '#333', // انتخاب رنگ پیش فرض
            'transport' => 'refresh',
            'sanitize_callback' => ''
        )
    );

    $wp_customize->add_control(
        'sample_default_color', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل رنگ'),
            'description' => esc_html__('رنگ مورد نظر را انتخاب کنید'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 7,
            'type' => 'color',
            'capability' => 'edit_theme_options',
        )
    );

برای پاکسازی کد رنگ انتخاب شده توسط کاربر از تابع موجود در هسته وردپرس به اسم sanitize_hex_color استفاده میکنیم . این تابع به این صورت عمل میکند که چک میکند اولا مقدار وارد شده با # شروع شده باشد و همچنین طول مقدار وارد شده را چک میکند تا به جز # ، 3 یا 6 کارکتر باشد و همچنین مقدار مجاز برای هر کاراکتر اعداد از 0 تا 9 و حروف از a تا f که نمایانگر اعداد در مبنای 16 میباشد وارد شده باشد در صورت ورود اطلاعات غیر مجاز مقدار خالی را بازمیگرداند .

نوع Media

این کنترل ، آیدی فایل انتخاب شده را در دیتابیس ذخیره میکند . البته در صورت قرار دادن مقدار پیش فرض برای این کنترل حتما باید آدرس url فایل مورد نظر را وارد کنید . شما می توانید با استفاده از تابع wp_get_attachment_url  آدرس فابل مورد نظر را براساس آیدی ذخیره شده در دیتابیس را دریافت کنید برای مثال

  wp_get_attachment_url( get_theme_mod( 'sample_default_media' ) )

این کنترل میتواند هر فرمتی از مدیا را پشتیبانی کند برای مثال تصاویر ، اسناد پی دی اف ، فایل صوتی و فایل ویدیویی و یا هر فرمتی که سرور از آن پشتیبانی میکند . برای محدود کردن کاربر به انتخاب نوع خاصی فایل از پارامتر mime_type استفاده میکنیم

• mime_type – مشخص کردن نوع فایل وردی توسط کاربر که میتواند (image, audio, video, application, text) باشد. – الزامی
• button_labels  – آرایه ای از تنظیمات سفارشی برای دکمه مدیا – اختیاری

یک نمونه کد برای مدیا به شکل زیر است

   $wp_customize->add_setting(
        'sample_default_media', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'default' => '',
            'transport' => 'refresh',
            'sanitize_callback' => ''
        )
    );

    $wp_customize->add_control(new WP_Customize_Media_Control(
        $wp_customize,
        'sample_default_media', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل مدیا'),
            'description' => esc_html__('این توضیح برای کنترل مدیا میباشد'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'mime_type' => 'audio',  // نوع فایل ورودی 
            'priority' => 8,
            'button_labels' => array( // گزینه های شخصی سازی
                'select' => __('انتخاب فایل'),
                'change' => __('تغییر فایل'),
                'default' => __('پیش فرض'),
                'remove' => __('حذف'),
                'placeholder' => __('فایلی انتخاب نشده است'),
                'frame_title' => __('انتخاب فایل'),
                'frame_button' => __('انتخاب فایل'),
            )
        )
    ));

شما می توانید صدا و انواع مدیا های پشتیبانی شده را در این بخش توسط تنظیمات ذخیره نموده و در سایت نمایش دهید . یک نوع کاربردی تصاویر می باشند که در ادامه بررسی می کنیم

نوع Image

با این کنترل میتوان یک تصویر را انتخاب کنید . این کنترل آدرس url تصویر مورد نظر را ذخیره میکند و بهتر است در تابع sanitize_callback آن از esc_url_raw برای پاکسازی آدرس url جهت امنیت استفاده کنیم

• button_labels  – آرایه ای از تنظیمات سفارشی برای دکمه مدیا – اختیاری

یک نمونه کد به شکل زیر می باشد

 $wp_customize->add_control(new WP_Customize_Image_Control(
        $wp_customize,
        'sample_default_image', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل ساده عکس'),
            'description' => esc_html__('این یک توضیح برای کنترل تصویر میباشد'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 9,
            'button_labels' => array( // گزینه های شخصی سازی دکمه .
                'select' => __('انتخاب تصویر'),
                'change' => __('تغییر تصویر'),
                'remove' => __('حذف'),
                'default' => __('پیش فرض'),
                'placeholder' => __('تصویری انتخاب نشده است'),
                'frame_title' => __('انتخاب تصویر'),
                'frame_button' => __('انتخاب تصویر'),
            )
        )
    ));

توجه داشته باشید که پارامتر های تنظیم شده برای تصاویر درست باشند تا هنگام ذخیره سازی و نمایش مشکلی نداشته باشیم

نوع Cropped Image

با این کنترل میتوان یک تصویر را انتخاب کرد و سپس در اندازه دلخواه برش داده و ذخیره کرد . این کنترل آیدی تصویر مورد نظر را ذخیره میکند . شما می توانید با استفاده از تابع wp_get_attachment_url آدرس عکس مورد نظر را براساس آیدی ذخیره شده در دیتابیس را دریافت کنید . برای مثال

  wp_get_attachment_url( get_theme_mod( 'sample_default_media' ) )

• flex_width – آیا عرض انعظاف پذیر باشد یا خیر (پیش فرض false) – اختیاری
• flex_height – آیا طول انعظاف پذیر باشد یا خیر (پیش فرض false) – اختیاری
• width  – عرض پیشنهادی برای بریدن عکس (پیش فرض 150 پیکسل) – اختیاری
• height – طول پیشنهادی برای بریدن عکس (پیش فرض 150 پیکسل) – اختیاری
• button_labels  – آرایه ای از تنظیمات سفارشی برای دکمه مدیا – اختیاری

یک نمونه کد به شکل زیر می باشد

 $wp_customize->add_control(new WP_Customize_Cropped_Image_Control(
        $wp_customize,
        'sample_default_cropped_image', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل تصویر با قابلیت بریدن'),
            'description' => esc_html__('تصویر را انتخاب کن و با اندازه دلخواه برش بزن'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'flex_width' => false, // عرض انعطاف پذیر مقدار پیش فرض خیر
            'flex_height' => true, //طول انعطاف پذیر مقدار پیش فرض خیر
            'priority' => 10,
            'width' => 800,
            'height' => 400,
            'button_labels' => array( // گزینه های شخصی سازی.
                'select' => __('انتخاب تصویر'),
                'change' => __('تغییر تصویر'),
                'remove' => __('حذف'),
                'default' => __('پیش فرض'),
                'placeholder' => __('تصویری انتخاب نشده است'),
                'frame_title' => __('انتخاب تصویر'),
                'frame_button' => __('انتخاب تصویر'),
            )
        )
    ));

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

نوع Date Time

تاریخ و زمان نیز یکی دیگر از کنترل های پیش فرض در وردپرس است که می توان در قسمت سفارشی سازی از آن استفاده کرد

• include_time  – نمایش یا عدم نمایش فیلد زمان اگر false باشد فقط فیلد تاریخ نمایش داده میشود (پیش فرض true ) – اختیاری
• allow_past_date – اجازه دادن به کاربر برای انتخاب تاریخ گذشته اگر false باشد کاربر فقط تاریخ آینده را میتواند انتخاب کند (پیش فرض true) – اختیاری
• twelve_hour_format -نمایش زمان در قالب 12 ساعته در صورت انتخاب false زمان به صورت 24 ساعته نمایش داده میشود (پیش فرض true) – اختیاری
• min_year  – کمترین تاریخی که کاربر میتواند انتخاب کند (پیش فرض 1000) – اختیاری
• max_year  – حداکثر تاریخی که کاربر میتواند انتخاب کند (پیش فرض 9999 ) – اختیاری

یک نمونه کد نیز برای بخش تاریخ می تواند به این شکل باشد

$wp_customize->add_setting(
        'sample_date_time', // آیدی تنظیمات که قرار است با این اسم در دیتا بیس ذخیره شود
        array(
            'default' => '2020-08-28 16:30:00', // تاریخ و زمان پیش فرض
            'transport' => 'refresh',
            'sanitize_callback' => ''
        )
    );

    $wp_customize->add_control(new WP_Customize_Date_Time_Control(
        $wp_customize,
        'sample_date_time', // آیدی تنظیماتی که این کنترل به آن اتصال دارد
        array(
            'label' => __('کنترل تاریخ'),
            'description' => esc_html__('این یک کنترل تاریخ میباشد که حداقل و حداکثر تاریخ  تنظیم شده است'),
            'section' => 'seo90_settings_section', // ایدی سکشنی که میخواهیم این کنترل در آن نمایش داده شود
            'priority' => 11,
            'include_time' => true, // نمایش زمان 
            'allow_past_date' => true, // اجازه به کاربر برای انتخاب تاریخ گذشته
            'twelve_hour_format' => true, // نمایش ساعت در قالب 12 ساعته
            'min_year' => '2010', // حداقل سالی که کاربر میتواند انتخاب کند
            'max_year' => '2025' // حداکثر سالی که کاربر میتواند انتخاب کند
        )
    ));

امیدواریم محتوا این دوره آموزشی برای شما دوستان عزیز مفید باشد . این چند جلسه که به شکل مختصر اما مفید برای شما عزیزان ارائه شده است بخش سفارشی سازی و المان های داخل آن را به شکل کامل تشریح نموده است اما باید گفت این قسمت می تواند بسیار پیشرفته تر نیز ایجاد شود که نیازمند برنامه نویسی کلاس و … است . اما برای ساخت تنظیمات بسیار پیشرفته تر برای سایر قسمت های قالب همچون نوشته ها ، برگه ها ، کاربران و … می توانید از فریمورک های پیشرفته تر همچون Cmb2 و یا Titan و … استفاده کنید که البته دوره کامل Cmb2 در سایت موجود است و می توانید تنظیمات بسیار پیشرفته تری برای قالب های خودتان با امکانات و انعطاف بیشتر ایجاد نمائید .

[/vc_column_text][/vc_column][/vc_row]