Difference between revisions of "Functions:userAccountAndAddressCreate"

From Whirlwind eCommerce Wiki
Jump to: navigation, search
(→‎Return Values: added groups)
 
(5 intermediate revisions by 2 users not shown)
Line 34: Line 34:
 
:::*company
 
:::*company
 
:::*title
 
:::*title
 +
:::*handle
 +
:::*passwordHint
 
::*Other Fields
 
::*Other Fields
 
:::*subscribe: if set to 1, newsletter registration process will be initiated for the passed emailAddress
 
:::*subscribe: if set to 1, newsletter registration process will be initiated for the passed emailAddress
 
:::*captcha: verifies captcha validation has been passed
 
:::*captcha: verifies captcha validation has been passed
 
:::*custom_field_...: any number of custom user fields can be passed, but must be set up in [[Settings]] in User Management.
 
:::*custom_field_...: any number of custom user fields can be passed, but must be set up in [[Settings]] in User Management.
 +
:::*group_#: any number of group assignments, must be valid groups set up in [[Groups]].
 
:: Example $fieldList value: "firstName,lastName,emailAddress,password,passwordConfirm"
 
:: Example $fieldList value: "firstName,lastName,emailAddress,password,passwordConfirm"
 
:: The listed fields in $fieldList can be complimented with the following field controls:
 
:: The listed fields in $fieldList can be complimented with the following field controls:
Line 47: Line 50:
 
:: example use of controls in $fieldList: "emailAddress/email:You must enter an valid email/unique:An account already exists with that email address - please select another,password/min:8:You must enter a password of at least 8 characters"
 
:: example use of controls in $fieldList: "emailAddress/email:You must enter an valid email/unique:An account already exists with that email address - please select another,password/min:8:You must enter a password of at least 8 characters"
 
:: note that the messages in control fields cannot contain comma (,), slash (/) or colon (:) as these have special meaning to the processing function
 
:: note that the messages in control fields cannot contain comma (,), slash (/) or colon (:) as these have special meaning to the processing function
 +
:: also note that you can place firstName,lastName,address_firstName and address_lastName in $fieldList, but only use/pass firstName / lastName in form. The system will use firstName/lastName value for address_firstName/address_lastName.
 
*$redirect STRING
 
*$redirect STRING
 
:: URL where visitor will be forwarded to following a successful form submission
 
:: URL where visitor will be forwarded to following a successful form submission
Line 86: Line 90:
 
           //Custom Fields
 
           //Custom Fields
 
           [custom_field_...] => STRING
 
           [custom_field_...] => STRING
 +
          [group_...] => BIT
 
           ...
 
           ...
 
         )
 
         )
 
)
 
)
 
</pre>
 
</pre>
 +
 
== Examples ==
 
== Examples ==
−
;Simple Example:
+
;Simple Example (only account with login,password):
 
<source lang="php">
 
<source lang="php">
  
Line 128: Line 134:
  
 
// user account fields:
 
// user account fields:
 +
// note that the maxlength of all account fields in this form matches the data field length in the database. Be sure to include the maxlength attributes in your form field or you risk mysql errors to users.
  
 
// email address
 
// email address
Line 148: Line 155:
  
 
</source>
 
</source>
−
;Full Example:
+
;Full Example (includes first address in address book, custom fields, newsletter subscription):
 
<source lang="php">
 
<source lang="php">
  
Line 191: Line 198:
  
 
// user account fields:
 
// user account fields:
 +
// not that the maxlength of all the below fields matches the data length in the database - be sure to include these maxlength attributes or you risk users exceeding column sizes and receiving a mySQL error.
  
 
// email address
 
// email address
Line 209: Line 217:
 
// address fields
 
// address fields
 
// create first address in address book
 
// create first address in address book
 +
 +
// note that you can use one set of name fields for BOTH the useraccount and the address
 +
// to do this, specify firstName, lastName, address_firstName, address_lastName in $fieldList attribute
 +
// then ONLY use firstName and lastName form fields. The system will use the firstName,lastName values for BOTH the address and user account
 
echo "<br>First Name: <input name=\"address_firstName\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_firstName']) . "\" maxlength=50 />";
 
