BP Style Modules – a proposal

User Submitted Style Modules

This post is a RFC to gauge feedback from the wider BP community for an idea I have been mulling over and sketching out in rough code locally.


Style Modules is a concept that seeks to provide or explore a means to add CSS and JavaScript snippets to existing themes in a modular sense for BP elements or components – think Members list ul/li constructs or user profile messaging table lists – allowing developers to work on specific aspects of BP’s components adding style enhancements or added JS functionality.

Why Modular? Modular is a method we can use to provide added enhancement in easy to manage smaller ‘chunks’; small enhancement files created by the BP development community where they can concentrate on improving a given area without feeling bowed down by an overwhelming challenge.
Modular because users can download and install just the enhancement they desire without effecting aspects of their BP install they’re happy with.

The Primary Benefit(s):

There is in this proposal one overriding aim, that prompted thinking this through to very basic implementation which is that the BP project is able to bring to the community a further means to engage in the project and to feel even more a part of that project as a contributor acknowledged as such by their module inclusion.

As we’re all aware engagement is paramount for a healthy project, the more people that feel engaged and involved the healthier any project is; this is one means to further that aim and to bring people in to contributing, and contributing at a level that could as equally suit mid range coders as more advanced coders, and where the established developers can mentor and advise where it helps.

A secondary benefit would be that BP gains far more by way of enhancement to it’s components and gains a growing library users can peruse and download modules they like the look of, which install in a very simple fashion by simply dropping into the correct sub folder.

The Approach

So far the approach to implementing this idea and which I’ve been working from is thus:

A module is defined in a ‘folder'(directory) that lives under the BP folders /community/style-modules//buddypress/style-modules/

The user needs to create the /style-modules folder (conversely we could possibly create programatically, but would rather avoid that)

The folder /style-modules/ is a critical one we scan for this folder and don’t continue if not found.

A module is defined as a folder e.g /bp-members-list-module/ this folder constitutes the ‘module’ as uploaded to the repo or downloaded to users site theme directory for use.

In the ‘module’ we have a series of files that validate the module, in the simplistic offering this folder will contain a stylesheet, in more advanced ones we might also have a supporting JS file or perhaps just a JS one (JS supporting styles was my original thinking). All modules will contain a readme.txt file (maybe in .md form), the stylesheet will use style headers in a similar manner to WP stylesheets. Both the style file and the JS file if included take the same name as the module directory name, using just the file ext to identify the type (file headers could expand this though & partly why they are mentioned)

By example in a practical module or example module to use as a skeleton we’ll set out some guidelines to follow for a module to be considered for inclusion.

An example initial module might be member lists as panels(boxes) – often desired; a module would provide this styling for members lists to work for twenty* themes.

Loading the Modules:

Loading up the modules will be relatively trivial and involve a directory scan and fopen to enqueue an array of files, for local purposes I’ve run a simple scandir and fopen looping out the files to build an array on files I find as long as the ‘modules’ parent is located otherwise I’ll bail. This process we already do do in BP’s templates functions.php so I propose we simply extend that to check for this folder given two criteria are met 1/ running a BP overloaded theme 2/ having the existence of a folder named ‘/modules/’

If BP provides the mechanism for loading automagically then it’s easy for users to use these files, and an incentive for dev to produce them.

Curating & Location:

My proposal would be that we maintained a ‘modules’ repo on BP’s github account in which modules would be kept available for download, along with instructions for use.

BP would be making it clear that while the modules were tested not to cause any major issues it didn’t guarantee that they would work for all themes/installs.

Curation would be amount to one or more devs stepping up to test a new module to work in a couple of main WP themes, not in detail but not to cause issues, then a scan of the files to ensure basic formatting standards were adhered to. All in all this shouldn’t be too much of a burden on existing BP team, as not expecting hundreds to be submitted, although would be only too happy if that were the case, this would also be something that could be a task for aspiring new contributors to tackle, similar to the way theme reviewing works. 🙂

Comments & Feedback:

