UserBase

Frequently Asked Questions

See also: Shared FAQ

How do I configure/customize UserBase?
How do I change UserBase's styling?
How do I use the /login shortcut URL?
How do I embed UserBase in another page, or within my site's existing layout?
How do I embed UserBase's sub-pages, such as the sign-up page?

I get an Internal Server Error!
I get an error saying "undefined function virtual" or "request execution failed."

Can you add feature XYZ to UserBase?
Can I put a small login form or "user $name logged in" message on every page?
Can I put just a login/logout link on every page?
Can I display the main menu for just a single group?
Can I get the logged-in username or other user info from PHP?
How do I password-protect my web pages?
I forgot my admin password or can't access my admin account.
How do groups work?
How do the paid accounts work?
How does UserBase's login redirection work?
How does UserBase store passwords?
How do I pass external data to UserBase?
How do I pass URL variables from php/shtml to UserBase?
UserBase (sometimes) says I'm not logged in, when I really am!

Does UserBase work with iWeb, or other 3rd-party website editors?
How do I integrate UserBase with WordPress?

How do I configure/customize UserBase?

Just use WebConfig: log into UserBase with your admin account, then go to the Settings page, and do all your configuration there, via web browser.  WebConfig is available in UserBase v3 and newer (get the latest version here).  In older versions, you configure the app by editing its prefs file (and you can still do this in newer versions if you prefer).  Here's how:

Edit your userbase_prefs.cgi file in a text editor.  This file is normally in your server's cgi-bin directory, or it may be in your login directory on Windows servers.  The prefs file contains many adjustable settings along with documentation for them.  You'll need to set the $PREF{database_*} settings right away, and you'll probably want to adjust the $PREF{webmaster_email_address} setting, for example.

You'll notice that many lines in the prefs file begin with a "#" character.  These lines are inactive "comment" lines containing instructions and examples, so don't change anything on them, because it won't have any effect on UserBase.  If you see a pref that you want to adjust, but it's on an inactive line, that usually means it's just an example included as part of the documentation, so you should look for another instance of that same pref on a line that doesn't begin with a "#" character – that will be the active version of the pref, so that's the one you should adjust.

How do I change UserBase's styling?

To customize the styling (look and feel), adjust the CSS code in the $PREF{css} setting.  To include an external CSS file, use a CSS @import statement:

Notice that the @-symbol on the @import statement must be escaped with a backslash, otherwise Perl will treat it as a variable, which will result in an error.

How do I use the /login shortcut URL?

On most servers, you can use www.yoursite.com/login instead of www.yoursite.com/cgi-bin/userbase.cgi to access UserBase.  But first, you must get the full userbase.cgi URL working.  Once that's working, you can try these shortcut URLs:

If one or both of those works, then delete the index file that doesn't work (if any), and then you should be able to use this shorter URL:

If neither index page works, then try www.yoursite.com/login/call_ub.php instead.  If that works, then edit the index.php file, remove the "#" from the front of the call_ub line, and add a "#" to the front of the virtual line.  Now www.yoursite.com/login/index.php should work, and if you delete the index.shtml file, then www.yoursite.com/login should work too.

If your server runs IIS rather than Apache, you can also use the Default Content Page feature to enable the shortcut URL.  Open your IIS manager, find the /login/ directory, right-click on it and choose Properties.  Go to the Documents tab, check the "Enable default content page" box, and add "userbase.cgi" to the top of the list.

If the short /login URL works on your server using one of the above methods, then set $PREF{login_url} to '/login/' in your prefs file.

If your server doesn't support any of the above methods, and you don't want to upgrade to a better hosting company, then you can use the not-quite-as-nice META Refresh method.  Copy the /login/index-redirect.html file to /login/index.html and then edit the index.html file.  In it, replace "mysite.com" with your domain name.  Now yoursite.com/login will auto-redirect your visitors to yoursite.com/cgi-bin/userbase.cgi.

How do I embed UserBase in another page, or within my site's existing layout?

