Addons

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

Important change (2018-06-18): These instructions have been modified and are in the process of being improved. The previous “full” addon branches have been removed from the Scipio addon Git repos, while the “subtree” method described below is the method that should now principally be used by nearly all projects. If you previously used the “full” merge method to get addons, please switch to the “subtree” method below. The process will be simplified further shortly and this page updated again. Thank you.

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.

Usually the best 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
  • 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

Addon Layout

Each addon’s Git repository consists of:

  • Several “subtree/[addons|themes]/[component]” or “[addonname]/subtree/[addons|themes]/[component]” branches for each component in the addon and for each SCIPIO ERP branch

Most addons available are simple and contain a single component, so only one subtree branch for each SCIPIO ERP branch.

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

subtree/themes/ignite-admin/1.14
subtree/themes/ignite-admin/master

This addon repo layout allows installing using 2 different sub-project management or merging strategies in order to suit any project.

The subtree branches are meant to provide support for the two widely used Git sub-project integration methods: subtrees and submodules. They also hold the unsquashed addon’s history. Normally, the subtree branch’s name indicates the filesystem path where its component should be placed.

Installing from Git

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.

In addition, you may substitute 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 below assume 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.

In all cases below, after adding the remote for the addon and performing a fetch, it is possible to view the available branches before adding them using:

git branch -r

Git subtrees

This method uses the git subtree command. It merges the squashed addon into your SCIPIO ERP branch and becomes part of your branch. As such it can be edited in-place and if your branch is pushed to a repo and checked out, it will automatically contain the addon. Later, updates can be merged in from our addon repos. A more thorough explanation of the command can be found here.

Because this is a somewhat standard Git function, for many development projects this is the recommended method.

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
git subtree add --squash --prefix=themes/ignite-admin ignite-admin-theme subtree/themes/ignite-admin/[branch]

# For addons with multiple components, repeat the last two commands for each component folder.

# Later, to update ignite-admin:
git subtree pull --squash --prefix=themes/ignite-admin ignite-admin-theme subtree/themes/ignite-admin/[branch]

# For addons with multiple components, repeat the last command for each component folder.

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. Also, it becomes clear from this example that the addon’s subtree branch name (which starts with “/subtree/” here) in effect contains the pathname that you need to specify to the --prefix option.

Tip: To avoid manual errors, you may want to keep a cheat sheet of the commands you used to add each addon and the corresponding pull commands you will need to pull in updates. For complex projects, a helper script such as a linux bash script may be needed. Unfortunately, git does not yet provide a way to record these addresses and paths in project config files for subtree.

Some alternative procedures exist (example using read-tree), each with their strengths and drawbacks; this is the most succinct and least error-prone, with squashed history.

Git submodules

This method uses the git submodule command. Submodules require complex maintenance and are normally only appropriate if you intend to host your own addon repositories mirrored from the SCIPIO ERP addon repositories (mirroring instructions).

NOTE: These instructions are basic examples only. They do not contain all commands necessary to properly update or maintain submodule commit pointers, nor how to clone them properly from your project’s internal repo after you have pushed and shared it. They also do not specify how to keep your mirrors up-to-date with our servers or Github. This is beyond the scope of this article.

You should substitute the remote addresses below with the addresses of your mirrored SCIPIO ERP ScipioCE and addon repositories, otherwise you will not have a copy of the upstream projects and will rely entirely on Ilscipio’s servers.

# Add the addon's component as a submodule
git submodule add -b subtree/themes/ignite-admin/[branch] ssh://.../my-ignite-admin-theme-fork.git themes/ignite-admin
git commit -m "Added ignite-admin theme submodule"
# NOTE: If you are using an addon with multiple components, 
# you will have to run the previous add and commit commands for each component folder.

# Later, to update ignite-admin:
git submodule update --remote --merge
# Record the merge in the parent project (assumes you have no other changes)
git add themes/ignite-admin
git commit -m "Updated ignite-admin theme submodule"

# Push to your server
git push