# Using JavaScript on your theme customization screen (ok)

### Introduction

![js-theme-customizer](https://www.gavick.com/blog/wp-content/uploads/2015/01/js-theme-customizer-1.png)The JavaScript API is being constantly expanded, including in regards to how one might apply it to a theme customization screen – the last major change introduced in WordPress 4.1 was templates for controls created using the Underscore.js library. In short, some controls are now generated on the basis of a template for the JavaScript language – with this it’s possible to, for example, regenerate the control’s code on the fly, taking into account changes in the value of its options. Before we get to such sophisticated issues, we’ll first need to understand the basics of the API. Let’s look at what each API method is meant to do, along with practical examples of its use on the theme customization screen.

### Basics

All collections and API methods of the theme customization screen are included in the **wp.customize** object. Many developers add a **api** variable at the beginning to shorten the code:

| 1 | `var` `api = wp.customize;` |
| - | --------------------------- |

If we refer to API from a level of a frame that displays the preview of the theme, we should refer to the **parent.wp.customize** object.

We may add the code via the [customize\_preview\_init](https://codex.wordpress.org/Plugin_API/Action_Reference/customize_preview_init) action or [customize\_controls\_enqueue\_scripts](https://codex.wordpress.org/Plugin_API/Action_Reference/customize_controls_enqueue_scripts).

The available controls are contained in the **wp.customize.control** object, whereas the available settings are contained in the **wp.customize** object. Sections may be found in the strong>wp.customize.section, and panels in **wp.customize.panel**. Each of the elements of these objects is an instance of the **Values** class, which includes several useful methods, such as:

* **add(id, value)** – adds the object from the set with a specific identifier and value
* **each(callback, context)** – iterates through all elements of the set performing the desired function
* **has(id)** – checks whether there is an element from the set with a particular ID
* **instance(id)** – returns an element from the set with the specified ID (but it’s enough to simply call the set as a method to get the same effect: **wp.customize.control(id)**)
* **remove(id)** – removes an element with the specified ID from the set

### Modifying elements

Elements of the theme customization screen may be modified in many ways- here’s some of the most useful methods:

* **expand()** – expands panel/section
* **collapse()** – collapses panel/section
* **toggle()** – allows the activee status of the item to be changed
* **activate()** – activates an item
* **deactivate()** – deactivates an item
* **focus()** – scroll to the side panel of the item
* **priority()** – downloads/rearranges the items
* **active()** – returns the activity status of the item
* **panel()** – returns the name of the panel to which the item belongs
* **section()** – returns the name of the section to which the item belongs
* **renderContent()** – generates the new HTML structure element (if the element is generated using themes in JS – for now they are just more complex control of file, color, and other user controls selection)
* **ready()** – displays the rendered element (we should use it after **renderContent**).

Additionally, elements in the **params** firled stores the settings such as label or description:

* **params.label**
* **params.description**

Another notable field element is **container** – it includes a handle to an element that stores the control/panel/section. This allows us to modify the elements that we can’t usually modify by changing the parameters and calling the **renderContent** method.

### Preview actions

Through the **wp.customize.previewer** object we may call actions such as:

* refresh preview – method **refresh()**,
* save settings – method **save()**

### Some simple examples

Opening the “colors” section:

| 1 | `wp.customize.section("colors").expand();` |
| - | ------------------------------------------ |

Changing the order of the elements:

| 1 | `wp.customize.control("blogname").priority(100);` |
| - | ------------------------------------------------- |

Transfer control to another section:

| 1 | `wp.customize.control("blogname").section("colors");` |
| - | ----------------------------------------------------- |

Change the name of the control and refresh its structure based on the template:

| 1234 | `var` `ctrl = wp.customize.control("background_color");ctrl.params.label = "New label";ctrl.renderContent();ctrl.ready();` |
| ---- | -------------------------------------------------------------------------------------------------------------------------- |

### Summary

The current API in JavaScript for the theme customization screen offers some really amazing opportunities that can be used to significantly enrich the theme configuration options.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learnphp.gitbook.io/learnphp/wordpress/using-javascript-on-your-theme-customization-screen-ok.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.