Using Plugins

Overview

This article deals with customization plugins, which are zip files that contain a plugin.xml file and custom pages, plus maybe extended tables and string key information.

Plugins have been in use only since PS 7.9.  When related to customizations, the process is similar to importing a zip file into CPM via the import process, however, plugins are more powerful than the original CPM import process.  The main differences are covered below. 

The main things to remember about customization plugins are a) plugins are zip files and you install the zip file, and b) not all customizations are plugins.   Don't assume that because the customization comes in a zip file that it's a plugin.  Sometimes developers put customizations in zip files to make them easier to download, such as the sqlReports main download, or it's a zip file for people to use for a CPM import instead.  Always check to see if the customization is a plugin before trying to install it as a plugin.


Customization Plugins vs CPM Imports

If you have been using CPM prior to plugins, you may have done a CPM import.  The whole purpose of a CPM import is to mass upload custom pages into CPM versus the user having to upload one page at a time.  Unfortunately, CPM imports have restrictions on what type of files they will upload and if you want to remove the files that were uploaded, you have to delete the files one at a time.  Also, CPM imports will overwrite any other custom pages similar ot it that may be in place. 

Customization plugins are similar to CPM imports in that they will also mass upload custom pages, however, customization plugins will upload a wide range of files, and will even install extended tables and fields.   During the upload process, the files that are uploaded are tracked in the database, which allows you to delete a customization plugin and it will remove the files it uploaded and you don't have to manually remove the files one at a time.  Extended tables and fields though are not removed.  Also, unlike CPM imports, customization plugins will not overwrite any existing files.  If a file in the plugin already exists, either because it's a core file or a custom file already in use, the plugin install will error out.


Installing a Customization Plugin

The main thing to remember about installing a customization plugin is that you will be installing a zip file.  The zip file contains an xml file that is used to help track the plugin, and then the actual files that will be imported during the install process.  You go to the plugin management dashboard page - it's found via the system settings page, make sure to have adequate page permissions in place to restrict who can install or delete plugins - and choose to install a new plugin.  You will then browse and choose the plugin zip file and install it.  Below is an example of installing a sqlReports plugin - the plugin-sqlReports-46.zip file is the actual plugin and is the file one would choose to install:

46plugin


One of two things will happen after you click the Install button.  You'll either 1) get a message that the plugin was installed successfully, or 2) there were errors during the install and therefore the plugin did not install.   The most common error is a file already exists, and in those cases, the error message will list the file(s). Here is an example of that error:

fileserrors

The above error happens because most plugins will not overwrite existing files.  Any files listed in the error already exist and must be removed in order for that type of plugin to install.  Even if only one file exists the plugin will not install, so use the list as a guide of what files need to be removed.  You can ignore the WEB_ROOT at the start of each reference and begin with the next item.  For example, the above error indicates there is already a file in CPM called dropdownmenu.html in the /admin/sqlReports4 folder.

Another common error is this "Invalid plugin file type" error when using Firefox.  It tends to happen at random and if you switch to another browser and try the install, the plugin will install okay:

FireFoxErrorOr some browsers will not install the zip file but instead unzip it and make you choose files within it.  This is especially common among Safari users on Macs.  If that happens, switch to a different browser as you have to install the zip file for the plugin to install correctly. 


Post-Installation

Once a plugin has been installed successfully, you will need to enable it for it to work.  Like all customizations, you must also have customizations enabled.   You should be able to see that files were installed in two different places:

1 - CPM - where they appear should mimic the folder structure of the files in the plugin zip file.  For example, the sqlReports 4 plugin contains an admin folder and a sqlReports4 subfolder with folders and files within it.  If you expand the admin folder in CPM, you should see a sqlReports4 folder in it after installing the plugin, along with folders and files within it.  You can make changes to those files, replace files, or even add new ones. 

2 - in the plugin information page - click on the name of the plugin on the Plugin Management Dashboard page and then look for an Installed Resources section.  The Web Resources area will list all of the files that were installed with the customization (FYI - if this part is blank after trying to install a customization, it's likely that only the plugin.xml file got installed rather than the zip file).

pluginresources

If you delete the plugin, any files that the plugin installed will be removed, whether they're still in their original condition or have been modified.  The folders and subfolders that are part of the plugin are not removed, and neither are any new files that you've manually added in CPM.  If the plugin installed any extended tables or fields, they will not be removed either, so be sure to check to see if a plugin will be adding them (FYI - sqlReports does not add any extended tables or fields to your database).

 

  Back to the List of Articles