echo "<br>First Name: <input name=\"address_firstName\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_firstName']) . "\" maxlength=50 />";
 
echo "<br>Last Name: <input name=\"address_lastName\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_lastName']) . "\" maxlength=50 />";
 
echo "<br>Last Name: <input name=\"address_lastName\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_lastName']) . "\" maxlength=50 />";

Latest revision as of 13:40, 11 December 2011

Description

Controls a new user/address form, adds a new user/address. Use this function to build a 'create account' page.

Syntax

$accountArray = eV::userAccountAndAddressCreate($fieldList,$redirect);

Paramaters

  • $fieldList STRING
Comma separated list of fields to be managed by the form.
Available fields to place in $fieldList:
  • Address Fields
  • address_firstName
  • address_lastName
  • address_company
  • addressName
  • street1
  • street2
  • city
  • state
  • state_alt
  • zipCode
  • country
  • phone1
  • phone2
  • phone3
  • fax
  • User Account Fields
  • emailAddress
  • firstName
  • lastName
  • password
  • passwordConfirm
  • userNotes
  • company
  • title
  • handle
  • passwordHint
  • Other Fields
  • subscribe: if set to 1, newsletter registration process will be initiated for the passed emailAddress
  • captcha: verifies captcha validation has been passed
  • custom_field_...: any number of custom user fields can be passed, but must be set up in Settings in User Management.
  • group_#: any number of group assignments, must be valid groups set up in Groups.
Example $fieldList value: "firstName,lastName,emailAddress,password,passwordConfirm"
The listed fields in $fieldList can be complimented with the following field controls:
  • /min:#:message
  • /max:#:message
  • /default:value
  • /email:message
  • /unique:message
example use of controls in $fieldList: "emailAddress/email:You must enter an valid email/unique:An account already exists with that email address - please select another,password/min:8:You must enter a password of at least 8 characters"
note that the messages in control fields cannot contain comma (,), slash (/) or colon (:) as these have special meaning to the processing function
also note that you can place firstName,lastName,address_firstName and address_lastName in $fieldList, but only use/pass firstName / lastName in form. The system will use firstName/lastName value for address_firstName/address_lastName.
  • $redirect STRING
URL where visitor will be forwarded to following a successful form submission

Return Values

Multidimensional array of field values and error messages containing [message]: a string containing any error messages that prohibited the form data from being submitted, and [values]: a keyed array of fields and their values. Note that only fields specified in the $fieldList attribute will be contained in the [value] array: 

Array
(
    [message] => STRING
    [values] => ARRAY
        (
           //Address Fields
           [address_firstName] => STRING
           [address_lastName] => STRING
           [address_company] => STRING
           [addressName] => STRING
           [street1] => STRING
           [street2] => STRING
           [city] => STRING
           [state] => STRING
           [state_alt] => STRING
           [zipCode] => STRING
           [country] => STRING
           [phone1] => STRING
           [phone2] => STRING
           [phone3] => STRING
           [fax] => STRING
           //User Account Fields
           [firstName] => STRING
           [lastName] => STRING
           [emailAddress] => STRING
           [password] => STRING
           [passwordConfirm] => STRING
           [userNotes] => STRING
           [company] => STRING
           [title] => STRING
           //Custom Fields
           [custom_field_...] => STRING
           [group_...] => BIT
           ...
        )
)

Examples

Simple Example (only account with login,password)
// kick if logged in // recommended to place in 'pre process' code of template - no reason to waste processing power if we just gonna kick to home.
eV::authorizeIsLoggedOut('index.php?message=You cannot create an account while logged in');
 
// create account function
$account = eV::userAccountAndAddressCreate("emailAddress/email:You must enter a valid email address/unique:The email address you entered is already in use - please select another,password/min:8:Your password must be at least 8 characters long,passwordConfirm","index.php?message=Your account has been created!");
 
// shortcut the elements of the userAccountAndAddressCreate array
$accVals = $account['values'];
 
// display the message (if applicable)
// this message is generated by the userAccountAndAddress create function
// not to be confused with the global $message attribute 
// you probably want to accomidate both
if(!empty($account['message'])) echo $account['message'];
 
// here is the global message
if(!empty($message)) echo $message;
 