Would love to hear some thoughts and comments from the wider community as to whether this idea has any merit, I certainly think it does; yes there are pros and cons and I have deliberately not included the cons at this stage as want to avoid the negative and focus on what might work and if thought viable then tackle the cons in the process.

One definite pro is that overall setting this up is not a huge amount of work!.

Looking forward to comments good or bad.


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: https://buddypress.trac.wordpress.org/ticket/6556

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 https://buddypress.trac.wordpress.org/ticket/6844 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.


Twentysixteen Companion Styles

With the impending release of a new WP theme ‘Twentysixteen‘ in WordPress 4.4 – towards the end of December- , we thought it prudent and a good opportunity to have a look at the theme and implement a ‘Companion’ stylesheet for it as we have been doing for the previous WP themes.

WP 4.4 due to ship late December would likely fall towards the end of the BuddyPress 2.5 release cycle but before we would be ready for release, so with that in mind we decided it wouldn’t hurt to take an advanced look at Twentysixteen and implement our companion stylesheet in our 2.4 release, especially as Twentysixteen was pretty much at a completed state. As this is technically an early release ( although late in our release cycle ) the view was we could implement the sheet and then if necessary tweak and update through our 2.5 cycle.

As with the previous companion styles for twentyfifteen, twentyfourteen etc these styles are intended to compliment the theme and harmonize, while allowing us to address any specific styling issues that might be evident.

Today, Saturday, sees the initial commit of the scs sheet updated for new breakpoints, and layouts of BP screens re-factored for the new themes widths and breakpoints, along with a basic run trough the styles to update and address any initial and obvious issues.

fullwidth bp-user account screen sans sidebar

fullwidth bp-user account screen sans sidebar

We can now iterate on these styles and further refine them where we see outstanding layout concerns or simply for any design factors thought applicable and that suited / complimented twentysixteen.

We would love any feedback from developers, community members and anyone interested in running twentysixteen plus BP ( twentysixteen will only run under WP 4.4 so you will need to be running WP trunk ).

Feedback, comments, patches or simply code snippets (if working with the scss file is awkward) may be left on the master ticket for twentysixteen:

We look forward to hearing any and all comments and suggestions to help BP look at it’s best running under this theme.

Companion Styles – An update

The companion styles tasks progress and we reach a good point for a résúme of the current status.

For those that haven’t read about this project the last bpdevel update post outlines the purpose of these tasks companion-styles-task-updates

We have two main tickets running to cover enhancement styles for the WP themes Twentyfifteen & Twentyfourteen. Last week we committed the initial pass for twentyfourteen’s scss file and compiled CS & rtl CSS files. A further round of updates and styling have been committed to twentyfourteen to bring it to a par with twentyfifteen’s current state of play.

Both sets of files now provide the two themes with styles that are designed to provide additional enhancement supporting the BuddyPress default stylesheet, with the aim of ensuring that BP displays at it’s best and that any particular requirements that the themes have are catered for in these additional stylesheets.

So we achieve our primary goal if we can have an almost seamless rendering of BP elements in one of these given themes, where BP just blends in naturally looking as though it belongs in that theme. Our secondary goal would be to then tweak BP elements to have a little extra sparkle and would be the icing on the cake so to speak.

Our primary aim is pretty much achieved, yes there are still aspects that could take attention and yes doubtless we will find issues to address, but these tasks are less about themeing every aspect as about ensuring a broad sweep on elements to ensure the majority of critical issues are addressed, but overall BP renders in a far more seamless manner now in these themes, with for example twentyfifteen now producing a pleasing experience when we activate BP.

Design factors:

Although the tasks here were always about harmonizing with the theme rather than ‘design’ there are two aspects to both tasks where what may be described as ‘design considerations’ were undertaken, both of these are up for criticism and review.

1/ Major layout elements

Both twentyfourteen & fifteen have what is best described as narrow content widths best used for rendering blog or magazine style posts, this sort of narrow text width container doesn’t suit BP components which need to display quite a bit of detail on pages, thus where BP renders it’s screens we have manipulated those widths to effectively create new layout pages for wider content, while attempting to maintain a relationship with the themes concepts for layout containers.

