The usersc folder serves a bunch of purposes that may not be obvious, so we'd like to take a few moments to lay out what it does and does not do.

It's the home for (most) addons

UserSpice defines addons as Language Packs, Widgets,  Plugins and Templates and all but Language Packs are stored in usersc.

Language packs are stored in users/lang

Widgets are in usersc/widgets

Plugins are in usersc/plugins

Templates are in usersc/templates

Editing Addons (Except Language)

Although addons are located in the usersc directory, they are not meant to be edited directly. If you want to modify one of the UserSpice addons, the proper way to do that is to copy the addon to another folder.  For instance, if you want to modify the standard template, you will copy the

usersc/templates/standard folder

to

usersc/templates/your_name_here

and edit away. This prevents our updates from breaking your modifications.  The same holds true for widgets and plugins.

Editing Language

If you don't like the way something is translated, you can override that in usersc.  Let's say that you want to override Italian (users/lang/it-IT.php).  You can create a file called usersc/lang/it-IT.php and override language keys in there.  The format looks like this.

<?php 
$lang = array_merge($lang, array(
    "DAT_SEARCH" 		=> "Your translation here",
    "DAT_FIRST" 		=> "Your translation here",
));

Overriding Core UserSpice Files

This used to be the most common use for usersc, but let's say that you want to completely override one of the "core" UserSpice php files that is located in the actual /users folder. Something like account.php.  You can copy

users/account.php

to

usersc/account.php

and your file will load instead of ours.   Please note, there is a whole other guide for customizing the dashboard using usersc.

Pro Tip

When you're poking around and considering customizing our files, do a search of the file for the term "usersc".  You will often find that there are optional files that can be created/edited in the usersc folder that will allow you to override/insert something in one of our files without forcing you to maintain a completely separate page.

Usersc Includes

The usersc/includes folder contains some things that you may  want to modify.

1. analytics.php – Paste your Google analytics or other tracking code here and it will be loaded on every page automatically.
2. custom_functions.php – Store your custom functions here and they will be available everywhere.
3. database_navigation_hooks_dropdown.php – Allows you to put special codes like {{myCustom}} in menus to make them dynamic
4. database_navigation_hooks.php – Same as above but for non-dropdown navigation links
5. footer.php – Load code on the footer of every page
6. head_tags.php – This is a perfect place to put something that needs to be at the top of every page.
7. oauth_success_redirect.php – If you want to do something after someone logs in with oAuth, put that code here.
8. security_headers.php – Set your php headers here
9. user_agreement.php – Customize your user_agreement here.

Usersc Scripts

The usersc/scripts folder contains some things that you may  want to modify.

1. additional_join_form_fields.php  – Allows you to add more form fields to the UserSpice join form.
2. during_user_creation.php – This is where you process the form fields for #1 AND do any other things you want to do every time a new user is created.
3. banned.php – Set a message what someone sees when they are banned from your site.
4. custom_login_script_no_redir.php – This script runs every time someone logs in if you want to perform any tasks on login. Do not put redirects in here.
5. custom_login_script.php – If you want to redirect people on login, you can do so here. This is a good place if you want different users to go different places.
6. did_not_have_permission.php – This script runs every time someone tries to visit a page they do not have permission to visit.
7. just_after_logout.php – Do some maintenance after someone visits users/logout.php.
8. just_before_logout.php – Do some maintenance before someone is logged out after visiting users/logout.php.
9. not_logged_in.php – This script is run when a user who is not logged in tries to visit a page that requires a logged in user.
10. token_error.php – This is the error displayed if the form token check fails.

What are templates?

Templates control the look and feel of the front end of your UserSpice project.  Although the default UserSpice templates use Bootstrap 4, one of the beautiful things about UserSpice is that you can build your PHP pages however you like using any css framework or no css framework.  You can use jQuery or not use it.  It's your project and you can design it however you want.

Installing Templates