Note: embedding puts the whole UserBase app into the page where you embed it.  If you just want a small login form to be embedded into your site's header, sidebar, etc, see this FAQ item instead.

Embedding Method A: call userbase.cgi from your PHP or SSI/shtml page:

1. First make sure UserBase is installed and working: visit yoursite.com/cgi-bin/userbase.cgi and you should see the login form.  If not, you need to fix that before trying to embed it.  Important note: if you install UserBase in a non-standard location (somewhere other than yoursite.com/cgi-bin/userbase.cgi), then you'll need to adjust the "/cgi-bin/userbase.cgi" throughout these instructions, to match wherever you've actually installed it.
2. Within the <head> section of the PHP or SSI/shtml page where you want to embed UserBase, add the following two lines:
   
   
   <script type="text/javascript" src="/login/appdata/ub.js"></script>
   
   <link rel="stylesheet" type="text/css" media="all" href="/login/appdata/ub.css" />
   
   If you're using an older version, you won't have the ub.js and ub.css files in the /login/appdata folder on your server, so you'll need to create them.
3. If your page is a PHP page, then add the following line to it wherever you want UserBase's output to appear:
   
   
   <?PHP virtual("/cgi-bin/userbase.cgi?encembed=yes&" . $_SERVER['QUERY_STRING']); ?>
   
   
   Or if your server doesn't support the PHP virtual() function, use this line instead:
   
   
   <?PHP require($_SERVER['DOCUMENT_ROOT'] . "/login/call_ub_embed.php"); ?>
   
   
   Or, if your page is a plain HTML page with an extension of .htm or .html, rename its extension to .shtml and then add the following line to it wherever you want UserBase's output to appear:
   
   
   <!--#include virtual="/cgi-bin/userbase.cgi?encembed=yes&$QUERY_STRING" -->
4. In your userbase_prefs.cgi file, set $PREF{login_url} = '/mypage.php' or '/mypage.shtml', where the value is the URL (starting with a slash) to the page within your website where you've embedded UserBase.
   
   Now visit www.yoursite.com/mypage.php (or shtml) and you'll see UserBase in the page.

Embedding Method B: call userbase.cgi directly, and let it display your HTML template file:

If your server doesn't support the PHP/SSI/shtml that's necessary for Embedding Method A (above), then you can use an HTML template file instead.  Your page will look exactly the same as with Method A; the difference is that Method B requires you to use the full URL to the CGI script itself, and not use the /login shortcut URL, since your server doesn't support any way to use that.

First you create an HTML file in whatever way you normally create web pages.  Name this file encodable_app_template.html.  In the <body> section of the file, wherever you want UserBase's output to go, put the string %%encodable_app_output%%.  Then upload this HTML file onto your website in its top level (i.e. not in a subfolder).

Now open your userbase_prefs.cgi file and find the $PREF{encodable_app_template_file} setting; set that to "%PREF{DOCROOT}/encodable_app_template.html";

Now visit www.yoursite.com/cgi-bin/userbase.cgi and it'll use your template file.

How do I embed UserBase's sub-pages, such as the sign-up page?

This happens automatically when you embed UserBase itself, because all of its sub-pages are accessed via URL variables (e.g. ?action=signup) on the end of your embedded page URL.  So by adjusting $PREF{login_url} as instructed in the embed FAQ, your sign-up page for example is no longer /cgi-bin/userbase.cgi?action=signup but is instead /mypage.php?action=signup -- it's embedded automatically because you embedded the whole app.  So there is no need to separately embed every individual sub-page; indeed that would be pretty difficult since there are dozens of them.

But if you insist on doing separate embeds (which is unnecessary in 99.9% of cases), you can do it by following the regular embed instructions for your additional URLs, and including the URL variables for that specific page (e.g. ?action=signup) within the call to virtual(), or by setting $custqs="action=signup"; in the PHP code before calling require().

I get an Internal Server Error!

If this happens after you edit your userbase.cgi file, then the simple solution is: don't change userbase.cgi at all.  Instead, only edit userbase_prefs.cgi, as explained above.