2/ User Account / Groups object Nav layout
Horizontal navigation has long been an issue where dynamic nav elements are concerned of an unknown quantity, thus for both themes and for the User acount and single groups we have re-factored thse navs so that the primary object nav runs vertically to the left – opinions and thoughts are sought on this, whether this works, or do people prefer the older style horizontal navs?

Community Participation:

At this stage feedback and/or suggestions are welcomed on these two tasks. it would be great if core dev team and all community members that can run local dev installs could switch to using twentyfifteen/twentyfourteen in their day to day dev work and note any issues that they may spot in passing, these can be fed back to the respective tickets 2015 | 2014 or even left as comments to this bpdevel post.

Initially feedback on these two aspects would be helpful:
* Layout re-factoring of parent theme containers for BP screens Dir, Group, user accounts
* Vertical Mnus Useracounts /group screens.

We would also be hugely interested in anyone that has any thoughts on styling specific elements of the BP components e.g the various tables in user accounts, activity stream comment display etc. Again comment feedback or even code if people want to tackle a section and provide a patch via the SCSS file or if not comfortable with SCSS simply work up styles in, say the bottom of the .css version and upload that to the trac ticket and we’ll check it over and if necessary work it into the SCSS file.

Companion Styles Task Updates

This is a brief update on the current progress for this task of creating supporting styles for BuddyPress when activated on the default WordPress themes.

The task origin & concept

This task was originally prompted by a discussion on the rendering of Buddypress on the WP Twentyfifteen theme and the concern we had that BP did not display to it’s best on this theme. We discussed and agreed in essence that it would be nice that BP displayed at it’s best when activated on these default WP themes as they may well be a users first impression of BP and first impressions last 🙂 On the original discussion, having agreed in principle that we needed to correct twentyfifteen display we did create an initial set of corrective styles provided by @mercime and which are rolled into the first iteration of the twentyfifteen styles.

On discussion the proposal or one proposal was that we actually programatically check and enqueue an additional set of styles dependent on the theme activated and that these styles then would address any issues or conflicts arising from the buddypress styles and themes styles. This process would also be used, moving forward, to provide support for any new WP themes released. For existing WP themes we would approach them from a current latest version first tracking back as time allowed in a given release cycle.

The task in hand

This task is now underway and using a patch provided by @r-a-y we can now enqueue new stylesheets if found for the twentysomething themes.

We introduce  styles under pre-processor support (.scss) for these companion styles which likely will be compiled to the bp package as a grunt task, for the purposes of developing and testing I’m compiling locally and including the compiled file in the patch and any subsequent patch updates on a ticket.

A master ticket exists to manage technical discussion at #6248

Individual tickets exist and are underway to manage particular WP theme tasks

The Task Objectives

  • Primary: Correct any obvious issues with styles as pertaining to BP component screens
  • Secondary: Enhance the rendered BP elements with a view to maintaining a harmony with the themes look and style
  • Tertiary : Look to add refined styling for BP elements

For a task to be considered ‘completed’ and viable for inclusion in a release we must fulfill the primary and secondary objectives with the third objective being considered a bonus if we are able to achieve some additional and interesting visual styles that harmonize with the theme.

In this overall task it’s important to keep focused on the initial reason we are tackling these styles as a means of ensuring BP is presented in the best possible light, however we are not ‘theming’ BuddyPress so the third objective while great if we can tackle and add a little bit of an extra ‘wow’ factor should not be the driving force behind the tasks.

Current state of ticket tasks

All ticketed tasks provide a patch containing two files the Scss file and a compiled css file. The scss file provides the framework we will work to and guidance notes and will have some essential initial styles that address the main areas of concern with displays. Breakpoints used in a given theme are noted and provided in commented examples for use if needed.  A few essential mixins are provided to manage font-sizing on a rem/px basis and variables to manage margin/padding, we attempt to ensure we work to the themes parameters in use.

Twentyfifteen currently is underway and addresses in the styles areas such as the restricted content width of the layout which while fine for textual content i.e a post or magazine doesn’t suit more complex content such as is presented on the BP user account screens. re-styles the user object navigation to a vertical style, it also takes a look at the search forms to re-style those.

