Skip to content

Commit

Permalink
fixes #11
Browse files Browse the repository at this point in the history
  • Loading branch information
moldcraft committed Mar 4, 2016
1 parent 34602c1 commit a13c718
Show file tree
Hide file tree
Showing 4 changed files with 301 additions and 167 deletions.
168 changes: 168 additions & 0 deletions options/customizer.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
Customizer
==========

Starting with `v2.3.0 <https://github.com/ThemeFuse/Unyson-Extensions-Approval/issues/66>`__ options can be used in Customizer.

**Customizer Options** ``{theme}/framework-customizations/theme/options/customizer.php``
are turned into `Customizer <https://codex.wordpress.org/Theme_Customization_API>`__ elements (panels, sections and controls).

The customizer elements have a strict structure which also applies to options array structure:

* Containers can be nested only 2 levels

* ``container > option`` is turned into ``section > control``
* ``container > container > option`` is turned into ``panel > section > control``
* ``container > container > container > option`` will not work ``panel > section > ERROR``

* Containers must contain only options or only containers, because a panel can't contain both sections and controls.

Examples
--------

Try the below arrays in ``{theme}/framework-customizations/theme/options/customizer.php``.

* Create a Section

.. code-block:: php
$options = array(
'section_1' => array(
'title' => __('Unyson Section', '{domain}'),
'options' => array(
'option_1' => array(
'type' => 'text',
'value' => 'Default Value',
'label' => __('Unyson Option', '{domain}'),
'desc' => __('Option Description', '{domain}'),
),
),
),
);
* Create a Panel with Sections

.. code-block:: php
$options = array(
'panel_1' => array(
'title' => __('Unyson Panel', '{domain}'),
'options' => array(
'section_1' => array(
'title' => __('Unyson Section #1', '{domain}'),
'options' => array(
'option_1' => array(
'type' => 'text',
'value' => 'Default Value',
'label' => __('Unyson Option #1', '{domain}'),
'desc' => __('Option Description', '{domain}'),
),
),
),
'section_2' => array(
'title' => __('Unyson Section #2', '{domain}'),
'options' => array(
'option_2' => array(
'type' => 'text',
'value' => 'Default Value',
'label' => __('Unyson Option #2', '{domain}'),
'desc' => __('Option Description', '{domain}'),
),
'option_3' => array(
'type' => 'text',
'value' => 'Default Value',
'label' => __('Unyson Option #3', '{domain}'),
'desc' => __('Option Description', '{domain}'),
),
),
),
),
),
);
* Get option database/saved value in template

.. code-block:: php
$value = fw_get_db_customizer_option('option_1');
.. _customizer-options-live-preview:

Live Preview
------------

In background, customizer options are converted into `customizer elements <https://codex.wordpress.org/Theme_Customization_API#Part_1:_Defining_Settings.2C_Controls.2C_Etc.>`__,
so they follow default WordPress behavior and implementing a live preview can be done using `the default WordPress solution <https://codex.wordpress.org/Theme_Customization_API#Part_3:_Configure_Live_Preview_.28Optional.29>`__.

1. Change the setting transport and enqueue the javascript

.. code-block:: php
// file: {theme}/inc/hooks.php
if (defined('FW')):
/**
* @param WP_Customize_Manager $wp_customize
* @internal
*/
function _action_customizer_live_fw_options($wp_customize) {
if ($wp_customize->get_setting('fw_options[OPTION_ID]')) {
$wp_customize->get_setting('fw_options[OPTION_ID]')->transport = 'postMessage';
add_action( 'customize_preview_init', '_action_customizer_live_fw_options_preview' );
}
}
add_action('customize_register', '_action_customizer_live_fw_options');
/**
* @internal
*/
function _action_customizer_live_fw_options_preview() {
wp_enqueue_script(
'mytheme-customizer',
get_template_directory_uri() .'/assets/js/theme-customizer.js',
array( 'jquery','customize-preview' ),
fw()->theme->manifest->get_version(),
true
);
}
endif;
2. Handle the change in javascript

