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.

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
  • A “full”, from-root branch for each major SCIPIO ERP branch: “master”, “1.14”, …
    • For some larger, composed addons, the full branches may be under “[addonname]/full/*” instead: “[addonname]/full/master”, “[addonname]/full/1.14”, …

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

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

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

This addon repo layout allows installing using 3 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.

The full branches are simplest and intended for a quick and easy way to pull and test out addons, with no need to specify the component paths. They are pre-built using the subtree method with squashed history.

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.

Regular merge (full branches, from root)

This method uses a regular Git merge to blend the addon’s full branch into your SCIPIO ERP branch, where the merged components are already relative to the project root. As with the subtree method, the addons become part of the project branch. It is the simplest method to remember because the paths are already taken into account, but it may not be appropriate for all projects.

For Git 2.9 and higher:

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

git fetch ignite-admin-theme

# Add/merge in the addon subfolders (you may get a prompt to edit the merge commit message)
# NOTE: for some repos, the branch name may be in the form: "[addonname]/full/[branch]"
git merge --allow-unrelated-histories ignite-admin-theme/[branch]

# To merge again later, rerun the last two commands.

For Git 2.8 and earlier:

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

git fetch ignite-admin-theme

# Add/merge in the addon subfolders (you may get a prompt to edit the merge commit message)
# NOTE: for some repos, the branch name may be in the form: "[addonname]/full/[branch]"
git merge ignite-admin-theme/[branch]

# To merge again later, rerun the last two commands.

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