Documentation

Creating your own branded installation

Every feature and setting in AbleOrganizer that can be customized can also be exported. This capability allows you to create your own custom distributions of AbleOrganizer that can be set up through a web-based installer. These are called branded installations.

Why would you need a branded installation

You might want to consider creating your own branded installations of the platform in the following situations.

  • You have a specific methodology for engaging with communities and want to configure the tools around it for your own system.
  • You are part of a chapter-based organization that needs to set up new installations for a large number of chapters.
  • You work with external clients and want to use AbleOrganizer as a platform that reflects your own identity.
  • You just need specific layout / contact / activity / relationship / report settings with every new installation and don't want to have to set them up over and over again.

Potential downsides

There are a number of potential downsides to creating your own branded installation. You want to be aware of these and take steps to mitigate them.

  • It's possible to overwrite key features in the base platform. This limits the support you can get from other members of the community and your ability to benefit from other contributions.
  • It's possible to break compatibility with future releases of the platform. This complicates your ability to upgrade the system over time.
  • It's possible that your enhancements might not be backwards compatible with other releases of AbleOrganizer. This limits your ability to distribute and share specific components in the system.
  • It's possible that you are creating a fork of the platform. While there's nothing wrong with creating a fork per se, it does have the potential to fragment the community of people using AbleOrganizer. Open source communities are healthiest in numbers.
  • It's possible to run afoul of the GPL license. This is mostly a situational concern that basically revolves around distribution. If you plan to take AbleOrganizer and turn it into a commercial platform that you distribute without releasing the code behind your enhancements, you can get into gray areas really fast.

How to create a branded installation

With the discussion about downsides out of the way, it's pretty easy to understand how to create your own branded installation of AbleOrganizer. There are a number of things you can customize in the core platform, and they include the following items, along with many, many others.

  • The overall look and feel (the theme)
  • The configuration of fields used for contacts, activities and relationships
  • The contact types, activity types and relationship types that ship with the platform
  • The tools for searching and identifying contacts
  • The reports that ship with the platform
  • The content types, user roles, permissions and other items that ship with the platform
  • The options available through the web-based installer
  • The specific modules installed within the underlying content management system
  • The general settings available when a site is set up
  • Preconfigured settings for specific components such as payment processors, third party mailers, deduplication and data injection tools, social media integration, and many other settings

It should be understood there is no single way to customize all the components in AbleOrganizer. The platform is robust and your specific goals can be accomplished a lot of ways.

There are ways of building a branded installation that minimize the potential downsides. This article focuses on those techniques.

Don't hack core

As a rule of thumb, the basic rule of many open source software projects applies: don't hack core. Hacking core will most likely lead to problems that will affect you over time, which will cost money, take time to resolve, and affect your sense of self-confidence and enjoyment of life. Even if you do not run into problems in the short term, you will have to live with the knowledge you broke a cardinal rule of working with open source projects until the inevitiable day some disaster strikes. Disasters only strike on the wrong days, at the worst possible time and when they can cost you the respect of your peers and the people you care about.

If you are going to change something within the underlying platform, the contributed modules, or anything you did not build yourself, consider writing a patch instead. Patches are much easier to track and their impact can be understood without needing to search through every line of code. Patches can be applied through automated installers and shared with project maintainers for eventual incorporation into the base platform. 

Search the web for articles about 'writing a patch for Drupal' if you need to learn how to write a patch. Seriously, it is a lot better to know how to do this than to be watching over your shoulder for problems that will emerge from hacking core.

Use features

There are a lot of techniques for building portable code in Drupal websites. The standard currently in use for AbleOrganzier is features.

Features provide you with a way to export settings through a web-based administrative interface. You can use them to export a ton of settings: contact types, activity types, relationship types, content types, specific fields for each of the previous entities, forms, reports, contexts, settings for user accounts, permissions, and about 90% of the other things that will go into a branded installation. 

There are some best practices for creating features included in the documentation for AbleOrganizer, as well as a set of best practices maintained on the Drupal.org website. Read through these articles and pay special attention to the points about avoiding feature conflicts.

The goal, when you create a feature, should always be to ensure it can operate in harmony with other features installed in AbleOrganizer. You can ensure this will happen by sticking to the practices around namespaces, respecting the reserved paths, and managing fields on contact records. Just remember, best practices are guidelines, and you may run into situations where it makes sense to break them (for instance, if you have a set of contact record fields that apply only to your installation.) 

Clone and override, don't overwrite

One thing that is hard for people to get their heads around is the importance of of cloning and overriding tools in AbleOrganizer instead of overwriting them.

This is a little counterintuitive to someone who has customized the platform. You may have used views or panels to change the way a report looks, or to create new filters for the main list of contacts. You want to share these items with other people.

Overwriting basic components leads to situations where updates to the platform can overwrite your customizations. In general, when you are building a branded installation of AbleOrganizer, it is best to clone a tool and give it a unique machine name instead of exporting a customized version. There are tools for cloning views and panels available within their respective interfaces.

Another thing to understand is that views and panels can be enabled and disabled programmatically. You can write code within a feature that turns the default item off so that your cloned copy is used instead. This is what is meant by overriding.

Export sample content with UUID and deploy

If you are going to export sample content with your branded installation, use the UUID and Deploy modules. There are a number of advantages to taking this route. First off, it allows you to include photos and other media within the exported content. Secondly, it allows you to make your content portable between websites.

Heads up! Future version of AbleOrganizer are going to make extensive use of UUID for keeping data synchronized across multiple sites (this includes contacts, activities, relationships, content, users, paths, tags, and a lot of other stuff). Becoming familiar with UUID and Deploy now is worthwhile because it means you are preparing yourself for the next version.

The basic steps involved in exporting content through UUID and deploy are as follows.

  • Download, install and enable both modules.
  • Create a deploy plan. 
  • Deploy your content to the plan.
  • Create a feature that contains the deploy plan.
  • Export your plan to the feature.

Use a supported theme

If you are going to create a branded installation of AbleOrganizer, you are likely going to want to create your own look and feel for the site. You can create a separate look and feel for the frontend of the platform, the CRM section of the platform, and the backend of the platform.

In general, unless you want to put work into building your own theme from scratch and maintaining it over time, it is best to use a contributed theme for Drupal. You can take any supported them and use it as a base theme for you own work. Currently, AbleOrganizer is using the Omega theme as its own base theme and simply styling it to look the way it looks.

Some considerations about themes:

  • You will most likely want to stick with a theme that is well supported. Look at the number of installations and how long the theme has been around.
  • You will mostly likely want to stick with a theme that supports mobile devices.
  • Different themes offer different options and settings. Look around and find the one that is right for you.