.. code-block:: javascript
// file: {theme}/assets/js/theme-customizer.js
( function( $ ) {
wp.customize( 'fw_options[OPTION_ID]', function( value ) {
value.bind( function( newval ) {
/**
* An array of collected html inputs
* [{'name':'input[name]','value':'input value'}]
* or
* [{'name':'input[name]','value':'input value'},{'name':'input[name]','value':'input value'},...]
*/
newval = JSON.parse(newval);
$( 'h1' ).text( newval[0].value );
} );
} );
} )( jQuery );
.. note::

The value comes in ``[{'name':'input[name]','value':'input value'}]`` format,
because the customizer form is not submitted as a regular form.
A control can store its value only inside a single input which has some special attributes (instead of ``name="..."``)
and it is monitored for changes by the Customizer script to trigger the preview update.
Because of that, the framework options collect all their inputs values and store them in that special input
(`here <http://bit.ly/1Fau8gg>`__ is an advanced explanation).
2 changes: 2 additions & 0 deletions options/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ Options
:hidden:

introduction
integrate
customizer
option-types
built-in-option-types
create-option-type
131 changes: 131 additions & 0 deletions options/integrate.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
Theme Integration
=================

With options you can easy create admin forms and use the values in frontend. Let's to this!

Customizer Options
------------------

1. Create ``{theme}/framework-customizations/theme/options/customizer.php`` with the following contents:

.. code-block:: php
<?php if (!defined( 'FW' )) die('Forbidden');
$options = array(
'body-color' => array(
'type' => 'color-picker',
'label' => __('Body Color', '{domain}'),
'value' => '#ADFF2F',
),
);
2. Add in ``{theme}/functions.php``

.. code-block:: php
function _action_theme_wp_print_styles() {
if (!defined('FW')) return; // prevent fatal error when the framework is not active
$option_value = fw_get_db_customizer_option('body-color');
echo '<style type="text/css">'
. 'body { '
. 'border: 30px solid '. esc_html($option_value) .'; '
. '}'
. '</style>';
}
add_action('wp_print_styles', '_action_theme_wp_print_styles');
3. Go to menu **Appearance > Customize**, find the **Body Color** option and change it.
.. hint::
You can enable :ref:`Live Preview <customizer-options-live-preview>` for customizer options.
Settings Options
----------------
1. Create ``{theme}/framework-customizations/theme/options/settings.php`` with the following contents:
.. code-block:: php
<?php if (!defined( 'FW' )) die('Forbidden');
$options = array(
'body-color' => array(
'type' => 'color-picker',
'label' => __('Body Color', '{domain}'),
'value' => '#ADFF2F',
),
);
2. Add in ``{theme}/functions.php``
.. code-block:: php
function _action_theme_wp_print_styles() {
if (!defined('FW')) return; // prevent fatal error when the framework is not active
$option_value = fw_get_db_settings_option('body-color');
echo '<style type="text/css">'
. 'body { '
. 'border: 30px solid '. esc_html($option_value) .'; '
. '}'
. '</style>';
}
add_action('wp_print_styles', '_action_theme_wp_print_styles');
3. Go to menu **Appearance > Theme Settings**, find the **Body Color** option, change it and press Save.
4. Go to frontend and see the changes.
Post Options
------------
1. Create ``{theme}/framework-customizations/theme/options/posts/post.php`` with the following contents:
.. code-block:: php
<?php if (!defined( 'FW' )) die('Forbidden');
$options = array(
'main' => array(
'type' => 'box',
'title' => __('Testing Options', '{domain}'),
'options' => array(
'body-color' => array(
'type' => 'color-picker',
'label' => __('Body Color', '{domain}'),
'value' => '#ADFF2F',
),
),
),
);
2. Add in ``{theme}/functions.php``
.. code-block:: php
function _action_theme_wp_print_styles() {
if (!defined('FW')) return; // prevent fatal error when the framework is not active
global $post;
if (!$post || $post->post_type != 'post') {
return;
}
$option_value = fw_get_db_post_option($post->ID, 'body-color');
echo '<style type="text/css">'
. 'body { '
. 'border: 30px solid '. esc_html($option_value) .'; '
. '}'
. '</style>';
}
add_action('wp_print_styles', '_action_theme_wp_print_styles');
3. Create a new Post, find **Body Color** option, change it and save the post.
4. Open the post in frontend and see the changes.

0 comments on commit a13c718

Please sign in to comment.