UserBase

Frequently Asked Questions


How do I customize UserBase?
I get an Internal Server Error after I edit userbase.cgi!
How do I embed UserBase in another page, or within my site's existing layout?
I get an error when I try to call UserBase from PHP using virtual().
Can I put a small login form or "user $name logged in" message on every page?
UserBase (sometimes) says I'm not logged in, when I really am!

 

How do I customize UserBase?

Just edit userbase_prefs.cgi in a text editor; it contains many adjustable settings.  You'll probably want to adjust the $PREF{title_*} settings and $PREF{webmaster_email_address} right away, for example.

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

$PREF{css} = qq`

\@import url("/mystylesheet.css");

[rest of UserBase's CSS here]

`;

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.

 

I get an Internal Server Error after I edit userbase.cgi!

The simple solution is: don't change userbase.cgi at all.  Instead, only edit userbase_prefs.cgi, as explained above.

The long answer is that many text editors mess up the line-endings in text files in ways that don't show up within the editor itself, so you don't notice them until you try to execute the file as a script on a server that requires proper line endings.  Editors that are known to mess up the line endings are Word, Notepad, GoLive, Dreamweaver, etc.; one editor that's known to handle the line endings properly is WordPad.  So if you must edit userbase.cgi, first make a backup copy of it, and then try using WordPad.  Of course, if you run Linux or Mac OS X, most editors will handle the line endings properly; it's Windows that messes everything up, as usual.

 

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

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

  1. Within the <head> section of the PHP or SSI/shtml page where you want to embed UserBase, add the following lines:

    <script type="text/javascript" src="/cgi-bin/userbase.cgi?js"></script>

    <link rel="stylesheet" type="text/css" media="all" href="/cgi-bin/userbase.cgi?css" />
  2. 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?" . $_SERVER['QUERY_STRING']); ?>


    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?$QUERY_STRING" -->
  3. In your userbase_prefs.cgi file, set $PREF{print_full_html_tags} = 'no'.  Then set $PREF{login_url} = '/mypage.php' or '/mypage.shtml' where 'mypage' is the name of the page where you've embedded it.

    Now visit www.yoursite.com/mypage.php (or shtml) and you'll see UserBase in the page.

    See step #5 of the installation instructions for more details on calling UserBase from another 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, since your server doesn't support any other way.

First you create an HTML file in whatever way you normally create web pages.  Name this file encodable_app_template.html.  In the <head> section of this file, put the strings %%css%% and %%js%% each on their own line.  Then in the <body> section of the file, wherever you want UserBase's output to go, put the string %%encodable_app_output%%.  Now 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{print_full_html_tags} setting and set it to "no".  Near there, you'll also 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.

 

I get an error when I try to call UserBase from PHP using virtual().

If you get an error saying "call to undefined function virtual()" then that means your server doesn't support PHP's virtual() function.  That's OK; you just need to try one of the other methods for calling UserBase, as explained in step #5 of the instructions.

 

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 PHP pages, then use this line:

<?PHP virtual("/cgi-bin/userbase.cgi?format=mini"); ?>

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

<!--#include virtual="/cgi-bin/userbase.cgi?format=mini" -->

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.)

 

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.