APIs for JS-templated custom Sections and Panels

Maybe the Customizer API section of the soon to be published Theme Developer Handbook will get you started.

The Theme Developer Handbook has started me on Customizer API development, but it has been daunting trying to understand where to use JS and PHP (if any at all). It seems to me The Customizer JS API will soon become a key component in WordPress and all developers must adapt quickly. I would like to cover some core concepts that have been cleaned up for development purposes. For instance I would like to understand how the Menu panel dynamically adds and removes sections.

I know your not here to do my work for me and I do understand there is documentation in the core files but I seem to get lost when I crack them open. Here is a question I have asked on stack exchange. I hope this helps you better understand exactly what it is I would like to do. Dynamically add sections

It would help if WordPress provided pure substratum code to help developers first conceptualize concepts before moving into the grander core files. Thank you for any guidance you may provide as I am thrilled with JS changes that are taking place.

I don’t think anyone would argue that the WP documentation is completely adequate. It’s an ongoing work in progress done by volunteers. Considering that, it’s not too bad IMO. You too can help make documentation better, the docs team is always looking for more help ??

The division between PHP and JS is up to you. If you don’t mind every settings change generating a complete page reload, then no JS at all is required. The JS is to allow settings changes to be reflected client side without having to reload the entire page. Obviously this makes for a better UX.

I’m fairly sure the Customizer is intended to completely replace the old fashioned static theme settings page. From what I’ve seen (very limited), existing themes have not whole heartedly embraced the concept, giving the Customizer a slight nod and otherwise desperately clinging to the old ways. Understandable but disappointing. Hopefully newly developed themes are doing better.

All I’m able to tell you about the Menus screen is that it is a variation of the backend widgets interface, which we also see on the Dashboard, these too are a type of widgets. There’s a JS framework to manage the various entities. I’m unsure how useful these would be within the customizer.

From my understanding of the Customizer, (which is limited as I’m not a theme developer) the idea is mainly the user changes a setting and that change is immediately reflected on the preview page. Whether that change is accomplished via a reload or JS is up to you. I don’t think the page preview was intended to be interactive like widgets, but that is not say you couldn’t do something like that. You’re not going to get much help from the Customizer API. It’s mainly like a launcher for your scripts. A settings change can launch a particular script, what happens within that script is up to you. This is why you’re not seeing much in supporting documentation, you can do pretty much whatever you want.

Thank you for the input. I have started extending the core files. My goal is to soley use JS. How would I go about this.

1. Create a panel.
2. Create a section.

Think in terms of how you would do this outside of the Customizer on a normal page. Work with the DOM to add nodes based on user interaction. Panels and sections are labels of convenience, they are all just DOM nodes, the difference lies in the associated CSS.

You then need to determine some sort of data schema in which you can store the user’s added nodes in a way that the same structure can then be applied repeatably on each applicable page as they are served in normal operation of the site.

It just occurred to me that I misspoke about the operation of the menu and dashboard screens in calling the elements widgets. Wrong term! I meant meta boxes, apologies for my confusion. The widget objects are also a special type of meta boxes. While all the screens use a common framework, the dashboard is probably closest to what you are trying to do. It’s worth studying the underlying code to see how it’s done and determine if any of it can be used for your purposes.

On the dashboard, users cannot create new meta boxes, but devs can. A user clicking an Add Section button to run code that adds a meta box is really no different than a dev adding a meta box. Either way, it’s done with the same code. What would be the most advantageous code to reuse is the code that allows the user to drag boxes around to place them in new positions.

I realize I haven’t directly answered your questions, that is because I’m not really sure of the exact procedure, I just know it involves manipulating the DOM. Hopefully I’ve given you at least a direction to pursue. Good luck!

A couple hours spent educating myself on JS DOM Interface interactions has helped decipher parts of the modal. I see what your saying about the dashboard Ajax. I haven’t built anything yet as I am trying to shed light on whether starting fresh with clean backbone elements will be more beneficial than manipulating the Customizer. Although, I have found standalone controls I could possibly implement, I need to educate myself further on either postTransport or selective refresh. Any ideas on how to build settings for live previewing? I don’t necessarily need to update the fronted until the modal is saved.

All I can suggest is the Theme Developer’s Handbook I linked in my initial reply here. That link deep linked to the selective refresh section, but farther up the same page near the beginning is where Customizer settings are covered. The start of the Customizer API page for your convenience.

Hello again. I have implemented the add new section control and I am now on to the next one. For the layout control I am working on implementing a selector that activates multiple controllers activate state conditionally depending on the value selected. If you are available I could use the input (:

I’ll do what I can, I’ve little practical experience with either the Customizer or significant DOM manipulation with JS, and even less with jQuery. I’m better at how to get something done in concept than actual coding.

I have a question about the WordPress db. Here is some background: A panel has control on reflowing and scaling its section collection. Sections contain a control that conditionally embed a selection of metaboxes. Those metaboxes will contain input text and media that sync to the preview. The preview contains the panels section collection in real time order. When saving to the db should each section have its own row or should all sections be contained in one row using a larger multidimensional array?
Hundreds of players will be saving to the user table.

So the classic small data in several rows or big data in one row conundrum then? I don’t have empirical evidence to support my opinions in this matter, but from what I understand of data structures it wouldn’t make much difference either way as far as the DB engine is concerned. It’s roughly the same amount of data either way.

What could make a difference is the number of queries required to get the needed data. You should always want to minimize that. Let’s assume that you can get all the needed data with one query with either storage scheme.

Then another consideration would be if there is any specific data within the big array that you might want to use in a query. Querying for data buried within a serialized array is problematic at best. Any such data should be accessible in its own field, which could be a reason to go with multiple rows. If there is no such need, the data is all used at the same time and there is no need to query for any specific values, you just need to get the data in or out, then I would go ahead and save it all in one big array.

Just my opinion. If the other factors I mentioned are not an issue, then there is no compelling reason to not use multiple rows, I just think it makes more sense to keep everything together in that big array.

The workstation calls the db on modal initiation and on the update click callback. As for accessing specific data within the array I do call the wp_get_attachment_image_src action. Maybe you can advise me on a better way to retreiving media sources within an array. At the moment I am leaning towards the “A Row A Section” approach. I may dedicate each section to a unique page so calling an entire array maybe overkill. One factor I am struggling to grasp is the foreach construct. The sections must be called to order as a dynamic user prefernce. I have some thoughts on how to save the section index information maybe you could continue with your extremely helpful guidance.

Create a row with a sole purpose of capturing the saved sections index as an array. I would then call the foreach construct to list the arrays objects. I would then somehow link those objects to their associated db row and present the values.

OR

All the section rows have the same key? Within their value array a position identifier is called to determin the order of the foreach construct objects.

If each row has a different key how would I call the foreach construct to only display the required keys?