Relocating Core Markup

This post outlines a proposed task within the BuddyPress project that will attempt to identify and relocate all core html markup that currently lives in core files to theme file locations.

There exist a number of functions in core that are almost exclusively markup related (bp_directory_*_search_form() reference throughout this article as one, that live in the component bp-*-template.php files.) there also exists a degree of code replication due to the nature of component files that would seem to be unecessary.

Why is this something we should be concerned about? There are a number of reasons why this approach is perhaps not to be considered optimal and broadly speaking the following…

  • (very loosely) the belief that a separation between backend code and frontend code is to be the preferred goal always – mixed scripting and markup can lead to hard to maintain code blocks.
  • In a plugin paradigm where developers know they can’t modify core files locking markup into those core files just leads to increased work to be able to modify and manage that markup.

Now in BuddyPress terms it does need to be pointed out that whereas we do have markup in core files it is and has been written in as clean and thoughtful a manner as possible, and provision is made to be able to filter, for example, the search form markup in its entirety so developers can write their own markup, return via add_filter to effectively replace the entire form.

So what is the problem then? The problem or problems might be thought of as:

  • Replication of markup – core writes a search form 4 times once for each component, bulk action markup for messaging occurs repeatedly.
  • In respect of our search forms they are, in reality, one form that only changes classes and query args so we should be writing one form with logic to add the correct class/query arg for component.
  • A developer needing to adjust a form for any reason, lets say to add a new token, would need to stop find a convenient file to write a new function in and filter that back to the core function, possibly having to do that for four instances; either way a two sec job to add a new class becomes substantially more involved.
  • It is not so much the Cores responsibility to write markup this is the province of template files, at most, Core is required to provide template tags or functions to return out ? query arg as appropriate.
  • While Core retains control over this markup it makes things harder in respect of building clean new fresh templates – if those templates are having to reference functions that are perhaps not optimal, that might carry inherent issue through – moving the responsibility for that markup/functionality to template files allows us completely re-write the markup with absolute freedom.

The current task exploratory progress:

I started a wider discussion a while back on tasks pertaining to the ultimate goal of creating a new set of templates files to replace bp-legacy (often we refer to new template packs, I prefer though not to use this phrase in reference to what I see as the base level theme_compat template.)
This somewhat lengthy and admittedly ? rambling ticket can be read here:

To achieve the wider goal I realised that really the issue of tackling core markup was required in advance of any other tasks, and actually could stand as a useful task in its own right even if further template updating wasn’t tackled.

In I started this process of with a patch and approach to dealing with Search forms as an example to work with.

In the initial patch I removed the search form markup to a new file, which I then located in a new folder under the template parent and included from the buddypress-functions.php file, one immediate issue was the apply_filters that existed for each search form function as this meant backwards compatibility had to be taken into account, if any function had been filtered we needed to honour that also in each template we called the search forms in using a unique name, both of aspects required a re-think on the approach I’ve used in the past replacing function calls and creating a new single form function checking components to add correct query arg, my initial approach then was to write out the existing functions in my new file but in each I called in a new form block so that I only need deal with one single form in markup terms, as the apply_filters were retained, I was free to then delete the old core functions altogether, this worked but was far from the rosy ideal I had in mind I also struggled with whether it was better to use bp_get_template_part() with it’s built in ability to look to theme directories for parts to include over a new function to manage including files looking at the template stack (similar to our stylesheet locate_asset_in_stack() I settled on the latter as I felt uncomfortable with the new file being strictly regarded as a template part.

A second approach was mooted and demonstrated when @boone took a look and provided an alternative approach and I’m very grateful for Boone’s time on this as it settled some concerns I had but also provided a better alternative.

This second pass at the task is the one I’ve now reverted my files to and updated the other directory index templates to.
Essentially we now check in the template files to see whether the old function has filters applied to it has_filter() in which case we load the original function else we load our new function from the new template file located in a new dir common/ fetched via bp_get_template_part() which handles the file location, i.e overloading files from BP core to theme or child theme positions. To provide the correct form control names, query args etc we have new template tags in bp-core-template.php – bp_search_input_name(), bp_search_placeholder(), bp_search_default_text()

Although I have some regrets having to run checks in case filters are in use and loading older functions, in truth this aspect in the actual templates would simply be changed to just run the new template call in any new core templates or overloaded ones, the other sadness is that in fact we need to retain functions in core that really I wanted to see removed, but given we achieve the majority of requirements with the approach in the second pass the regrets are minor and not impediments.

Moving forward I want to implement the next ticket perhaps tackling the directory filters which also could be streamlined into one function, and tackling another set of template markup functions will allow us to see whether the generic approach will work or needs refinement to some degree.

It will be interesting to hear anyone’s thoughts on this whole process, feedback and considerations perhaps overlooked will be really welcome, it could well be the case that in fact we could build a better approach in core to managing new template tags? At this stage we have the opportunity to explore options, do we like the idea of this new directory ‘commons/’ for new template parts, has anyone a better suggestion for naming convention? Has anyone any thoughts on how we might best handle new template tags, will it suffice to add these as has been done in bp-core-templates.php or should we separate them in some other way, any and all thoughts are welcome!

I’ve made an early start to this in the belief that we could get a lot of these markup functions identified and moved for BP 2.6, if not all a significant number of them should be possible.