Spice Shaker is the preferred way to install official and curated community templates.  Simply go to Spice Shaker, select Templates (and hit Go) and you will get a list of templates that can be easily installed.  Please note that installing a template is not the same as activating it.  You must go to Tools->Templates and click the Activate button to activate your template. Most templates also have a preview option.

Manually Installing Templates

If you do not want to or cannot use Spice Shaker, you can still view the raw template files and download template zips at our UserSpice Template List. Download your zip and unzip it to usersc/templates.  Then go to Tools->Templates and click the Activate button to activate your template.

Deleting Templates

Please make sure you have a new template active before deleting a template.  Otherwise, UserSpice will try to reactivate the "Standard" template. If Standard is missing, it will try to activate another template (in ABC order). If it cannot find a template, your site will not load.  Once you are sure you have a new template active, simply delete that template's folder in usersc/templates/your_template_name.

Using a Template on Only One Page

Set a variable

$template_override = 'citrus';

above the line for requiring init.php to call the 'citrus' template on that one page. The word in quotes is the folder name in usersc/templates of the template you want to use.

Creating Your Own Template

It is not a good idea to directly edit UserSpice templates.  Depending on what you want to accomplish, one of the solutions in the Customizing UserSpice Guide may be a better option. If you need something that loads every page (like a function or CSS override), usersc/includes/head_tags.php or usersc/includes/custom_functions.php might be a better choice.

If that doesn't work, feel free to copy any template that is close to what you want into a new folder in usersc/templates and edit away.  We even have a template called "nocss" that has no CSS in it, so you can start from scratch.

One of the hardest parts about creating your own template is dealing with navigation. You might find it easier to use file based navigation (i.e. hard coded) navigation instead of database-driven navigation in your custom template.

The file structure of a template is pretty self-explanatory. Headers, footers. Stuff like that.  The "assets" folder is where we store all the CSS/JS/Navigation stuff.

Spice Shaker is the preferred way to install official and curated community developed add-ons to your UserSpice project.

API Key

Spice Shaker requires a free API key.  Register for a free account at https://bugs.userspice.com and get your API Key from your account page.  Paste this API key in Spice Shaker on the dashboard and refresh the page. In addition to Spice Shaker, it will also allow you to fill out bug reports from your dashboard and even use our built in Auto Updater (New in UserSpice 5.0.4).   One key can be used in all your UserSpice installs and did we mention…it's free?

What it does

Spice shaker installs and updates.

Language Packs – Download additional front end translations for UserSpice

Widgets – UserSpice Dashboard Addons

Plugins – Add additional features such as Social Logins, Form Builders, and Credit Card processing to your UserSpice.

Templates – Change the look and feel of UserSpice with one click.

Updating

Addons that are already installed can be updated by searching for them and clicking the update button.

Spice Shaker Problems

Having problems? Check out our guide to Spice Shaker Problems.

Customizing the Dashboard

Spice Shaker (UserSpice Addon Installer)

Installing and Creating Templates

Understanding the usersc folder

Widgets

Those little charts/tables on the home page of your UserSpice dashboard are actually individual php files called widgets.  You can get more of them from Spice Shaker.  Don't like the order they're in? Just rename the folder of the widget itself in usersc/widgets because they load in ABC order.  Want to create your own? Copy any widget folder and edit away using the existing widget as a template!  Super simple.

Additional Menu Items

If you would like to add other menu items to the Dashboard menu, create a file in usersc/includes/ called admin_menu.php and edit it. You can add additional links in the format

<a href="proxy.php?url=<?=$us_url_root?>index.php"><i class="menu-icon fa fa-home"></i>Visit Homepage</a>

and they will show up on the dashboard menu.

Additional Views

If you notice, when you view the menu links in the dashboard, they're usually something along the lines of admin.php?view=plugins.

You can add additional view files to the users/views file and load them.  It is recommended that you create them by copying the file users/views/_aaaa_master_view_template.php to users/views/_whatever_you_want.php

