Addons

This section will help developers get started with understanding all the different things an addon can do. It is still very much a work in progress, so if you have questions not answered here, send them to [email protected] and we will be happy to explain things further.

The bulk of the documentation for addons is still in the form of an example addon that can be downloaded from the "public downloads" section in the client area. This section of the user manual is meant to complement the example addon, not replace it.

There are a few main parts to an addon, which are listed below:

• info.php - Holds information about the addon. This is what tells the addon system anything it needs to know, like the addon name, version, and author. It also tells the addon system about some of the capabilities of the addon, for instance it says what core events the addon uses or what tags the addon has.
• Core Events - sometimes called "software hooks", this is one of the main ways an addon will interact with the main software without having to change any of the base code like might normally be required. Core events can do many different things, see the linked page for more info.
• Tags - replace a special tag in a template with whatever the addon wants to.
• Pages - Added in 4.0.0 - Allows the addon to have it own page(s), where it can replace the "mainbody" content with whatever it wants to. The page has a template assigned to it just like a normal "page".
• setup.php - The addon can do what it needs to when the addon is being installed, enabled, disabled, or un-installed. For instance it can create a needed database table when the addon is being installed, and delete that table when the addon is un-installed.
• Admin - Can display pages in the admin, and can display and update addon settings.
  • Addon Settings - Added in 4.0.0 - Addons can have their own settings, using the geoAddon::getRegistry() method. See the documentation on geoRegistry class for more info.
  • Text - Addons can have their own text which will be handled by the "set text" page in the admin for that addon. The text is language specific, and when you retrieve the text in your code using geoAddon::getText() it will already be for the currently selected language.
• app_top.php - Allows your addon to do something at the top of the page load. Only use this if it's the best option¹⁾, as it will be run on every page load.
• Cron tasks - Your addon can create its own cron task if it wants. See the cron/ directory and contents in the example addon.
• Remote API Call - Added in 4.0.0 - An addon can add its own remote API call. See the api/ directory and contents in the example addon.
• Order Item - Added in 4.0.0 - You can create your own order item with an addon. See the order_items/ directory and contents in the example addon, also there is a developer tutorial using a skeleton order item to do what it needs.
• Payment Gateway - Added in 4.0.0 - You can create your own payment gateway with an addon. See the payment_gateways/ directory in the example addon.
• Seller to Buyer Gateway - Added in 4.0.0 - You can create your own "seller to buyer" payment gateway with an addon. See the payment_gateways/seller_buyer/ directory in the example addon.

The addon's folder name is part of what defines the addon, and is used for the name var in the info.php file. To ensure the best compatibility, and reduce chances of future compatibility changes, we recommend using the following guidelines. Some of these are suggestions, and some are required in order for certain things to work in the software.

• Do not use period (.) in the folder name as it will cause problems in the software²⁾.
• Highly recommend using alpha-numeric and underscore (_) characters only. This will ensure best compatibility and reduce/remove any chances of problems in the software itself.
• Check to make sure the name is not already being used by one of the available official addons released by Geodesic Solutions. We also recommend checking the addons posted by 3rd party developers on our site http://geocoregoodies.com.
• Choose a unique name, perhaps consider adding something unique to you to the beginning of each addon folder you create³⁾. Doing this will greatly reduce the chances of compatibility problems from 2 different addons using the same folder name.

We have a website http://geocoregoodies.com, owned and operated by Geodesic Solutions, LLC. specifically for showcasing 3rd party addons (Addons created by you!). If you have created your own addon and would like to sell or give it away, register a developer account on http://geocoregoodies.com and post a listing about your addon on the site. The http://geocoregoodies.com website is powered by GeoClassAuctions Enterprise, and uses a lot of the built in features like ability for users to review addons.

You can create your own developer storefront as well once you get a few addons posted on the site that you want to be able to showcase from a single location on the site.

These guidelines are for developers wishing to advertise an addon on geocoregoodies.com. Below are the guidelines that your addon must adhere to, in order to advertise your addon by posting it on http://geocoregoodies.com. Note that we also recommend these guidelines for any custom / 1-off addon as well⁴⁾, as these are considered "best practices" and good ideas to follow in general.

Addon Requirements:

• Must be a "drop-in addon", meaning that you upload the addon folder, install/enable it in the admin, perhaps change configuration settings or modify templates to add addon tags, and that is it. Beyond uploading the addon folder and perhaps changes to file permissions for your addon, any other steps must be able to be completed from the admin panel, which means no changes to core files or things of that nature. To be absolutely clear: addons that require modification of "core" PHP files even when using the "latest GeoCore version", are not permitted.⁵⁾
• Must provide clear way to contact the author (that's you!) for support questions. Be ready to support your addon, as Geodesic Solutions does not support 3rd party addons at all, we will always refer questions to the addon's author. If you require "paid support" or support for specific time period, be sure that is mentioned clearly in the post. Addons that are no longer supported by the author will be removed. The only exception to this is free addons, if you wish to provide a free addon "as is" clearly state in the description that the addon is free but not supported⁶⁾.
• Must provide the link to purchase and/or download the addon.
• Clearly define all requirements such as if it requires another specific addon to be enabled, and which versions of the main software it is compatible with.
• Enter all required fields accurately when posting the addon. If you are not sure what a particular field should contain, ask us!

These guidelines are subject to revision as needed. If any of the guidelines above are not met, we may remove your listing and attempt to contact you to re-post it with any corrections or changes needed.

Below are recommendations if you plan to post your addon on geocoregoodies.com:

Addon Suggestions:

• Follow the Addon Folder Guidelines.
• Eliminate any HTML inside PHP files, make use of Smarty templates which can be located in sub-folder templates/. That way they can be easily customized through the template set system.
• When there are new Geo updates, we recommend to read the Changes to Note. Any time there are changes that have a high chance of impacting existing addons, we will document it there.
• Keep your addon up to date, to work with newer versions of the software. If your addon only works with older versions of the software, and for whatever reason you cannot or will not update it to work with newer version, be sure to edit the post and make it absolutely clear that it is not compatible with the new version, or simply take the post down.
• Try to follow "best practices" wherever possible, and in your addon documentation make sure to advocate best practices. For instance, you should never have "edit geo_templates/default/…" in the instructions, since you should never edit any templates in the default template set. We recommend to link directly to user manual pages here on our site when applicable.

<tip c n>Note: If you happen to find any addons posted on http://geocoregoodies.com that do not follow the requirements above, please let us know. We do try to review every addon posted but sometimes things can slip through.</tip>

If you are creating an addon that you plan to sell to others, you may wish to use some sort of licensing or other mechanism to ensure that the addon is only used on a single installation. Or perhaps wish to encode or obfuscate⁷⁾ the addon code to prevent others from "stealing" the source code and re-using it.

For brevity, the rest of this section will refer to any sort of "source code protection" or mechanisms to prevent unlicensed copying, as "license protection".

Such practices are perfectly fine as it allows 3rd party developers like yourself, to use technology to make sure your works are not stolen or used without permission, so that you can focus on making great customizations and addons. When you do so however, we ask that you go over the following guidelines:

Tips & Best Practices for Licensing your Addon:

• Include the company / author's name in any license related errors, especially any that might "exit" or cause the rest of the script to not load.
  • BAD:⁸⁾ This script is locked to a different domain.
  • GOOD:⁹⁾ The Acme Co. Anvil addon is locked to a different domain.
  • We cannot stress this enough… When someone with a lot of 3rd party addons tries to change domain names, just think of the headache it would cause if each of those addons generated a generic error and none "claimed" the error.. Not to mention extra down-time and frustration, sometimes that frustration gets mis-directed at Geodesic as it appears the main software is creating the error. So please make sure all error messages include the author and addon name!
• If protecting the code, we recommend Ioncube as that is what the software's licensing files use. Whatever you use, just remember to customize any error messages to include the author / addon name for any type of errors that it produces.
• We discourage using "obfuscation" as that usually causes more "work" for every page load, and in most cases is easy for a PHP developer to unravel the original source code. You are much better off going with an encoding option like Ioncube.
• If validating a license from your server, we generally recommend to save the information in the database or a file so that it does not need to repeatedly contact your server to validate the license. That will cause your servers to get bogged down, and anyone using your addons to have a slow site.
• Any solutions you use to lock, protect, license, etc. - remember to customize all the "built in" errors for whatever tool you are using, so that it includes the author name and addon name in any errors.¹⁰⁾

Note that the example addon, in the info.php file, look at the method addon_example_info::enableCheck() - this is a "built in" location that you can add licensing checks if you wish. Just return "true" to allow the addon to be enabled or "false" and the addon will be disabled for "that page load". Returning false does not affect the actual enable/disable status of the addon, it basically just stops the addon from being used for that page load. If the method does not exist then it defaults to allow the addon to be used. You can see more information in the Developer API Docs Here or in the source code of the example addon.