Addons

Last updated: 2019-06-11
Important changes (2019-06-11): The legacy Scipio addons branches that were name “subtree/*” have now been removed and were no longer needed. Please use the git-addons script instead. If you have issues switching, contact us.

Scipio ERP offers a number of addons available for enterprise clients as well as through Scipio ERP Store. These include functional Addons for social media, web integration and payment providers, as well as alternative backend and frontend Themes.

Addons and Themes, together referred to as “plugins” or “addons” for short, are installed into Scipio ERP using the drop-in addons/ and themes/ component container folders, respectively. These have specially modified framework integration to allow better self-containment and expression of dependencies. Some addons require extra configuration and some may be composed of more than one component, but many can work out-of-the-box.

The official way to integrate addons into your project is using the Git version control system, which allows to customize the addons while maintaining the ability to merge changes from upstream if needed. It is possible to manually drop-in the addons into the project, but this is rarely appropriate except for demoing purposes.

We provide access to Git repositories for the addons. Upon placing an order for an addon or receiving enterprise access, you will be provided with a Scipio ERP Gitlab account, a way to add an SSH key to your account, and a link to the Git repository for the addon.

Requirements

• Git 2.0 or greater command line client or equivalent (commands may run on older versions, but not recommended) – to determine, run: git --version NOTE: Git 2.7 or later is highly recommended
• An SSH agent loaded with your SSH key
• A copy or forked project of Scipio ERP – cloned from Github, the Scipio ERP Gitlab, your own mirror or the address of your forked project
• For the git-addons script: Bash v4 or higher (Linux/Mac; for Windows, Git Bash or Cygwin may need to be used)

Addon Layout

Each addon’s Git repository consists of:

• An addon branch for and named after each major Scipio ERP branch: master, 2.x, … (NOTE: in the past, these branches were pre-squashed “full” branches from root; these have been replaced by regular subtree branches)
• Legacy support: several “subtree/[addons|themes]/[component]/[master|2.x|…]” branches – these are exact copies of the [master|2.x|…] branches, provided for backward compability for the time being (NOTE: These may be removed in some time) 2019-06-11: Removed.

For example, currently the Ignite Admin theme contains the following branches:

master
2.x

These branches are most often single Scipio ERP components, though some may also have more than one contained. They are mainly intended to be added into Scipio ERP working copies at predetermined component directory locations using Git subtrees, with or without the git-addons script detailed below.

Preparation

In the examples below, you will have to substitute ssh://.../[addon].git with the addon repository address provided to you, and the [branch] with the name of the Scipio ERP branch you intend to work with and checkout, or that your project’s branch forked from. You must always use the same branch name for SCIPIO ERP and any addons you merge (i.e. Do not try to install master addon branches into Scipio 2.x branch or installed copy).

You may substitute the address https://github.com/ilscipio/scipio-erp.git with the Scipio ERP Gitlab ScipioCE address (it is a mirror), your own mirror or the address of your project.

All commands in the sections after this assume that you cloned either your own project forked from Scipio ERP or Scipio ERP itself in case you are preparing to push to a new repo, and you checked out the branch in question. The simplest way to test the instructions below is to simply clone Scipio ERP (but you will have to push the result to another remote afterward):

git clone https://github.com/ilscipio/scipio-erp.git
cd scipio-erp
git checkout [branch]

To mirror SCIPIO ERP to a git repository of your own, you could do:

git clone --bare https://github.com/ilscipio/scipio-erp.git
cd scipio-erp.git
git push --mirror https://[my-server-address]/my-scipio-erp-fork.git

and afterward delete the scipio-erp.git folder and re-clone from my-scipio-erp-fork.git.

Installing addons

Addons can be installed with the help of the new git-addons script, or failing that, manually using git subtree commands.

It is also possible to use Git submodules, but they are rarely appropriate for Scipio-based projects and usually not recommended in this context, and so will not be covered here.

Installing addons using the git-addons bash script

As of 2018-06-22, the Scipio ERP Community Edition master branch and upcoming branches contain a simple addon installation Bash script in the project root: git-addons. It requires Bash v4 or higher or compatible environment (for Linux/Mac; for Windows, use or update your Git Bash, Cygwin, etc.).

The script’s main purpose is to add and pull addons into your working copy using git subtree. It merges the squashed addon into your Scipio ERP branch and becomes part of your branch. As such the addon can be edited in-place and if your branch is pushed to a repo and checked out, it will automatically contain the addon (as opposed to git submodules). Further updates are merged in.

Secondarily, the script can also trigger addon configuration and data load.

For help, simply type on the console:

./git-addons help

Configuring the git-addons script

Before using the other commands below, if you have purchased an addon from the Scipio store, you must input the base ssh://…/SCIPIO-ERP/ address you received (excluding the addon.git suffix) into the file: git-addons-config, with trailing slash:

SCIPIO_ADDONS_URL_EE="ssh://.../SCIPIO-ERP/"

You will have to commit the change locally (otherwise the other commands will complain about working copy changes):

git add git-addons-config
git commit -m "Updated git-addons-config"

Alternatively to git-addons-config, you can instead set the SCIPIO_ADDONS_URL_EE variable in a file named “git-addons-config-local” in the same directory as git-addons-config (you will need to create the file). The filename git-addons-config-local is under git ignore and therefore does not need to be committed. This is suitable if only one developer is handling the addons for your project.

If you omit setting this address, you will only be able to pull community/public addons from Github.

Using the git-addons script

To get a list of available addons and status of ones installed, as well as the target folders for each addon:

./git-addons list --all

To add the files for a new addon or update an existing one:

./git-addons pull angular-shop

This command will invoke git subtree pull or git subtree add, as appropriate, depending on whether the addon is already installed or not. NOTE: If you add any options (e.g. -e, –dry-run), they must come after the addon name (e.g. ./git-addons pull angular-shop -e).

In addition, the ‘pull’ command will automatically trigger addon configuration, if any is available or needed (this can be prevented by passing –no-config option).

To update all subtree addons in your working copy:

./git-addons pull --all

Note that addon updates will usually prompt you to enter a merge commit message (this can be turned off by passing the -e option to git-addons). If a conflict occurs during pull, you will have to resolve it using the regular Git conflict resolution commands, commit, and re-run the script again to finish updates for the remaining addons (if any more).

After you have pulled an addon, you can optionally load seed and/or demo data for the addon individually using the load-xxxx command:

./git-addons load-demo angular-shop
OR
./git-addons load-production angular-shop

Note that you only need to do this if you are adding an addon after you have already seeded your Scipio project using ./ant [load-demo|load-extseed|…] or the install.sh script. If you have not yet seeded the main project, the addon’s data will automatically be included with all others when you seed the main project.

As a shortcut, it is also possible to run ‘pull’ and ‘load-xxxx’ in a single command, ‘install-xxxx’:

./git-addons install-demo angular-shop
OR
./git-addons install-production angular-shop

Limitations

Note that the script can only update addons installed using Git subtree. If you have an addon you installed using a different method, you will have to remove it before running the commands above (and reapply any custom changes afterward). This is because the Git subtree command can only merge in changes to a subtree that it previously added and squashed itself.

If you experience any problems with the script, please contact us by either opening a thread on the Scipio ERP forums or a ticket on Github.

Custom git-addons addon definitions

The git-addons-config script file contains the information for all Scipio ERP addons. Most users should not have need to edit or override them.

If you do need custom definitions (e.g., to fork an addon to a different target folder than the default, install multiple modified copies of the same one into different folders, etc.), you can add overrides at the end of the file overriding or adding entries in the SCIPIO_ADDON_MAP array. The entry format is documented above.

Manual addon installation: Git subtrees

If you are unable to use the git-addons script or run into problems, you may try to add/pull addons manually using git subtree commands directly. Another more thorough explanation of the subtree command can be found here.

The following is an example using the Ignite Admin Theme:

# Add the addon project remote
git remote add ignite-admin-theme ssh://.../ignite-admin-theme.git

# Add the addon's component as a subtree
# NOTE: To get correct target folder (--prefix), consult the output of "./git-addons list --all"
git subtree add --squash --prefix=themes/ignite-admin ignite-admin-theme [master|2.x|...]

# Later, to update ignite-admin:
git subtree pull --squash --prefix=themes/ignite-admin ignite-admin-theme [master|2.x|...]

Note that the subtree add and subtree pull commands must always have the same parameters. The squash flag is always necessary for this usage of subtrees. These commands must be re-inputted in full every time because git subtree does not record much information about the subtrees on its own.

Advanced: Some other subtree-like integration methods exist as alternatives to the git subtree command (example using read-tree), each with their strengths and drawbacks; git subtree is simply the most popular, succinct and least error-prone, and as such the only one currently supported in Scipio.