Then you can call this view by just doing view=_whatever_you_want

Note that you can test that this works on the existing template by visiting admin.php?view=_aaaa_master_view_template and you will see that the blank template loads.

Overriding Our Views

What if you don't like our view=admin_users?  Should you edit it? No. Why? Because our updates may overwrite your changes.  Never fear. There's a way around this.  Copy users/views/_admin_users.php to usersc/includes/admin/_admin_users.php and then you can edit to your heart's content.  Your view will be loaded instead of ours.  Keep an eye on updates to see when we add features to the old view and you can incorporate those in your custom view.

Dashboard Access

Put simply, the Dashboard is designed for people that you absolutely 100% trust.  It is not made for "public" access. However, in big projects, you might need to allow someone access to part of the dashboard without giving access to all of it.  In this case, you may want to consider using the Settings->Dashboard Access feature to allow partial dashboard access.

Admin vs Master Account

Please note: Even if you give "admin" access to a user, there are still certain things they cannot do in the Dashboard and they may find themselves redirected to the Dashboard home screen and not really understand why.  This is because, by default, only user #1 has Master Account access. Please check out our article on master accounts to understand this better.

Pro Tip

When you're poking around and considering customizing our files, do a search of the file for the term "usersc".  You will often find that there are optional files that can be created/edited in the usersc folder that will allow you to override/insert something in one of our files without forcing you to maintain a completely separate page.

Spice Shaker doesn't work on WAMP
-Download ca-bundle.crt from https://github.com/bagder/ca-bundle/blob/e9175fec5d0c4d42de24ed6d84a06d504d5e5a09/ca-bundle.crt
-Put the file in c:\wamp64\
-Change php.ini to the following

curl.cainfo="C:/wamp64/ca-bundle.crt"
openssl.cafile="C:/wamp64/ca-bundle.crt"
Uncomment extension=php_curl.dll in php.ini

Issue: Curl is not enabled
– Edit php.ini (You can find the link to your proper php.ini file on the UserSpice Dashboard Snapshot
Remove the ; before ;extension=curl
Restart Apache/FPM

Issue: Curl not installed
– Install it. On Debian/Ubuntu that's
sudo apt-get install php-curl
sudo service apache2 restart

Cannot write to users/parsers
– Make sure you own them
In Debian/Ubuntu this is most likely
sudo chown -R www-data:www-data /var/www

So what is Master Account?
Master Account is reserved for things that could impact the security of your site or cause other types of abuse. These include (but aren't limited to) installing plugins, themes, widgets, filling out bug reports, and doing backups (which would allow someone to fully download your source code and database). Some plugins (such as the database and file manager) are also master account only.

How do I give someone a Master Account?
Simple. Go to users/init.php and add their user id to the $master_account array.

Why is it done this way?
There is a concept in hacking called "escalation of privilege." The idea is that you can chain a whole bunch of hacks together to gain additional permissions to perform bigger and bigger hacks. While there has never been a demonstrated case of someone being able to promote themselves from "User" to "Admin" in UserSpice, we have taken the stand for years that we wanted to protect your project's most valuable secrets in case it ever happened. This is primarily your source code and direct access to the database. This is why you must physically change the init.php file to escalate someone to Master Account. The idea is that if someone has the ability to edit your init.php file, it is game over from a security perspective anyway.

Debugging
A quick way to know that you're an admin without Master Account is that you click something in the back end and find yourself redirected to the dashboard.

To get a UserSpice API Key,

1. Visit https://bugs.userspice.com
2. Sign up or login
3. Click your username on the upper right corner.
4. Click Account.
5. If you don't have one, click Generate New Developer Key
6. Copy your key
7. v5.0.5 or later  – Store your key on the General Settings section of the dashboard.
8. v5.0.4 or earlier – Store your key in any of the plugins/resources that ask for your API key. If you put it one place, it will be available anywhere in UserSpice.

usersc/includes/head_tags.php file.

<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">