Writing a Basic Plugin

These are the basic steps for creating a plugin.

Step 1. Decide if you really need to create a plugin

A widget, custom function, or custom page might be a better choice.  Feel free to check out the UserSpice Customization Guide for some of the options to customize UserSpice. The main reasons to create a plugin are for code-re-usability, code sharing, and things that need to be used across all UserSpice pages.  If you only want to take advantage of the "hooks" features that plugins have, you can use the "Hooker" plugin to access these features without creating a whole plugin.

Step 2.  Use the Demo Plugin

Download the "demo" plugin from Spice Shaker and copy it to another folder inside the usersc/plugins folder.  The folder should be lowercase and unique.  This is your "reserved name" and it will be used throughout the project.

Step 3. Do some initial setup

In your new plugin folder, open up info.xml and update it with your own information.  If you are going to have a "control panel/configure" page for your plugin, put the name of that page between the "button" tags.  Otherwise, leave it blank.  If it is not blank, your plugin's config page will show up under the "Addons" menu on the Dashboard.

Step 4. Understanding the folders

You may not need to use any of the folders inside the demo plugin, but here's their purpose.

assets – this is where you store files that are going to be used in the regular use of your plugin. For instance, if you have javascript, css, or other php pages, put them in here.

files – This is generally where you store files that need to be copied during install.  Sometimes it may make sense to copy a file to users/views so you can add another view to the dashboard. That sort of thing goes here.

hooks – this is where you store your hook files if you're using the plugin hooks feature (see below).

Step 5.  Install, Uninstall, Activate, Update

If you want to use plugin hooks or your own database tables your project, you will set that up in install.php.  We recommend you do that somewhere around line 32.  You are welcome to use the existing tables in UserSpice.  Depending on your plugin, it may make sense to add a few columns to the users or settings table.  We strongly recommend that you begin your column names with plg_ to make it clear that those columns are coming from a plugin.  If you're adding an exempt column and your plugin is called logger, you may even want to do something like plg_logger_exempt just to make it really clear what that data is referencing.  An example query would be…

$db->query("ALTER TABLE settings ADD COLUMN plg_sl_guest tinyint(1) DEFAULT 0");

To create an entire table, your query would look like…

$db->query("CREATE TABLE us_plugin_hooks (
  id int(11) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
  page varchar(255) NOT NULL,
  folder varchar(255) NOT NULL,
  position varchar(255) NOT NULL,
  hook varchar(255) NOT NULL,
  disabled tinyint(1) DEFAULT 0
)");

Most people do not need to touch the activate.php or uninstall.php files. Plugin hooks are turned off and unregistered automatically during uninstall.  One thing to consider is if you want to delete the tables/columns you added when someone uninstalls the plugin. Think very carefully about this.  There may be reasons someone wants the data created by the plugin even after it is uninstalled.  Sometimes they're even just "reinstalling" and don't want to lose their data.   Either way, if something needs to happen during that step, feel free to edit those files.

Step 6. Update

Newer versions of UserSpice have the ability to update themselves. For now, the better way to do this is to uninstall/reinstall.  More instructions will be here as we update that logic.

Step 7. Configure

The configure.php file is the default control panel for your plugin. Note, if you use additional files, it is VERY important that they cannot be accessed by navigating directly to the plugin folder.  One way to achieve this is to "include" them in configure.php and give those files the same snippet

<?php if(count(get_included_files()) ==1) die(); //Direct Access Not Permitted ?>

that plugin hooks have.

Step 8. Functions,  Header, Footer

When your plugin is active, these files will be included in every UserSpice page load, so it's really important that you take care when coding these. Functions is for storing your custom functions. Header and footer add to those respective locations.

Step 9. Logo

Add a fun icon to your project by putting a 200×200 clear png icon in the root folder of your plugin and calling it logo.png

Step 10. Sharing  Your Plugin

You can share your plugin with the world outside of Spice Shaker by going to https://bugs.userspice.com and adding it to your account page.  To get your plugin in Spice Shaker, please contact the developers on Discord.