Get an addon or theme ready for the marketplace

This is a community-contributed tutorial. This tutorial is over a year old and may not apply to your version of Concrete CMS.
Sep 20, 2014

An addon or theme that works beautifully and obviously for the developer may not be robust, easy or user-proof enough for the marketplace. What makes sense to you as a developer may be cryptic to others. Getting an addon or theme ready for the marketplace can typically involve an additional 20% to 50% on the work you would put into developing for a single site.

There are many procedural issues with getting a marketplace submission through the PRB. Here I will run through some of the common technical issues.

PHP Version

If you develop on the latest php version, check you have not used any php syntax or functions that do not exist in older php versions that others may be running. As developers, many of us like to use the latest and shiniest software toys. Meanwhile, a site owner could be using a php installation that is way back at php version 5.2 (or 5.3 for Concrete CMS 5.7+). We don’t want your addon or theme to break their site!

Errors and Warnings

Perhaps your production server is set up to be as forgiving as possible, to continue running despite minor errors and warnings. However, you can't be sure your users will be running such a benign environment and reviewers probably won't be either. So similar to php version, you will also want all the errors and warnings switched on throughout your server software.

User inputs

You may be careful about inputting correct values, but site owners or even site visitors may not be so careful. Some site visitors may even be malicious. If it is possible to enter an input value that will cause an error, your marketplace submission will not be approved. Some typical weaknesses left by developers include:

  • Non numeric values breaking a numeric input field.
  • Long text inputs being too big for fixed length database fields.
  • Incorrectly quoted text breaking an html tag on the page it is rendered on.
  • Empty inputs causing subsequent null object or zero errors.
  • A over-long or too big input value causing something to overflow or to keep looping effectively forever.
  • Script or SQL injection - where an site visitor can input text that, when rendered later, inserts script or SQL that does something they should not be allowed to do.

The PRB will look critically at inputs in dashboard pages and edit dialogs. When an input is open to a site visitor, the PRB will look at it very critically.

A related issue is uneconomical database fields. Don't be tempted to declare every database field as X or X2 so as to avoid any risk of overflow. As a general rule, database fields should be of a type and size relevant to their purpose and no more.

User Interface

There are conventions in the Concrete user interface. In most cases, marketplace submissions should stick to those conventions. If your submission goes outside those conventions, the PRB will expect you to justify why.

If the convention is for a blue button, don’t try and design an edit dialog with a rainbow striped button.

Text Translation

Your development may be just in English or your own language, but for the marketplace all themes and addons must support translation into other languages. This means that all interface text strings must be written in English with t() functions wrapped about each string. You don't need to provide any translations, just wrap the t() functions about all text strings so that the Concrete core can match them to translations.

These t() functions should be about the raw strings. Placing them about variables obstruct translators from picking out the strings to write translation text.

You can find out more about translation in Internationalization and the t() functions family. The howto in turn links to further howto and other translation help and resources.

Often forgotten are date displays. Remember that different countries have different conventions for writing dates, to make sure any date format is also wrapped in a t() to facilitate translation and ideally uses one of the standard Concrete date constants.

Theme compatibility

You may have developed a block while working on a site with a particular theme. However, when that block is released to the marketplace, your block will have to work with any theme. The PRB obviously cant test it against all possible themes, but it will be tested on the core themes such as Elemental or Greek Yogurt and a few others picked from the experience of PRB members with the sole purpose of finding something that breaks.

Core user interface

Creating style side-effects in the core user interface is most common in themes, but can also happen with blocks. That CSS, HTML or JavaScript introduced by your addon or theme moves a field in a dialog down a few pixels, changes its font or changes its colour may not matter to your one-site project, but it will matter to another user somewhere.

Because the Concrete core uses Bootstrap, Bootstrap based theme or addon styling needs to be especially careful of CSS side effects. Another common area of side effects is jQuery.UI styled blocks.

Use Concrete API libraries, models and helpers

The general rule is that if there is a Concrete utility for doing something, you should use it, even if it appears more long-winded than a direct call to a php function. Common mistakes in this area include php include statements, direct file input/output and JSON conversion.

Using core utilities often helps make code more flexible and robust, allowing an addon to be installed in a wider range of environments and protecting against known issues and edge cases.

Again, such conformance may not be important to a single development, but it becomes important when other developers use marketplace addons or themes from many different developers.

Function and class namespace

A single site addon or theme doesn't have to be overly concerned about colliding with other addons or themes. Where two variables, functions, classes or anything else accidentally end up with the same name and consequently cause errors, on a single site you, the developer, have control of everything, so you can fix it.

When a theme or addon is released into the marketplace, anything that uses a name visible outside of your addon or theme could conflict with something else. Names you have used need to coexist with names that thousands of other developers may be using. When two of those names collide, it can result in some hard to track bugs and consequent support requests. This can apply to PHP, JavaScript, database tables, files, and as discussed above, to CSS.

In general:

  • Stick to Concrete naming conventions for files and classes.
  • Where possible, keep any name locally scoped. If it isn't visible outside your submission, then it can't be confused with anything else.
  • If it needs to be visible outside your submission, use a prefix or wrapper of some sort. Many developers use their initials or business names, so protecting the namespace also promotes their branding!
  • Don't steal other's namespaces. For example, a JavaScript file that steals the jQuery "$" magic function is doomed to cause script errors if used in conjunction with many addons, themes or the Concrete core.

Clean up after yourself

Uninstall is rarely important on a single site project. In the wild, uninstalling cleanly is very much more important. Much of uninstalling is addon dependant. For a simple block, it may not even be necessary.

Automated Tests

You can check a package against the automated tests before submitting to the marketplace. That way, you can resolve any sutomated test failured before making the official submission. See Lint a Package.

Documentation

Not an inside technical issue, but worth repeating here. What is often obvious to you, the developer, or even to your directly trained customer, can easily be not so obvious or even cryptic to others. A marketplace submission needs to have relevant and detailed documentation. Good documentation can also help with sales.

Minimal documentation may just about be approved, but graded as requiring more expertise to use. Minimal documentation can result in a green (beginner) addon being re-graded to red (developer) for the marketplace. Good documentation can make a complex addon orange (intermediate) or even green (beginner).

Read more How-tos by JohntheFish

Recent Tutorials
Reusing the same Express entity in multiple associations
Apr 11, 2024
By myq.

How to create and manage multiple associations in Express

Express Form Styling
Apr 11, 2024
By myq.

Different ways to style Express forms

Setting addon/theme version compatibility in the marketplace
Jan 9, 2024

For developers worn out with setting the latest addon or theme version manually across too many core versions, here is a JavaScript bookmarklet to do it for you.

How to get the locale of a page
Jan 8, 2024
By wtfdesign.

Now, why don't we just have a getLocale() method on Page objects beats me, but here's how you work around it

Using a Redis Server
Jun 16, 2023
By mlocati.

How to configure Concrete to use one or more Redis servers to persist the cache.

Using the Concrete Migration Tool Addon
Apr 27, 2023

How to use the Concrete CMS Migration Tool

Improvements?

Let us know by posting here.