8.3. User Database Functions
The user database features are implemented as a series of functions attached to the userdb tag. The functions are:
login
-
Active parameters: username, password, crypt, md5, pass_field, ignore_case, indirect_login
Log in to Interchange. By default, the username is contained in the form variable mv_username and the password in mv_password. If the login is successful, the session value username ([data session username]) will be set to the user name. If indirect_login is used, it should be set to a field name which can be used as a lookup for the real username. This also causes a new_account operation to create a user account based on an assigned username, and assign_username should always be set when using indirect login.
This will recall the values of all non-special fields in the user database and place them in their corresponding user form variables.
The CookieLogin directive (catalog.cfg) allows users to save their username/password in a cookie. Expiration time is set by SaveExpire, renewed every time they log in. To cause the cookie to be generated originally, the form variable mv_cookie_password or mv_cookie_username must be set in the login form. The former causes both username and password to be saved, the latter just the username.
logout
-
Log out of Interchange. No additional parameters are needed.
new_account
-
Active parameters: username, password, verify, assign_username, username_mask, ignore_case,indirect_login
Create a new account. It requires the username, password, and verify parameters, which are by default contained in the form variables mv_username, mv_password, mv_verify respectively.
If the assign_username parameter is set, UserDB will assign a sequential username. The counter parameter can be used to set the filename (must be absolute), or the default of CATALOG_DIR/etc/username.counter can be accepted. The first username will be "U0001" if the counter doesn't exist already.
If assign_username is used, you can choose to have a pseudo-username that is different from the real username. (Email address is commonly used.) The field name is contained in the indirect_login parameter. When the user logs in this field name will also be used to find the real username. The value must be unique in the database or a "user already exists" error will be thrown.
The ignore_case parameter forces the username and password to lower case in the database, in effect rendering the username and password case-insensitive. This is recommended if using email address as a login.
If username_mask is set to a valid Perl regular expression (without the surrounding / /), then any username containing a matching string will not be allowed for use. For example, to screen out order numbers from being used by a random user:
[userdb function=new_account username_mask="^[A-Z]*[0-9]" ]
-
The CookieLogin directive (catalog.cfg) allows users to save their username/password in a cookie. Expiration time is set by SaveExpire, renewed every time they log in. To cause the cookie to be generated originally, the form variable mv_cookie_password or mv_cookie_username must be set in the login form. The former causes both username and password to be saved, the latter just the username.
To automatically create an account for every order, set the following in the OrderReport file:
[userdb function=new_account username="[value mv_order_number]" password="[value zip]" verify="[value zip]" database="orders" ]
-
This would be coupled with a login form that asks for order number and zip code, thereupon allowing the display of the contents of a transaction database with (presumably updated) order status information or a shipping company tracking number.
change_pass
-
Active parameters: username, password, verify, oldpass
Change the password on the currently logged-in account. It requires the username, password, verify, and oldpass parameters, which are by default contained in the form variables mv_username, mv_password, mv_verify, mv_password_old respectively.
set_shipping
-
Active parameters: nickname, shipping, ship_field
Place an entry in the shipping Address book. For example:
[userdb function=set_shipping nickname=Dad]
-
See Address Book below.
get_shipping
-
Active parameters: nickname, shipping, ship_field
Recall an entry from the shipping Address book. For example:
[userdb function=get_shipping nickname=Dad]
-
See Address Book below.
get_shipping_names
-
Active parameters: ship_field
Gets the names of shipping address book entries and places them in the variable address_book. By default, it does not return the values. To have the values returned, set the parameter show to 1, as in:
[set name=shipping_nicknames interpolate=1] [userdb function=get_shipping_names show=1] [/set]
set_billing
-
Active parameters: nickname, billing, bill_field
Place an entry in the billing accounts book. For example:
[userdb function=set_billing nickname=discover]
-
See Accounts Book below.
get_billing
-
Active parameters: nickname, billing, bill_field
Recall an entry from the billing accounts book. For example:
[userdb function=get_billing nickname=visa]
-
See Accounts Book below.
save
-
Saves all non-special form values that have columns in the user database. If a field is defined as scratch, it retrieves the field from the Scratch storage area; otherwise from Values. If the field is one of the outboard fields, it will save it in the outboard table with the value of outboard_key_col as the key.
set_cart
-
Save the contents of a shopping cart.
[userdb function=set_cart nickname=christmas]
-
See Carts below.
get_cart
-
Active parameters: nickname, carts_field, target
Recall a saved shopping cart.
[userdb function=get_cart nickname=mom_birthday]
-
Setting target saves to a different shopping cart than the default main cart. The carts_field controls the database field used for storage.
set_acl
-
Active parameters: location, acl_field, delete
Set a simple acl. For example:
[userdb function=set_acl location=cartcfg/editcart]
-
This allows the current user to access the page "cartcfg/editcart" if it is access-protected.
To delete access, do:
[userdb function=set_acl location=cartcfg/editcart delete=1]
-
To display the setting at the same time as setting, use the show attribute:
[userdb function=set_acl location=cartcf/editcart show=1]
check_acl
-
Active parameters: location, acl_field
Checks the simple access control listing for a location, returning 1 if allowed and the empty string if not allowed.
[if type=explicit compare="[userdb function=check_acl location=cartcfg/editcart]" ] [page cartcfg/editcart]Edit your cart configuration</a> [/if]
set_file_acl, set_db_acl
-
Active parameters: location, mode, db_acl_field, file_acl_field, delete
Sets a complex access control value. Takes the form:
[userdb function=set_file_acl mode=rw location=products/inventory.txt]
-
where mode is any value to be checked with check_file_acl. As with the simple ACL, use delete=1 to delete the location entirely.
check_file_acl, check_db_acl
-
Active parameters: location, mode, db_acl_field, file_acl_field
Checks a complex access control value and returns a true/false (1/0) value. Takes the form:
[userdb function=check_db_acl mode=w location=inventory]
-
where mode is any value to be checked with check_file_acl. It will return true, if the mode string is contained within the entry for that location. For example:
[if type=explicit compare="[userdb function=check_db_acl mode=w location=inventory]" ] [userdb function=set_acl location=cartcfg/edit_inventory] [page cartcfg/edit_inventory]You may edit the inventory database</a> [else] [userdb function=set_acl location=cartcfg/edit_inventory delete=1] Sorry, you can't edit inventory. [/if]