General Documentation

This page is intended to be a supplement to existing forms of documentation. There have been a number of new features and additions that warrant a description of how to use them appropriately.

Anchor File z_us_root.php

One of the changes made during UserSpice 4.1 development was the addition of a file in the UserSpice root called z_us_root.php. It acts as an “anchor” for the root of the UserSpice installation so that each page can locate itself absolutely and relatively using the variables $us_url_root (the URL root path of the UserSpice installation) and $abs_us_root (the absolute file path to the UserSpice installation, used most often for PHP includes or requires).

The $path variable is the only user modified value in this file. This variable is an array of strings, where each string is a path (relative to the UserSpice installation root) that will be indexed when visiting the Page Permissions (admin_pages.php) portion of the Admin dashboard. Below is a description of each of the default paths:

• ”: This is an empty string signifying that it refers to the UserSpice root folder
• ‘users/’: This is the location of the core UserSpice files. All core functionality of UserSpice is determined by the files in this path. As such, where possible, it is strongly recommended that these files not get modified directly
• ‘usersc/’: This is the intended location for user customised files for UserSpice. As will be shown later, built in UserSpice files can be overridden by files in this folder if certain requirements are followed. Other installation customisation are also generally included in this location

When modifying the $path variable, be sure to enclose the string in single quotes (‘) with no white-space in this variable. To add another folder for indexing, simply at the directory (relative to the UserSpice installation root) and be sure to include the final ‘/’.

File users/init.php

This file is created (or more specifically, completed) during the UserSpice installation. Prior to completing the installation, this file will look incomplete and PHP will be unable to parse it correctly. If immediately after the installation you get an error message, it could be due to the UserSpice installer not having write permissions for this file location. After this file is completed, this file contains a few core functionalities that are required for each UserSpice (and most custom pages) page prior to other elements of each page being loaded (think of it as a “boot loader”). As such, this file must always be correctly and specifically referenced in each file it is used. This is in contrast to other files referenced by init.php which all make use of $abs_us_root and $us_url_root to automatically locate where they are.

At the beginning of this file, In UserSpice core files, you will notice the following PHP code:

$abs_us_root=$_SERVER['DOCUMENT_ROOT'];

$self_path=explode("/", $_SERVER['PHP_SELF']);
$self_path_length=count($self_path);
$file_found=FALSE;

for($i = 1; $i < $self_path_length; $i++){
	array_splice($self_path, $self_path_length-$i, $i);
	$us_url_root=implode("/",$self_path)."/";

	if (file_exists($abs_us_root.$us_url_root.'z_us_root.php')){
		$file_found=TRUE;
		break;
	}else{
		$file_found=FALSE;
	}
}

This code first defines the $abs_us_root variable which is the absolute file path to the UserSpice installation, used most often for PHP includes or requires. The for loop then searches from the page current directory, stripping off one level of hierarchy per loop until it finds the z_us_root.php file. When it finds the file, it stops and establishes this path as $us_url_root, which will define the installation path of UserSpice relative to the website file root.

The rest of this file contains many ‘requires’ necessary for each page (most importantly, the UserSpice classes) as well as many variables defined for use on each page.

Variable $us_url_root

If you install userspice inside a sub-folder, you can use this variable to preface any URLs you write or need to determine, so the code does not break if you move the UserSpice installation. This variable is very useful when you want to reuse the came code which exists or is called from different folders. This will always ensure the UserSpice installation path is correctly detected.

Variable $abs_us_root

The most common use of this file is when it is, concatenated with $us_url_root (i.e. $abs_us_root.$us_url_root) since it can be used for PHP file includes/requires. Again, it is also very useful when you need to include the same file in code which exists in different folders. This will ensure your includes/requires do not break if you move the calling file around.

Header Tags (for Facebook or other uses)

Located at usersc/includes/head_tags.php, this contents of this file are included in the <head></head> section of the generated page (the same <head> contents will be used on all pages). One example of using this section would be to modify the <meta> tags which Facebook uses when scraping  a page for sharing. The most relevant tags for Facebook are included, but should be edited for your specific information. You can see how these <meta> tags alter the Facebook scraper by entering your page URL at the Facebook for Developers Object Debugger.

<!-- Facebook sharing meta tags (delete if you don't want them) -->
<meta property="og:url" content="" /> <!-- URL for website (link address) -->
<meta property="og:type" content="website" /> <!-- type of site -->
<meta property="og:title" content="Userspice Site" /> <!-- title of site (title of share) -->
<meta property="og:description" content="Userspice Site Description" /> <!-- description of site (text which appears when sharing) -->
<meta property="og:image" content="" /> <!-- URL for preview image -->

Navigation

The UserSpice core navigation menu (for main user or admin links for example) is located at users/includes/navigation.php. This file contains the core menus and some logic for displaying appropriate menus and links for each user. This menu by default makes use of the navbar-right Bootstrap class to push the navigation items to the right. There is also some logic used for modifying the contents of the “hamburger menu”…this is the menu used on small screens.

Ideally, this core navigation file should remain untouched, and instead the file usersc/includes/navigation.php should be modified instead. By default, a Home icon/navlink is included, which can be commented out or entirely removed. Examples of dropdown links are also included. This file makes use of the navbar-left Bootstrap class to push the items in this file to the left. By changing this to navbar-right, the new menu items may be pushed to the right so they are immediately next to the core UserSpice navigation items.

Admin Panel

To integrate your own control functionality into the UserSpice admin panel, you can do so simply by copying the panel code from admin.php and placing it into usersc/includes/admin_panels.php

Registration User Agreement

Most people are familiar with the various agreements you must read and acknowledge when using software, registering on a forum, etc. UserSpice includes this funtionality by default during signup, and the text used for the agreement is found at usersc/includes/user_agreement.php. The text included is strictly sample text and should be modified to suit your website requirements. Users must check a box to agree to the terms when registering.

Custom Login Script

During the login sequence, you may customise or add any additional steps by modifying usersc/scripts/custom_login_script.php. Any code inserted here is executed before the login process is completed. One example of usage may be to use $_SESSION variables to further customise the user experience.

Custom Logout Script

Similar to the login script, the logout script provides space, both before and after the logout process to perform any cleanup required. One example continued from the previous section would be unsetting $_SESSION variables, or modify the redirection after logout.

Custom CSS Files

UserSpice is built on top of Twitters Bootstrap. This means that the core CSS used for building the UserSpice layout has already been tested in detail and contains a number of inter-dependencies. As a result, modifying the Bootstrap CSS files directly would be difficult, and may have other ramifications, along with making updates difficult. There are three layers of CSS that are applied to UserSpice:

1. Bootstrap core…these are the files used for core layout functionality, as well as some Javascript. Several color themes have been included which are based on the Bootstrap core
2. sb-admin…this is an admin CSS template used to add or override some limited Bootstrap functionality
3. custom.css…this is where any user customizations should go, and is located at usersc/css/*. Multiple CSS files can be present here, but UserSpice is only designed to accept only one additional CSS file.

The benefit of the third CSS file is that it would keep any user customizations outside of the core UserSpice code. This makes updates easier an defines a clear separation between the core code and any customised code. In general, since it is loaded last, the code in custom.css can be used to overwrite most of the UserSpice styling. If something does not appear to be changing, it is possible that the previous CSS styling makes use of the !important tag. If this is used, then you will need to tag your own CSS code with the !important tag after carefully considering the consequences of doing so. It is often quite useful to Google the CSS you are curious about, since many other people likely had the issues you are having.