HTML Logo by World Wide Web Consortium ( Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS. ocPortal 9 is superseded by Composr 10.

Head over to for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.

Feature development example: external-zones

Please note that this article was written before ocPortal version 4.0, which implemented something similar to what is discussed here.

Workflow diagram

An image illustrating a feature workflow for ocPortal. A text version of this image is available at the end of this document.
To help give you a look at the life of a feature suggestion, I'm going to share a real-life example of a popularly requested feature that, theoretically could be cool and 'easy to add', but in reality will be very tricky to implement. Hopefully this will give you a perspective into our thought processes. This article we will only look at one of many steps needed to see a feature completed: the planning phase.

The proposed feature we're going to explore is the ability to be able to place different links on the 'Zone menu' of the ocPortal default theme. Right now ocPortal automatically fills that area with links to each 'zone' of ocPortal. The suggestion is to allow administrators to add other links (to things like individual pages or to other websites) into that list. It sounds like a really cool theory… administrators could add whatever they wanted to up there – it would be completely customizable.

Here's a screenshot that illustrates what change we're talking about:
An illustration of where this change would occur

In a sense, this already exists. Users could delete the template that ocPortal uses to create that list of zones, and people could replace it with anything they wanted, assuming they knew how to program. But the feature proposed here is to allow users to keep the links up there intact – and just add new ones onto the end. ocPortal currently isn't designed to do this.

Deciding how to add this feature requires some thought. Going with the assumption that only "zones" should be in that list, we need an excuse to allow non-zones in there, too. Perhaps we should make a new 'kind' of zone so that we can keep that list up exclusively for 'zones'. We could call this new zone an "external zone", which would be a slimmed down zone that didn't actually follow any of the conventions that zones now have. It would essentially just be an additional link shown on this menu that could take people anywhere, so it doesn't abide by a lot of the things that make a zone a zone currently.

But the problem here is that we're really violating what a "zone" is. Right now it's defined as "a collection of ocPortal pages", which this new 'external zone' sure isn't. If we were to add 'external zones' as a feature, then we have a number of problems:
  • One is that we're breaking the definition of what a 'zone' is. Now since we're the writers of ocPortal we could, of course just change the definition. But there's a really good reason that we don't want to do that. Think about it – what is the purpose for a definition of an English word? It's so that when the word (or 'feature' in this case) is used in lots of different situations, it can always be clearly understood exactly where the boundaries start and end, and what its purpose is. If we changed the definition of a zone, then what happens is that we need to go back to every time we've ever used the 'zones' feature and make sure that our new definition still fits without causing any problems. Often problems do develop, like the assumption that each zone has a folder on your server (this wouldn't apply for external zones), so this creates what we call "dependency problems". It's basically a chain reaction where you 'fix' a problem but cause two more in the process. Changing definitions is a tricky tricky business that is rarely feasible.

The other side of that technical nightmare is the policy nightmare that also occurs. Let's assume for a moment that we changed the definition of the "zone" feature and patched every little bug and security hole that resulted from it. Now we also have the surface issues that result. Now that the definition of a "zone" has been expanded to fit two basically different features, we need to be able to explain this to our users. This means that when you click "edit zone", should we build two totally different forms to fit each kind of zone, or make it one unified form with the irrelevant options disabled?

And once you incorporate all of those interface changes, you need to make sure that the administrator understands the difference between zone types, advantages of each, ways to use both, etc etc.

Hopefully the picture you're beginning to see is that we cannot only make decisions based on individual features like this – we have to make policy decisions that influence the design of the overall product. So for example, if we made a policy decision to not give much thought to consistency (stretching the definition of a 'zone' is an example of this), then ocPortal would be much harder to use. It would be almost impossible to understand how parts of the system slot together (no longer could anyone assume that, for example, they can always assign permissions to "a zone").

That said, if it was really important, we could make exceptions to policies like this if we felt it was necessary. But this would only happen if we:
  • Have no alternative
  • Can justify the change because of an exceptional need

So, let's abandon the "external zone" approach to incorporating this feature. Let's try a new way of doing it – what if we make it so that ocPortal just thinks that that entire list of links is like any other menu: a list of user-configurable links? We already have a 'menu' system that's working well that lets people have their own list of links on the left-hand panel. This could be a special 'menu' that ocPortal populates with a list of links when new zones are added. That way we don't need to worry about redefining a 'zone', and now new links could be added to that menu freely.

But there's a problem. This solution violates the "separation of concerns" engineering principle. You can read more about it on wikipedia, but this quote sums up the reasoning well:
"Separation of concerns is an important design principle in many other areas as well, such as urban planning, architecture and information design. The goal is to design systems so that functions can be optimized independently of other functions, so that failure of one function does not cause other functions to fail, and in general to make it easier to understand, design and manage complex interdependent systems".

Separation of concerns

I wouldn't go so far to say that separation of concerns is something we always have to consider. For instance, allowing the shoutbox to work as an embedded chat room makes things cleaner, not more complex: features complement of the two complement and the association is clear and fairly easy to understand. I don't believe creating an association between zones and menus would be clear or easy to understand. These decisions are often very subtle and the subtleties are carefully considered.
  The bold part matches up exactly with our motivation. I fully appreciate how not being able to easily manage the zone-links as it stands now makes things complex. But the unfortunate reality is that the alternative would unify two features that should not be related, and that would cause larger problems in the long run. Making a solution that creates complexity at the very core of the product's framework is not a viable approach to solving the original usability problem that the user mentioned.

In this case, we decided for version 3.1.0 to compromise by allowing the user to make a template edit so that they could replace the automatically generated zone list with a proper menu. This doesn't break any separation of concerns, it doesn't make things inconsistent. The only problem is that it calls for the users to understand how to edit templates. Not all users do, even though it is a key requirement to changing the look of ocPortal (and any other web system).

But in the interest of the original proposal (which was to make this whole process easy on the user), we decided that in the long-term, we should make a solution that didn't require a template edit. Since we've already ruled out the concept of an 'external zone' and don't want to tie the menu system and zones together, we thought of one other idea.

This idea is to add an on/off option titled something like "Enable self-managed zone-menu". This would give people an interface to actually manage the whole system without causing any of the conflicts that we mentioned earlier.

But, it does introduce one new issue, and it's another manifestation of this separation of concerns issue. Here we go:

Those zone-links are purely a feature of the default ocPortal theme, and ocPortal's configuration should not make any assumptions about what theme is being used. It might be that a different theme is being used that doesn't have the zone-links, and therefore the option wouldn't make sense.

So, we could make one exception for this particular example. And then down the road we'd probably want other 'options' that would be equally justified as exceptions, and if they were all made to be exceptions, we'd end up with a big mess..

So why not build a new feature, a new definition, to contain all of these? We came up with the idea of 'Theme options'. After this feature exists, all themes will have their own set of options. These options would tweak some things about how those themes look. One option would be to enable a self-managed zone-menu, another would be to disable the help panel (another popular feature suggestion). However, for 'Theme options' to work we'll need to write a whole new area of the ocPortal Admin Zone, and extend the capabilities of themes – we can only do that in a major release.

So our long-term intention is to make a 'Theme options' system, which we may well incorporate into 4.0.x (though as I talked about at the beginning, we cannot provide any kind of guarantee or timescale for this since we might decide on something different, or something completely unforeseen might change our way of thinking.)


All of this effort is for phase one: planning. We're not going to explore this any further (in actuality this is all an oversimplification and there's far more little details involved), but to give you some perspective take a look at the other steps that will be involved before this feature comes to pass:

1) Planning
The long phase of deciding how the change is going to be made – you just read about this

2) Writing
Actually making all of the changes – it takes a while

3) Testing
Every new line of code needs to be tested again and again to check for problems.

4) Update documentation
Any documentation that talks about the feature involved needs to be updated

5) Rinse, lather, repeat
As community reports come in we learn about new bugs, maybe a security problem, a handful of confused users who didn't read the documentation, new things that break because of it, etc etc. Each line of code we have is literally a monthly cost that we have to budget for.

The purpose of this is to give you an idea of how large an undertaking even apparent "simple" features are. The fact isn't necessarily that we're afraid of the work involved, or by any means that we don't want any more suggestions, but many times they would require us to make sacrifices in usability in other areas, confuse the users with yet another feature, and "bloat" ocPortal that much more, and a balance needs to be made. As staff, we take the time to weigh that balance with every feature that is suggested on our forums. This is the reason we ask our users to only propose features once - because posting the request again will distract us from what we're working on and will not change the architectural limitations that made us decide yes or no in the first place. It is also for these reasons that we cannot spend the time to give each of you a commentary on the feature ideas you share with us – it simply isn't realistic and prevents us from spending time on ocPortal and our personal lives.

Thank you for taking the time to read this far – we appreciate your understanding with regards to this subject, and hope you've learned something in the process.