But if you haven't edited your userbase.cgi file and you still get an Internal Server Error, or if you absolutely need to edit userbase.cgi, then see the Internal Server Error page for solutions to this problem, which is most likely caused by an installation issue and not a problem with UserBase itself.

I get an error saying "undefined function virtual" or "request execution failed."

The "undefined function virtual" error means your server doesn't support PHP's virtual() function.  This is only a minor issue, and it is not a problem with UserBase itself.  It just means you need to use a different method for calling UserBase from a shortcut URL.  (See the shortcut FAQ item for more details and alternatives to the virtual() function, but read the rest of this FAQ item first.)

The "request execution failed" error most likely means that your userbase.cgi isn't installed quite right.

Either way, the first thing to do is get UserBase itself installed and working: visit www.yoursite.com/cgi-bin/userbase.cgi and make sure that works.  Only after that works properly should you try to get the shortcut URLs working (www.yoursite.com/login/ or www.yoursite.com/login/index.php or www.yoursite.com/login/index.shtml).  If your userbase.cgi gives you an Internal Server Error, it's most likely a chmod/permissions problem, but see this page for full details on how to fix it.

Can you add feature XYZ to UserBase?

Yes, we can usually add custom features to UserBase; just contact us and ask.

Can I put a small login form or "user $name logged in" message on every page?

Yes.  You just need to put one line of code into every page on your site where you want the login form / message to appear.  If your pages are .shtml pages, then use this line:

Or, if your pages are PHP pages, use this line instead:

For PHP pages on servers that don't support virtual(), use this:

To adjust the login form / message, adjust the $PREF{login_form_template__mini} and $PREF{mainmenu_template__mini} settings in your userbase_prefs.cgi file.