// output page content
echo "$title
<br>$subTitle
<br>$copy";
 
// start the form
echo "<form name=\"createAccountForm\" action=\"index.php\" method=\"post\">";
 
///////////////////////////////
////// CORE form fields ///////
///////////////////////////////
 
// note when calling userAccountAndAddressCreate you can specify the fields, so the below fields may vary
// make sure you call all, and only the fields you need
 
// user account fields:
// note that the maxlength of all account fields in this form matches the data field length in the database. Be sure to include the maxlength attributes in your form field or you risk mysql errors to users.
 
// email address
// recommend using htmlspecial chars to ensure quotes and carots don't disrupt the form tag
echo "<br>Email Address: <input name=\"emailAddress\" maxlength=100 value=\"" . htmlspecialchars($accVals['emailAddress']) . "\" type=\"text\" />";
 
// password and confirm password will be compared upon submission to match
// they must also be min 8 characters in length
echo "<br>Password: <input name=\"password\" type=\"password\" value=\"" . htmlspecialchars($accVals['password']) . "\" maxlength=50/>";
echo "<br>Confirm Password: <input name=\"passwordConfirm\" type=\"password\" value=\"" . htmlspecialchars($accVals['passwordConfirm']) . "\" maxlength=50/>";
 
// submit form button
echo "<br><input type=\"submit\" value=\"Create!\">";
 
// required hidden field - must pass this page id so submissions reload in this page
echo "<input type=\"hidden\" name=\"pageId\" value=\"$pageId\">";
 
// end the form
echo "</form>";
Full Example (includes first address in address book, custom fields, newsletter subscription)
// kick if logged in // recommended to place in 'pre process' code of template - no reason to waste processing power if we just gonna kick to home.
eV::authorizeIsLoggedOut('index.php?message=You cannot create an account while logged in');
 
// create account function
$account = eV::userAccountAndAddressCreate("emailAddress/email:You must enter a valid email address/unique:The email address you entered is already in use - please select another,firstName,lastName,title,password/min:8:Your password must be at least 8 characters long,passwordConfirm,address_firstName,address_lastName,address_company,street1,street2,city,state,state_alt,zipCode,country,phone1,subscribe,captcha,custom_field_x,custom_field_y,custom_field_z","index.php?message=You account has been created!");
 
// shortcut the elements of the userAccountAndAddressCreate array
$accVals = $account['values'];
$accCust = $account['customFieldTags'];
 
// get state options
$stateOptions = eV::addressStateOptions($accVals['state']);
// get country options
$countryOptions = eV::addressCountryOptions($accVals['country']);
 
// display the message (if applicable)
// this message is generated by the userAccountAndAddress create function
// not to be confused with the global $message attribute 
// you probably want to accomidate both
if(!empty($account['message'])) echo $account['message'];
 
// here is the global message
if(!empty($message)) echo $message;
 
// output page content
echo "$title
<br>$subTitle
<br>$copy";
 
// start the form
echo "<form name=\"createAccountForm\" action=\"index.php\" method=\"post\">";
 
///////////////////////////////
////// CORE form fields ///////
///////////////////////////////
 
// note when calling userAccountAndAddressCreate you can specify the fields, so the below fields may vary
// make sure you call all, and only the fields you need
 
// user account fields:
// not that the maxlength of all the below fields matches the data length in the database - be sure to include these maxlength attributes or you risk users exceeding column sizes and receiving a mySQL error.
 
// email address
// recommend using htmlspecial chars to ensure quotes and carots don't disrupt the form tag
echo "<br>Email Address: <input name=\"emailAddress\" maxlength=100 value=\"" . htmlspecialchars($accVals['emailAddress']) . "\" type=\"text\" />";
// newsletter subscribe field
// checking this will trigger the newsletter registration process in addition to creating an account
echo "<br>Join Our Newsletter: <input name=\"subscribe\" type=\"checkbox\" checked=\"checked\" value=\"1\"/>";
 
echo "<br>First Name: <input name=\"firstName\" type=\"text\" maxlength=50  value=\"" . htmlspecialchars($accVals['firstName']) . "\" />";
echo "<br>Last Name: <input name=\"lastName\" type=\"text\" maxlength=50  value=\"" . htmlspecialchars($accVals['lastName']) . "\" />";
 
