Get an addon or theme ready for the marketplace
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).