(Note that this is in addition to the call to userbase.cgi which you already have in your site's login page.)

Can I put just a login/logout link on every page?

Yes.  This will display either a "login" link or a "logout" link depending on whether the user viewing the page is currently logged in or not.  You just need to put one line of code into every page on your site where you want the link to appear.  If your pages are .shtml pages, then use this line:

Or, if your pages are .php pages, use this line instead:

For PHP pages on servers that don't support virtual(), use this:

To adjust the text of these two links, adjust the $PREF{login_logout_link_template___login} and $PREF{login_logout_link_template___logout} settings in your userbase_prefs.cgi file.

(Note that this is in addition to the call to userbase.cgi which you already have in your site's login page.)

Can I display the main menu for just a single group?

Yes: pass ?action=groupmenu&group=groupname on the URL, of course replacing "groupname" with the group name that you want.  You can also include &bare=true to get just the raw HTML, in case you want to totally change the way the menu is displayed.

Can I get the logged-in username or other user info from PHP?

Yes; the ubinfo.php file from the userbase.zip file shows how to do it.  Or you can call UserBase and pass ?action=chklogin if you want to parse the raw variables yourself, or from something other than PHP.

How do I password-protect my web pages?

See the instructions.

I forgot my admin password or can't access my admin account.

As the webmaster, with FTP/SSH access to the server, you can tell UserBase to create a new admin account.  Edit your userbase_prefs.cgi file and add this new line to the bottom of the file:

$PREF{allow_random_admin_account_creation} = 'yes';

Then visit yoursite.com/cgi-bin/userbase.cgi?createrandomadmin which will cause UserBase to create a new admin account with a randomly-chosen username and password.  The user/pass will be stored in a new text file on your server in your /cgi-bin/encdata/userbase/ directory.  Use those to login, then change the password on your original admin account (or create a new one).  Then delete the random admin account, and remove that new pref from your prefs file.

How do groups work?

UserBase has three built-in groups: public, member, and admin.  The public group includes all visitors, even ones without accounts.  The member group includes everyone with an account in UserBase.  And the admin group is for managing the application; admin has full access to everything.

The three built-in groups are used by UserBase for many internal functions and cannot be changed.  If you want to organize your users into different subsets, simply go to the Manage Groups page and create your own groups.  Users can belong to multiple groups at once (for example, all admins are also members).

Also, note that the mere presence of a given group -- for example, the public group -- does not give anyone access to anything.  You control access by adjusting the $PREF{groups_allowed_to_*} settings.  For example, $PREF{groups_allowed_to_change_profile_image} is set to 'member' by default, whereas $PREF{groups_allowed_to_manage_custom_fields} is set to 'admin'.

How do the paid accounts work?

In older versions of UserBase, set $PREF{enable_paid_accounts} to 'yes', and then set the various $PREF{paid_account_type_*} settings to specify your paid groups.  In newer versions, just go to the Manage Groups page, and while adding/editing a group, you'll see the "Price" field; by entering a price there, you make that group a paid group.

Your paid group(s) will then show up on the sign-up page for your visitors to select.  When a visitor submits the form, his account is created immediately, but it's in a pending state, where it cannot access any password-protected areas on your site.  UserBase then directs the user to PayPal to make the payment.  When he completes the payment, PayPal's server automatically notifies UserBase on your server, and only then does UserBase add the new account to the paid group.  If the user never completes the PayPal payment, then his account never becomes active, and UserBase will just keep showing him the "click here to pay" page that will send him to PayPal.

How does UserBase's login redirection work?

When a visitor logs in successfully, UserBase automatically sends him back to the page that he came from.  For example, if you have a page called "home.php" that contains a link to your UserBase login page, and a visitor clicks that link and logs in, UserBase will then send him back to home.php automatically.

On the other hand, if a visitor goes to your UserBase login page directly, rather than by following a link from another page, then upon successful login, UserBase will display its own Main Menu / Account Center page.

If you want to override this behavior and cause UserBase to always send your visitors to specific pages upon login, adjust the $PREF{on_member_login_redirect_to} setting (and/or the other similar settings) in your prefs file.

How does UserBase store passwords?

It doesn't.  For security purposes, UserBase only stores password hashes.  A hash function is a one-way operation that turns a block of text (a password in this case) into a specific corresponding fixed-length string, known as a hash.  A given password will always produce the same hash, but it is (for practical purposes) impossible to "decrypt" a hash back into the original password.  Instead, UserBase always hashes passwords as soon as it receives them, so when a user tries to log in, UserBase compares the hash from the entered password with the hash stored in the database for the account in question, and if they match then the login is allowed.

How do I pass external data to UserBase?

You can include external data within any of UserBase's $PREF settings by using the following syntax:

%COOKIE{cookie_name}
%URL{url_variable_name}
%ENV{environment_variable_name}
%SQL{{sql_select_statement_here}}
%PREF{other_pref_name_here}

For example, if you wanted to adjust UserBase's title by passing ?customtitle=MySpecialTitle on the URL, you would set the $PREF{title} setting like this:

Of course, your users can modify their URLs and even their cookie values, so you shouldn't use the URL nor cookies for passing any sensitive data.

To use environment variables to pass your own data from a PHP page to UserBase, you must call UserBase from your PHP page using the call_ub.php method as explained in the shortcut FAQ item.  Then in your PHP page, just before calling UserBase, use putenv() to set your variables.  On most servers the environment variable name that you create must start with "PHP", so for example:

<?php
// set your variable however you want to.
$somevar = what_ever();

// put your variable into an environment var.
putenv("PHP_SOMEVAR=$somevar");

require($_SERVER['DOCUMENT_ROOT'] . "/login/call_ub.php");
?>

Then in your userbase_prefs.cgi file, in whichever $PREF you're adjusting, you would use %ENV{PHP_SOMEVAR} to get the value of that variable.

How do I pass URL variables from php/shtml to UserBase?

If you're calling UserBase from within a PHP or SSI/shtml page, whether it's a shortcut or an embed, any query-string variables that you specify on the URL after your page's filename will automatically be passed on to userbase.cgi.  But if you want to hard-code some particular URL variables, you can do that too.  For SSI/shtml pages, just include the variables right after the CGI script name:

For PHP pages using virtual() it's much the same:

For PHP pages using call_ub.php, do the following:

UserBase (sometimes) says I'm not logged in, when I really am!

When this happens, it's often in response to having clicked on a link within a notification email.  It's usually caused by the URL either having, or not having, the "www." in front of your domain name.  Try adding or removing the "www." and see if that fixes things.

The root cause of this problem is the way that web browsers handle cookies.  A cookie set by http://yoursite.com/ cannot be read by http://www.yoursite.com/ and vice-versa, because technically those are different domains for security purposes.  There's no way for an application like UserBase to override this security setting and read the other domain's cookies.

Instead, to fix the problem, you need to configure your website itself to pick one form and stick to it: either always use http://yoursite.com/ without the "www.", or else always use http://www.yoursite.com/ with the "www."  Then if someone visits the "wrong" one, the website will automatically and transparently send the visitor to the "right" one.  To do this, check with your hosting company's control panel; Dreamhost for example has a simple setting for this that you can toggle.  If your hosting company doesn't, and your website runs Apache, then you can add a few lines to your main .htaccess file to make it happen:

# Use this to automatically redirect
# www.you.com to just you.com:
#
RewriteEngine On
RewriteCond %{HTTP_HOST}   ^www\.you\.com [NC]
RewriteRule (.*)           http://you.com/$1 [L,R]

# Or, use this to automatically redirect
# you.com to www.you.com:
#
RewriteEngine On
RewriteCond %{HTTP_HOST}   ^you\.com [NC]
RewriteRule (.*)           http://www.you.com/$1 [L,R]

If you use this code, you don't need to go back into your individual pages and update your links to add/remove the "www." on each one.  The .htaccess code will automatically do that for you, whenever someone visits the wrong domain.  And it will keep the rest of the request intact, so even if the link is a long URL to some page deep within your site, that's no problem: it'll just add or remove the "www." and leave the rest of the URL unchanged.

Does UserBase work with iWeb, or other 3rd-party website editors?

UserBase works fine on websites created with 3rd-party tools like iWeb, as long as the server itself is a standard kind of server supporting standard features (namely Perl CGI scripts and MySQL).  Because UserBase is a web application, not simply a web page, it's not created nor edited via iWeb, but it can be embedded into any of your iWeb pages, so that it appears within your own layout, and thus matches the style of the rest of your site.  Similarly, you would not need to use iWeb to configure UserBase, because all configuration is handled by simply editing the userbase_prefs.cgi file, which is a plain text file that can be edited in any text editor.

UserBase can also password-protect your webpages, regardless of how they're created (via iWeb or any other tool), as long as the pages, once created, are standard pages that you can edit as you wish.

How do I integrate UserBase with WordPress?

To embed UserBase within a WordPress page, use the WordPress web-based page editor to add the following line to the page:

Next, still in the WordPress web interface, go to the Plugins page, and look for one called "PHP Execution" or similar, and enable it.

Now you'll need to add UserBase's Javascript and style to your page, by putting the 2 lines below into your page's head section.  You can use a WordPress plugin like "Per page add to head" for this.  Or you can do it manually, by editing the file wp-content/themes/<themename>/header.php (via Appearance -> Editor in WordPress) and adding the following 2 lines to the page's <head> section:

Or if you only want those lines to load on the specific page where you've embedded UserBase, for example www.yoursite.com/pages/login/ , then wrap them in a PHP if/endif:

Finally, in your userbase_prefs.cgi file, set $PREF{login_url} to '/pages/login/' or whatever the URL is for the page where you've embedded UserBase.

And if you want to use UserBase to password-protect some of your WordPress pages, and you also have caching enabled in WordPress, you'll need to go into the WordPress settings for the cache, and add your protected pages to the "exclude" list, so that they are not cached.

Some WordPress installations have a bad habit of inserting random <br /> and <p> tags all over your pages, which can break UserBase's output.  To fix this, install a WordPress plugin like "Toggle wpautop" or "wpautop control"; these allow you to disable the "wpautop" behavior on a per-page basis, so you can disable it on just your UserBase page.

Shopping Cart