قالب وردپرس Customizer Boilerplate
به روز رسانی: این مقاله در 19 فوریه 2013 ویرایش شده است تا تغییرات ایجاد شده در Theme Customizer Boilerplate را منعکس کند.
امیدواریم دو پست اول مجموعه سفارشی ساز تم را خوانده باشید و از آن لذت برده باشید — مقدمه ای بر سفارشی ساز قالب وردپرس و تعامل با سفارشی ساز تم. اکنون زمان آن رسیده است که به دوره اصلی بروید و مونتاژ صفحه دیگ Theme Customizer را شروع کنید که می توانید از آن در تم های خود استفاده کنید. این پست حاوی چند بلوک طولانی کد است، بنابراین به نظرات درون خطی توجه کنید.
توجه: اگر ترجیح می‌دهید فوراً از دیگ بخار استفاده کنید، می‌توانید آن را از Github دانلود کنید و با وصل کردن به قلاب فیلتر «thsp_cbp_options_array»، فیلدهای آرایه $options را تغییر دهید.< /em>
آنچه در حال ایجاد هستیم
مشخصی ساز تم ساختار دایرکتوری Boilerplate
- customizer.php – این فایل اصلی Theme Customizer boilerplate است که بخش‌ها، تنظیمات و کنترل‌ها را با استفاده از داده‌ها از آرایه گزینه‌ها اضافه می‌کند
- custom-controls.php – کلاس‌های کنترل سفارشی و یک قلاب اقدام که به شما امکان می‌دهد کنترل‌های سفارشی خود را اضافه کنید
- helpers.php – توابع کمکی که برای بازیابی گزینه‌های تم، پیش‌فرض گزینه‌ها و غیره استفاده می‌شود.
- options.php – گزینه‌های نمونه و یک قلاب فیلتر که به شما امکان می‌دهد آرایه گزینه‌ها را ویرایش کنید و از فیلدهای خود استفاده کنید
- customizer-controls.css – CSS اصلی برای تصویر جایگزین کنترل سفارشی رادیویی
کل ایده این است که بتوانید این فایل ها را در یک زیرشاخه در فهرست تم خود کپی کنید، فایل customizer.php را از functions.php خود اضافه کنید و با استفاده از Theme Customizer Boilerplate هر چیزی را که دوست دارید، از جمله و به خصوص آرایه گزینه ها تغییر دهید. قلاب ها (توضیح داده شده در قسمت 4). به‌روزرسانی: قبلاً، فقط options.php را ویرایش می‌کردید، اما استفاده از قلاب‌ها همه چیز را بسیار تمیزتر می‌کند.
حالا از یک مثال واقعی استفاده می‌کنیم – یک کنترل متنی را به بخش سفارشی‌سازی تم جدید اضافه می‌کنیم. آرایه در یک تابع کمکی قرار می گیرد و پس از بازگشت یک فیلتر روی آن اعمال می شود. به این ترتیب می توانید گزینه های بیشتری را از یک طرح زمینه یا افزونه فرزند اضافه کنید. اینجاست:
/**
* تابع کمکی که آرایه ای از گزینه های تم را نگه می دارد.
*
* @return آرایه $options آرایه از گزینه های تم
* @ از thsp_get_theme_customizer_fields() که در customizer/helpers.php تعریف شده است استفاده می کند
*/
تابع thsp_get_theme_customizer_fields() {
/*
* استفاده از تابع کمکی برای دریافت قابلیت پیش فرض مورد نیاز
*/
$required_capability = thsp_settings_page_capability();
$options = آرایه(
// شناسه بخش
'new_customizer_section' => آرایه(
/*
* ما در حال بررسی هستیم که آیا این یک بخش موجود است یا خیر
* یا یک مورد جدید که باید ثبت شود
*/
'existing_section' => نادرست،
/*
* استدلال های مربوط به بخش
* Codex - http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_section
*/
'args' => آرایه(
'title' => __( 'عنوان بخش جدید'، 'my_theme_textdomain')،
'description' => __( 'توضیح بخش جدید'، 'my_theme_textdomain')،
'اولویت' => 10
)
/*
* آرایه "فیلدها" شامل تمام فیلدهایی است که باید باشد
* به این بخش اضافه شد
*/
'fields' => آرایه(
/*
* ==========
* ==========
* فیلد متنی
* ==========
* ==========
*/
// شناسه فیلد
'new_text_field' => آرایه(
/*
* تنظیم آرگومان های مرتبط
* Codex - http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting
*/
'setting_args' => آرایه(
'default' => __( 'مقدار متن پیش‌فرض'، 'my_theme_textdomain')،
'type' => 'گزینه',
'capability' => $required_capability،
'transport' => 'Refresh',
'sanitize_callback' => 'thsp_sanitize_cb',
)
/*
* استدلال های مرتبط را کنترل کنید
* Codex - http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control
*/
'control_args' => آرایه(
'label' => __( 'برچسب کنترل متن جدید'، 'my_theme_textdomain')،
'type' => 'text'، // کنترل فیلد متن
'اولویت' => 1
)
)
)
)
)
/*
* قلاب فیلتر 'thsp_customizer_options' به شما این امکان را می دهد
* افزودن/حذف برخی از این گزینه ها از یک تم کودک
*/
return application_filters( 'thsp_customizer_options', $options );
}به‌روزرسانی: آرایه ثابت می‌ماند، اما اکنون می‌توانید آرایه گزینه‌ها را به یک قلاب فیلتر نیز منتقل کنید، برای جزئیات بیشتر قسمت 4 را ببینید.
در نگاه اول پیچیده به نظر می رسد، می دانم، اما اجازه دهید توضیح دهم.
آرایه $options از بخش(ها) تشکیل شده است (در این مورد فقط یکی – new_customizer_section)، هر بخش دارای آرگومان ها، فیلدها و یک مقدار بولی (existing_section) است که نشان می دهد آیا جدید است یا خیر. بخش، یا فقط چند فیلد را به یکی از فیلدهای موجود اضافه می کنیم. آرایه آرگومان‌ها مشابه چیزی است که به $wp_customize->add_section. آرایه فیلدها کمی پیچیده تر است.
به روز رسانی: آرایه انتخاب در آرگومان های کنترل اکنون یک آرایه چند بعدی است.
هر فیلد از یک تنظیم Customizer و یک کنترل Customizer تشکیل شده است. به همین دلیل است که ما آرایه‌های setting_args و control_args داریم. تقریباً دقیقاً مشابه آرایه‌های آرگومان‌هایی هستند که می‌خواهید به $wp_customize->add_setting و $wp_customize->add_control. تنها تفاوت آرایه انتخاب ها در آرگومان های کنترل است، $wp_customize->add_control مستلزم آن است که یک آرایه جفت کلید ساده => ارزش باشد و به جای آن از یک آرایه چند بعدی استفاده می کنیم.
به این ترتیب می‌توانید داده‌های بیشتری را به هر یک از گزینه‌ها منتقل کنید، بنابراین اگر مثلاً فونت‌های Google را در قالب خود بارگیری می‌کنید، می‌توانید رشته‌هایی داشته باشید که به شما امکان می‌دهند فونت صحیح را بارگیری کنید. آرایه انتخاب های داخلی می‌توانید نمونه‌ای از این تم را ببینید که از Customizer Boilerplate استفاده می‌کند. .
بنابراین، اگر از قبل از این سه روش آگاه هستید، همه آنها بسیار آشنا هستند.
افزودن یک کنترل چک باکس تقریباً یکسان است، فقط باید «نوع» را در آرایه «control_args» به «چک باکس» تغییر دهید:
/*
* ==============
* فیلد چک باکس
* ==============
*/
'new_checkbox_field' => آرایه(
'setting_args' => آرایه(
'پیش فرض' => درست،
'type' => 'گزینه',
'capability' => $required_capability،
'transport' => 'Refresh',
'sanitize_callback' => 'thsp_sanitize_cb',
)
'control_args' => آرایه(
'label' => __( 'برچسب کنترل رادیویی جدید'، 'my_theme_textdomain')،
'type' => 'checkbox', // کنترل فیلد چک باکس
'اولویت' => 2
)
)
کنترل‌های رادیو و انتخاب تقریباً یکسان هستند، فقط باید انتخاب‌های داده شده را مشخص کنید:
/*
* ============
* ============
* میدان رادیویی
* ============
* ============
*/
'new_radio_field' => آرایه(
'setting_args' => آرایه(
'default' => 'گزینه-2',
'type' => 'گزینه',
'capability' => $thsp_cbp_capability،
'transport' => 'Refresh',
)
'control_args' => آرایه(
'label' => __( 'برچسب کنترل رادیویی جدید'، 'my_theme_textdomain')،
'type' => 'رادیو'، // کنترل رادیویی
'انتخابها' => آرایه(
'option-1' => آرایه(
'label' => __( 'گزینه 1'، 'my_theme_textdomain')
)
'option-2' => آرایه(
'label' => __( 'گزینه 2'، 'my_theme_textdomain')
)
'option-3' => آرایه(
'label' => __( 'گزینه 3'، 'my_theme_textdomain')
)
)
'اولویت' => 3
)
)
/*
* =============
* =============
* فیلد را انتخاب کنید
* =============
* =============
*/
'new_select_field' => آرایه(
'setting_args' => آرایه(
'default' => 'گزینه-3',
'type' => 'گزینه',
'capability' => $thsp_cbp_capability،
'transport' => 'Refresh',
)
'control_args' => آرایه(
'label' => __( 'برچسب فیلد انتخابی جدید'، 'my_theme_textdomain')،
'type' => 'انتخاب'، // کنترل را انتخاب کنید
'انتخابها' => آرایه(
'option-1' => آرایه(
'label' => __( 'گزینه 1'، 'my_theme_textdomain')
)
'option-2' => آرایه(
'label' => __( 'گزینه 2'، 'my_theme_textdomain')
)
'option-3' => آرایه(
'label' => __( 'گزینه 3'، 'my_theme_textdomain')
)
)
'اولویت' => 4
)
)و در نهایت، دو نوع کنترل پیچیده که در وردپرس تعبیه شده است – آپلود فایل و آپلود تصویر:
/*
* ============
* ============
* آپلود فایل
* ============
* ============
*/
'new_file_upload_field' => آرایه(
'setting_args' => آرایه(
'پیش فرض' => ''،
'type' => 'گزینه',
'capability' => $thsp_cbp_capability،
'transport' => 'Refresh',
)
'control_args' => آرایه(
'label' => __( 'بارگذاری فایل'، 'my_theme_textdomain')،
'type' => 'upload', // کنترل فیلد آپلود فایل
'اولویت' => 5
)
)
/*
* =============
* =============
* آپلود تصویر
* =============
* =============
*/
'new_image_upload_field' => آرایه(
'setting_args' => آرایه(
'پیش فرض' => ''،
'type' => 'گزینه',
'capability' => $thsp_cbp_capability،
'transport' => 'Refresh',
)
'control_args' => آرایه(
'label' => __( 'آپلود تصویر'، 'my_theme_textdomain')،
'type' => 'image'، // کنترل فیلد آپلود تصویر
'اولویت' => 6
)
)توجه داشته باشید که من از ‘type’ => ‘option’ در تنظیم آرگومان‌ها برای همه این فیلدها استفاده کردم. این اجازه می دهد تا تمام مقادیر به عنوان یک مقدار در پایگاه داده شما ذخیره شوند. گزینه جایگزین ‘type’ => ‘theme_mod’ است، اما در حال حاضر اجازه دهید به “option” بمانیم.
استفاده از Options Array برای افزودن بخش‌ها، تنظیمات و کنترل‌های Customizer
اگر مطمئن نیستید نحوه تعامل با WordPress Theme Customizer، بروید و بررسی کنید، زیرا این کاری است که ما اکنون انجام خواهیم داد. تنها تفاوت این است که به جای اضافه کردن بخش‌ها، تنظیمات و کنترل‌ها در یک زمان، فرآیند را با استفاده از آرایه سریالی که ایجاد کرده‌ایم خودکار می‌کنیم. بیایید به آن بپردازیم:
function thsp_cbp_customize_register( $wp_customize ) {
/**
* کنترل های سفارشی
*/
require( dirname(__FILE__). '/custom-controls.php' );
/*
* تمام فیلدها را با استفاده از یک تابع کمکی دریافت کنید
*/
$thsp_sections = thsp_cbp_get_fields();
/*
* دریافت نام ورودی DB که در آن گزینه ها ذخیره می شوند
*/
$thsp_cbp_option = thsp_cbp_option();
/**
* از طریق آرایه حلقه بزنید و بخش های Customizer را اضافه کنید
*/
foreach( $thsp_sections به عنوان $thsp_section_key => $thsp_section_value ) {
/**
* در صورت نیاز بخش Customizer را اضافه می کند
*/
if( ! $thsp_section_value['existing_section'] ) {
$thsp_section_args = $thsp_section_value['args'];
// افزودن بخش
$wp_customize->add_section(
$thsp_section_key،
$thsp_section_args
)
} // پایان اگر
/*
* از طریق آرایه "فیلدها" در هر بخش حلقه بزنید
* و تنظیمات و کنترل ها را اضافه کنید
*/
$thsp_section_fields = $thsp_section_value['fields'];
foreach( $thsp_section_fields به عنوان $thsp_field_key => $thsp_field_value ) {
/*
* بررسی کنید که آیا «option» یا «theme_mod» برای ذخیره گزینه استفاده شده است
*
* اگر چیزی تنظیم نشده باشد، روش $wp_customize->add_setting به طور پیش فرض روی "theme_mod" خواهد بود.
* اگر «گزینه» به عنوان نوع تنظیم استفاده شود، مقدار آن در ورودی ذخیره می‌شود
* جدول {prefix}_options. نام گزینه توسط تابع thsp_cbp_option() تعریف می شود
*/
if ( isset( $thsp_field_value['setting_args']['type'] ) && 'option' == $thsp_field_value['setting_args']['type'] ) {
$setting_control_id = $thsp_cbp_option . '['. $thsp_field_key . ']';
}دیگر {
$setting_control_id = $thsp_field_key;
}
/*
* اگر هیچ یک تعریف نشده است، عملکرد پیش فرض پاسخ به تماس را اضافه کنید
*/
if (! isset( $thsp_field_value['setting_args']['sanitize_cb'] ) ) {
$thsp_field_value['setting_args']['sanitize_cb'] = 'thsp_cbp_sanitize_cb';
}
/**
* تنظیمات Customizer را اضافه می کند
*/
$wp_customize->add_setting(
$setting_control_id،
$thsp_field_value['setting_args']
)
/**
* کنترل Customizer را اضافه می کند
*
* مقدار «بخش» باید به آرایه «control_args» اضافه شود
* بنابراین کنترل می تواند به بخش فعلی اضافه شود
*/
$thsp_field_value['control_args']['section'] = $thsp_section_key;
/*
* روش $wp_customize->add_control نیاز دارد که 'choices' یک کلید ساده باشد => جفت مقدار
*/
if ( isset( $thsp_field_value['control_args']['choices'] ) ) {
$thsp_cbp_choices = array();
foreach( $thsp_field_value['control_args']['choices'] به عنوان $thsp_cbp_choice_key => $thsp_cbp_choice_value ) {
$thsp_cbp_choices[$thsp_cbp_choice_key] = $thsp_cbp_choice_value['label'];
}
$thsp_field_value['control_args']['choices'] = $thsp_cbp_choices;
}
// نوع کنترل را بررسی کنید
if ( 'color' == $thsp_field_value['control_args']['type'] ) {
$wp_customize->add_control(
WP_Customize_Color_Control جدید(
$wp_customize،
$setting_control_id،
$thsp_field_value['control_args']
)
)
} elseif ( 'image' == $thsp_field_value['control_args']['type'] ) {
$wp_customize->add_control(
WP_Customize_Image_Control جدید(
$wp_customize،
$setting_control_id،
$thsp_field_value['control_args']
)
)
} elseif ( 'upload' == $thsp_field_value['control_args']['type'] ) {
$wp_customize->add_control(
WP_Customize_Upload_Control جدید(
$wp_customize،
$setting_control_id،
$thsp_field_value['control_args']
)
)
}دیگر {
$wp_customize->add_control(
$setting_control_id،
$thsp_field_value['control_args']
)
}
} // پایان foreach
} // پایان foreach
}
add_action('customize_register', 'thsp_cbp_customize_register');مرور همه بخش‌ها، اضافه کردن مواردی که از قبل وجود ندارند، سپس تمام قسمت‌ها را در هر بخش مرور کنید، یک تنظیم و یک کنترل برای هر کدام اضافه کنید. این تمام چیزی است که در اینجا می گذرد.
یادتان می‌آید که ما از “type” => “option” برای همه تنظیمات استفاده کردیم؟ به همین دلیل است که ما اکنون “my_theme_options[$thsp_field_key]” را برای تنظیمات و بخش‌ها داریم. این همه مقادیر را به عنوان یک آرایه سریالی ذخیره می کند که می توانید با استفاده از get_option( ‘my_theme_options’ ) بازیابی کنید. یا فقط می توانید از توابع کمکی تعریف شده در helpers.php استفاده کنید تا هم مقادیر فعلی و هم مقادیر پیش فرض را برای همه فیلدها بازیابی کنید:
/**
* مقادیر گزینه را دریافت کنید
*
* آرایه ای که تمام مقادیر گزینه ها را نگه می دارد
* مقدار پیش فرض گزینه در صورتی استفاده می شود که کاربر مقداری را مشخص نکرده باشد
*
* @ از thsp_get_theme_customizer_defaults() تعریف شده در /customizer/options.php استفاده می کند
* آرایه بازگشت @ مقادیر فعلی برای همه گزینه ها
* @since Theme_Customizer_Boilerplate 1.0
*/
تابع thsp_cbp_get_options_values() {
// گزینه پیش فرض را دریافت کنید
$option_defaults = thsp_cbp_get_options_defaults();
// گزینه های ذخیره شده را با پیش فرض ها تجزیه کنید
$thsp_cbp_options = wp_parse_args( get_option( thsp_cbp_option()، array() ), $option_defaults );
// آرایه تجزیه شده را برگردانید
$thsp_cbp_options را برگردانید.
}
/**
* پیش فرض های گزینه را دریافت کنید
*
* آرایه ای را برمی گرداند که مقادیر پیش فرض را برای همه گزینه ها نگه می دارد
*
* @ از thsp_get_theme_customizer_fields() تعریف شده در /customizer/options.php استفاده می کند
* @return آرایه $thsp_option_defaults مقادیر پیش‌فرض برای همه گزینه‌ها
* @since Theme_Customizer_Boilerplate 1.0
*/
تابع thsp_cbp_get_options_defaults() {
// آرایه ای را دریافت کنید که تمام فیلدهای گزینه تم را در خود جای می دهد
$thsp_sections = thsp_cbp_get_fields();
// آرایه را راه اندازی کنید تا مقادیر پیش فرض را برای همه گزینه های تم نگه دارد
$thsp_option_defaults = array();
// از طریق آرایه پارامترهای گزینه حلقه بزنید
foreach ( $thsp_sections به عنوان $thsp_section ) {
$thsp_section_fields = $thsp_section['fields'];
foreach ( $thsp_section_fields به عنوان $thsp_field_key => $thsp_field_value ) {
// برای هر گزینه در آرایه پارامترها یک کلید آرایه انجمنی به آرایه پیش فرض اضافه کنید
if( isset( $thsp_field_value['setting_args']['default'] ) ) {
$thsp_option_defaults[$thsp_field_key] = $thsp_field_value['setting_args']['default'];
}دیگر {
$thsp_option_defaults[$thsp_field_key] = نادرست;
}
}
}
// آرایه پیش فرض را برگردانید
$thsp_option_defaults را برگرداند.
}فقط یک چیز دیگر وجود دارد که باید به آن اشاره کنم – عملکرد بازخوانی پاکسازی که در آرایه “setting_args” مشخص کردیم. تابع در extend.php تعریف شده است و به سادگی داده ها را از طریق اجرا می کند. تابع wp_kses_post:
/**
* تابع پاکسازی تم سفارشی ساز پاسخ به تماس
*/
تابع thsp_sanitize_cb( $input ) {
بازگشت wp_kses_post( $input );
}از اینجا به کجا؟
در حال حاضر، می توانید از این Theme Customizer Boilerplate در تم های خود استفاده کنید، تنها کاری که باید انجام دهید این است که آن را از Github دانلود کنید، در فهرست قالب خود کپی کنید و فایل اصلی را از functions.php قرار دهید، که 100% کاربردی و خوب است. برای اکثر مضامین کافی است.
از آنجایی که طرح زمینه شما “مانند اکثر طرح‌های زمینه” نیست، هفته آینده نحوه گسترش دیگ بخار را با استفاده از فیلتر و قلاب‌های اکشن آن خواهیم دید.
خیلی دوست دارم بشنوم که چگونه فکر می کنید این دیگ بخار می تواند بهبود یابند یا گسترش یابد، پس لطفاً در نظرات از آن استفاده کنید.