// password and confirm password will be compared upon submission to match
// they must also be min 8 characters in length
echo "<br>Password: <input name=\"password\" type=\"password\" value=\"" . htmlspecialchars($accVals['password']) . "\" maxlength=50/>";
echo "<br>Confirm Password: <input name=\"passwordConfirm\" type=\"password\" value=\"" . htmlspecialchars($accVals['passwordConfirm']) . "\" maxlength=50/>";
 
// address fields
// create first address in address book
 
// note that you can use one set of name fields for BOTH the useraccount and the address
// to do this, specify firstName, lastName, address_firstName, address_lastName in $fieldList attribute
// then ONLY use firstName and lastName form fields. The system will use the firstName,lastName values for BOTH the address and user account
echo "<br>First Name: <input name=\"address_firstName\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_firstName']) . "\" maxlength=50 />";
echo "<br>Last Name: <input name=\"address_lastName\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_lastName']) . "\" maxlength=50 />";
echo "<br>Company Name: <input name=\"address_company\" type=\"text\" value=\"" . htmlspecialchars($accVals['address_company']) . "\" maxlength=50 />";
echo "<br>Address Line 1: <input name=\"street1\" type=\"text\" value=\"" . htmlspecialchars($accVals['street1']) . "\" maxlength=50  />";
echo "<br>Address Line 2: <input name=\"street2\" type=\"text\"  value=\"" . htmlspecialchars($accVals['street2']) . "\" maxlength=50 />";
echo "<br>City: <input name=\"city\" type=\"text\"  value=\"" . htmlspecialchars($accVals['city']) . "\" maxlength=50 />";
// output state options short cut called at beginning of script
echo "<br>State: <select name=\"state\">" . $stateOptions . "</select> "; 
// state alt- for international visitors to enter thier province, etc.       	
echo "<br>Province/Region: <input name=\"state_alt\" type=\"text\" maxlength=50 value=\"" . htmlspecialchars($accVals['state_alt']) . "\"/>";
echo "<br>Zip/Postal Code: <input name=\"zipCode\" type=\"text\" size=\"10\"  maxlength=10 value=\"" . htmlspecialchars($accVals['zipCode']) . "\"/>";
echo "<br>Country: <select name=\"country\">" . $countryOptions . "</select> "; 
echo "<br>Phone Number: <input name=\"phone1\" type=\"text\" maxlength=15 value=\"" . htmlspecialchars($accVals['phone1']) . "\" />";
 
// user custom fields
// these custom fields must be created in Settings > User Management
// and must be specified in the fieldList attributes of the userAccountAndAddressCreate function
// custom fields are included in the customFieldTags key of the returned userAccountAndAddressCreate array
// the contents of the customFieldTags elements are full tags for the field as set in field settings for the field in Settings > User Management
// you can simply output the customFieldTags element contents for the field
echo "<br>Custom Field X: " . $accCust['custom_field_x']);
echo "<br>Custom Field Y: " . $accCust['custom_field_y']);
echo "<br>Custom Field Z: " . $accCust['custom_field_z']);
 
// captcha verification
// great to keep ppl from using bots to abuse the system
// this is not required to use, but you must have 'captcha' in the fieldList attribute of the userAccountAndAddressCreate function
// 3 things required for this to work:
// 1. 'captcha' in the fieldList of the userAccountAndAddressCreate
// 2. calling on the captcha image by setting $CaptchaImgSrc as the image source
// 3. including the captcha form field
echo "<br>Captcha Validation <img src='$CaptchaImgSrc'>
<br>Please type in the characters you see above: <input type=text name=captcha value='' size=10 maxlength=10>";
 
// submit form button
echo "<br><input type=\"submit\" value=\"Create!\">";
 
// required hidden field - must pass this page id so submissions reload in this page
echo "<input type=\"hidden\" name=\"pageId\" value=\"$pageId\">";
 
// end the form
echo "</form>";
Retrieved from "http://wiki.whirlwind-ecommerce.com/mediawiki/index.php?title=Functions:userAccountAndAddressCreate&oldid=990"