Geodesic Solutions Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{indexmenu_n>10}}
====== 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 support@geodesicsolutions.com 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 [[https://geodesicsolutions.com/geo_store/customers/index.php?task=downloads|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.

===== Parts of Addons =====

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|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.
  * **[[developers/addons/tags/start|Tags]]** - replace a special tag in a template with whatever the addon wants to.
  * **[[developers/addons/pages/start|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".
  * **[[developers/addons/setup/start|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.
  * **[[developers/addons/admin/start|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((in other words, don't use it as a "lazy" way to accomplish something that can be done much better another way)), 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 [[tutorials/development/auto_check_extras|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.

===== Addon Folder Guidelines =====
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((For one, the addon text exporter uses a . between addon name and auth tag, so export/import text would not work for your addon.)).
  * 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((For instance what you use for //auth_tag// in the info.php file.)).  Doing this will greatly reduce the chances of compatibility problems from 2 different addons using the same folder name.


===== Advertise your Addons =====

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.

==== Geocoregoodies.com Guidelines ====

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((Yes following the guidelines can take longer, and thus cost more for custom development, for instance taking time to use an addon hook instead of editing the base software...  But it also means less work for each update.  In other words, following these guidelines will cost a little "more now" but save a lot in the long run.  We have seen many a site have to hire a developer to re-do customizations using these guidelines after they find their site is no longer able to be updated without paying an arm and a leg for every update, just to re-apply changes.)), 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**.((If you think that a core file needs to be modified to accomplish something, contact us for options. As stated on the [[developers/start|developers page]], we can add new hooks to the software if there is not a way to accomplish something already, or can point you to an existing way to accomplish what you need if there is already a way to do what you want.))
  * 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((We will still remove even "free" addons that are not supported in some way by the author, if that addon becomes a "problem" meaning we get complaints about it from clients.)).
  * 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 [[developers/changes_to_note/start|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>

==== Tips on Licensing / Locking to Domain ====

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((Note that encoding the software is very different from obfuscation.  We recommend encoding out of the 2, using Ioncube as that is what the main software uses itself.  Obfuscation is usually very easy to bypass.)) 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:**((Bad because there is no way to tell what addon is generating the error.  Customize your errors!!))  //This script is locked to a different domain.//
    * **GOOD:**((Good because the error message generated by the source code protection, was customized to include the author and addon name, so it is crystal clear what is generating the error and who needs to be contacted to fix it.))  //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 [[http://ioncube.com|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.((Yes this was sort of point 1 as well.  This is actually the main reason we created this section, as that happens from time to time, a client sees the error and gets mad at us.  In fact that is one of the main causes of "bad reviews" people leave on sites about our software, they see some error given by a 3rd party addon, think it is from the main software, and before we even have a chance to tell them it is not the software doing it, they leave angry reviews about us.  So please help stop angry reviews of our software, include your name in license error messages!  Thanks!  :-) ))


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 [[http://geodesicsolutions.com/phpdocs/addons.example.info.html#addon_example_info::enableCheck()|Developer API Docs Here]] or in the source code of the example addon.
Geodesic Solutions Community Wiki

User Tools

Site Tools

Page Tools