Twentyfourteen is very similar to Twentyfifteen in it’s content layout and we take the same approach to re-factoring the BP screens layout widths to better render BP elements and also again implement the vertical menu for user accounts. The initial styles are attached to the ticket.

Getting Involved

We welcome any participation in this mini project and people can follow along on the tickets as linked to above, comments are welcome as are contributions of code.

Working with the sheets can either be done by patching a local dev install and using the scss  file to work in, pushing changes back up to the ticket as a fresh patch or if not comfortable working in a pre-processor environment one could simply  copy the the compiled css file from the patch view on a ticket to the bottom of the themes style.css and work there building rulesets but being careful to isolate and mark / section new styles so they can be easily extracted out and added to the ticket as a simple text file, we can then run those to test and then work them into positions within the scss file if need be.

What to get involved with?

As mentioned comments on work to date welcome but if you do fancy running up some visual styles then suggested areas worth looking at might be as follows:

  • The loops: styling the activity stream entries or member lists
  • User account screen specific components
  • BP buttons in general action buttons/actions in lists and /or account headers

In other words drilling down to look at just how specific aspects are rendered and how they may be better presented.

Make.WordPress Community Hub poll

Here’s a reminder for those who haven’t seen it. Please take a few minutes to fill in the Community Hub Poll as the poll closes in the next few days. Get at it!

This poll’s aim is to find out what features the WordPress community would like in their Community Hub. This survey will close at 29 January 2015 00:00 UTC What do we need from you? Please fill in this poll to voice what features you feel are important for the WordPress community hub to have.

Take the poll

Codex News

The codex team are still quietly working away albeit at a gentle pace.

As part of a month by month task list as mentioned in the last update we have reorganized some of the pages in the codex. Further review of articles under the Developer Resources section resulted in finding some deprecated references and moving these to the Archives.
In addition we have added a few new sections and pages as follows:

New sections created:

Administrator Guide – http://codex.buddypress.org/administrator-guide/

Member Guide – http://codex.buddypress.org/member-guide/ ‎

These two sections are top level sections aimed at providing detailed guides for members and administrators of sites. This complements the more basic section ‘Getting Started’
We could do with some community involvement in non technical write ups for using BP from a user front end perspective for these sections, and we’ll list a few ideas for new pages towards the end of the post.

New subsections created:

Updating custom themes for new functionality – https://codex.buddypress.org/themes/updating-custom-themes/ A new section exists added as a sub section of ‘Themes’. The idea of this section is to provide clear detail on any template updates that are required in order for new functionality to be available and will be listed by BP version release. This is intended to help those that have custom themes, overloaded templates, who may miss out on functionality that would normally become available to bp-legacy templates and will show exactly what aspects of markup / styles need to be adjusted.

User Submitted Guides Under the theming & developer sections new sections are added intended to hold community submitted guides that are more related to extending BuddyPress for more custom requirements rather than describing core features.

The restructuring allow us to group codex articles into clearly defined areas while avoiding nesting pages too deeply in the hierarchy. The codex structure adheres to a principle of two levels down from the primary codex home page.

Recently Published Articles

There have been a number of articles added to the codex recently:

In addition we greatly thank contributions from, @Myg0t ‘Useful functions & hacks when using S2member

Improve Codex Navigation

Part of our administrative task is to improve user experience in the BP Codex. This month, our focus is on fixing the navigation structure in the codex sidebar menu and to reveal the hidden breadcrumbs. We’re following up on getting #5906 implemented. In this ticket the codex navigation structure in the sidebars where sub sections show the child pages or main sections and clearly styled to represent a section or page. This will help to facilitate navigation within sections of the codex.

Your Participation is Welcome

If you have suggestions for articles you believe will be useful and should be added to the BP Codex or articles you would like to write, we would love to hear them! Please let us know by leaving a comment below.

For your reference:
BuddyPress Codex table of Contents

That’s all for now,
The Codex Team.