Installing an extension

Every extension sold here installs the same way, so you only have to learn this once. It takes three steps, and all three are required. An extension that has been uploaded but not enabled, or enabled but not permitted, behaves as if it were not there.

Before you start, check the requirements.

Install on a copy first

If you have a staging or test copy of your store, install there first and look at the result. That is true of any extension, from anyone.

Step 1 — Upload the archive

You downloaded a file whose name ends in .ocmod.zip. Do not unzip it, and do not rename it. The store reads the extension's identity out of the filename, so a renamed file installs as the wrong thing.

1. Log in to your admin.
2. Go to Extensions → Installer.
3. Click Upload, and choose the .ocmod.zip file.
4. Wait for the progress bar to finish.

The extension now appears in the list on that page.

Step 2 — Enable it

Uploading only puts the files in place. The store does not use them until the extension is enabled.

1. Go to Extensions → Extensions.
2. In the Choose the extension type dropdown, select Modules.
3. Find the extension in the list.
4. Click the + (install) button next to it, if it is not already installed.
5. Click the pencil (edit) button to open its settings, set Status to Enabled, and click Save.

Step 3 — Grant your user group permission

This is the step people miss

Skipping it is the single most common reason an extension appears broken. You upload it, you enable it, you click through to it, and you get a blank white page, or you are bounced back to the dashboard with no message. That is not a broken extension. That is OpenCart declining to show you a page your user group has no permission for, and saying nothing about it.

Clicking the + in step 2 gives your own user group both permissions automatically. What it does not do is tell your current session about it: permissions are read when you sign in, and yours were read before the extension existed.

So: log out and log back in. For most people that is the whole of step 3, and skipping it produces exactly the blank page above.

Then, if anyone else is to use the extension:

1. Go to System → Users → User Groups.
2. Click the pencil (edit) button on the group you want to give access to.
3. In Access Permission, find the extension's entry and tick it.
4. In Modify Permission, find the same entry and tick it.
5. Click Save.
6. Have those users log out and back in as well.

Each extension's own install page names the exact entry to tick. For Import/export it is extension/preflight/module/preflight. The list is long and alphabetical; your browser's find-on-page is faster than scrolling.

A group you do not tick cannot see the extension, which is a reasonable way to keep it in the hands of the people who should be running it.

Checking it worked

Open the extension from Extensions → Extensions → Modules. You should get its own screen, with its own controls. If you get a blank page or a bounce back to the dashboard, go to troubleshooting an install. Start with the permission step, because that is nearly always what it is.

Updating to a newer version

You cannot upload the new version over the top of the old one. OpenCart refuses: the Installer will not extract into a directory that already exists, and it will not accept an upload whose code it already has. The old version has to come off first, and it comes off in a particular order.

Take a backup first

Steps 1 and 2 delete things. Everything below is designed so that what matters survives them, but a database backup costs a minute and this is exactly the minute to spend it.

1. Extensions → Extensions → Modules, find it, click − (uninstall). This unregisters the module.
2. Extensions → Installer, find it, click uninstall. This deletes its files. Then click delete, which removes its entry and the old archive.
3. Upload the new .ocmod.zip and install it, as in steps 1 and 2 above.
4. Enable it again, as in step 2 above.

You do not have to redo the permissions: those live on the user group and nothing above takes them away. You may have to log out and back in again. The reinstall in step 3 does grant the extension's own screens to the group of whoever runs it, as a fresh install does — so a screen you took away from that group comes back with every update, and you take it away again in System → Users → User Groups afterwards.

What survives an update is up to each extension, because step 1 is OpenCart deleting the extension's settings whether it likes it or not. An extension built here puts them back, and each one says so in its own changelog, under What an update keeps: which settings come back, which are asked for again and why, and whether what comes back is per store or one set for the whole installation. That section is generated from the extension's own declaration rather than written beside it, so it cannot stop being true unnoticed.

A release that adds a setting does not change what your store does. A new setting's default is whatever the extension already did before the setting existed, so there is never a setting you have to go and find after an update to get back the behaviour you had. That is why there is nothing here asking you to record your settings before you start, and no per-extension list of what to set again afterwards: the only ones an update asks for are the ones its changelog names, and they are named because something deliberately refuses to remember them, usually a credential.

What that section cannot tell you is whether a release changed how a setting behaves. That is written by hand, in the release's own changelog entry.

An extension from anywhere else may not put anything back, so read its changelog before you start.

Removing an extension

1. Go to Extensions → Extensions → Modules, find it, and click the − (uninstall) button. This unregisters the module and removes its settings.
2. Go to Extensions → Installer, find it, and click uninstall to delete its files, then delete to remove its entry and its archive.

Both steps are required, in that order: the Installer refuses to remove an extension whose module is still registered.

Data an extension stored for you is a separate question, and a deliberate one: some of it is history that is worth more than the extension. Import/export leaves its job history and journals in place on purpose, and says how to get rid of them.