Purpose of Module
The Extra Customer Fields module allows you to specify additional customer information fields within your store, as well as provides template-based layout control over the customer account screen and the customer information within all checkout screens. The extra customer fields can be displayed on all account and checkout screens, including the following:
- ACNT - Add / Edit Customer Account Screen,
- OINF - Checkout: Customer Information Screen,
- OSEL - Checkout: Shipping / Payment Selection Screen,
- OPAY - Checkout: Payment Screen, and
- INVC - Invoice Screen.
The Extra Customer Fields module supports all standard Miva Merchant fields, and also allows a variety of input types for custom fields, including text field, text area, checkbox, radio button, single select list, multi-select list, country dropdown, and state dropdown. These different input types, their settings and implementations are discussed in detail below.
How to Install
- Installing the Module
- Unzip the module's ZIP file to your hard drive
- Log into your Miva admin utility
- Expand the navigation tree next to Modules
- Click the link "Add Module"
- Click the "Upload File" graphic
- Click the "Browse" button
- Browse to the location where you stored the contents of the ZIP file
- Select nbecf.mvc
- Click the "Upload" button
- When the graphic has been uploaded, the small "Upload File" window will disappear, leaving you with the main Miva admin screen visible
- Click the "Add" button on the main Miva admin screen
- Associating the Module with a Store
- Log into your Miva admin utility
- Expand the navigation tree next to Stores
- Expand the navigation tree next to the store with which you wish to associate this module
- Click the link "System Extension Configuration"
- In the assigned module list, you should see an entry for "NetBlazon's Extra Customer Fields"
- Check the checkbox next to this module and click Update
- Installing the Log Helper Module
- Log into your Miva admin utility
- Expand the navigation tree next to Modules
- Click the link "Add Module"
- Click the "Upload File" graphic
- Click the "Browse" button
- Browse to the location where you stored the contents of the ZIP file
- Select nbecf_log.mvc
- Click the "Upload" button
- When the graphic has been uploaded, the small "Upload File" window will disappear, leaving you with the main Miva admin screen visible
- Click the "Add" button on the main Miva admin screen
- Associating the Log Helper Module with a Store
- Log into your Miva admin utility
- Expand the navigation tree next to Stores
- Expand the navigation tree next to the store with which you wish to associate this module
- Click the link "Logging Configuration"
- In the assigned module list, you should see an entry for "NetBlazon's Extra Customer Fields (Log Helper)"
- Check the checkbox next to this module and click Update
Administrator Interface
There are four main sections of the Administration Functionality - Global Settings, Standard Settings, Templates and Extra Fields. Each is available via a "subtab" on the administration screen. Additionally, when manipulating the options for an extra customer field, a fifth temporary section will be made available for the current customer field. Each of these sections and their utility are explained below.
How to Configure Global Settings
- Log into your Miva admin utility
- Expand the navigation tree next to Stores
- Expand the navigation tree next to the store with which you wish to associate this module
- Click the link "System Extension Configuration"
- Click the "Extra Customer Fields" tab. The "Global Settings" subtab is displayed by default
- If desired, enter a Required Field Indicator. This HTML or text will be displayed to the left of any field prompts for required fields. (See CSS Support, below, for additional ways to customize the display of required fields.)
- If desired, enter an OptionField Indicator. This HTML or text will be displayed to the left of any field prompts for optional fields. (See CSS Support, below, for additional ways to customize the display of optional fields.)
- Click the Update button to save your changes.
How to Assign/Manage Standard Customer Fields
By default, there are numerous standard fields that Miva Merchant provides out-of-the-box, for both shipping and billing information. Each of these sets of information are configurable with the Extra Customer Fields module. Selecting the Standard Fields tab provides access to each standard field. You can manipulate each of these fields by changing the field prompt to more suitable text or adding optional attributes for each field.
The prompts and optional field attributes are fully customizable and support OpenUI tokens and expressions. To change the prompt for a standard field, enter the new name in the "New Field Name" box. For instance, you may want to change "E-Mail" to "Email Address". You can also use OpenTokens to conditionally change the prompts. For instance, if you want to say "Your Email Address" on the Add / Edit Customer Account screen, but "Email Address" everywhere else, enter the following:
The addition of the WLNC and WLRC screens allows the "Your Email Address" prompt to be shown on the Add / Edit Customer Account screen when submitting the form results in an error.
The field attributes allow you to specify additional code to be displayed within the <input> or <select> tags. This may consist of "size", "maxlength", or "id" attributes (or any other valid HTML attributes except "name" or "class") or event handlers for JavaScript control.
How to Manage Templates
The Extra Customer Fields module provides templates for all screens associated with customer field entry or display. These screens include the following:
- Customer Account Screen (ACNT),
- Customer Edit Account Screen (ACNT),
- Checkout: Order Information Screen (OINF),
- Checkout: Shipping / Payment Selection (OSEL),
- Checkout: Payment Information (OPAY), and
- Checkout: Invoice (INVC)
In order to ensure maximum flexibility of design and page layout, each template placeholder is loaded, by default, with the display associated with an out-of-the-box Miva Merchant implementation. Therefore, as soon as you've installed this module, you are effectively using the Extra Customer Field functionality.
Additionally, each default template can be restored to its original default implementation, in case you mistakenly erase, or otherwise corrupt your template in the module. To accomplish this, simply select the appropriate checkbox associated with the module you wish to restore and click the Update button. Any changes that have been made to the template being restored will be permanently deleted!
Both standard and extra customer fields are designated within the templates as tokens. Standard fields have a prefix of "nbecf_", which tokens for extra fields are based on the corresponding Field Name. Prompts for standard and custom fields can also be displayed using tokens; this is preferred over hardcoding a name because it allows the system to display fields as required, optional, and/or invalid as specified via CSS.
A more in-depth discussion of tokens can be found in the tokens section.
How to Create your own Extra Customer Fields
While supporting the standard customer fields is important, the true purpose of this module is to extend that base functionality by allowing the administrator to create their own unique customer fields for the purpose of collecting valuable information.
These extra customer fields can be created with differing input types, such as text fields, text areas, checkboxes, radio buttons, and a variety of others. The example below details the steps required for setting up a new extra customer field, such as a second Address line.
- Click the "Extra Fields" subtab
- The system will display the extra fields currently associated with your store. To create a new field, select the button on the right hand side of the interface in the blue banner.
- A new field with blank settings will be displayed below any current extra fields. A new extra field requires, at a minimum, a Field Name, which is used later as a token for display purposes (this is detailed in the Tokens section below).
- Once you have entered all appropriate values for your new extra field, click the Update button to add the new field to your database.
How to Assign Option Values to an Extra Customer Field
- Radio Buttons, Dropdowns, and Single and Multi Select List Interface Types support options. Only fields with these Interface Types will have a button for editing options.
- To the right of every extra field in the list are one or two circular buttons. The first button allows you to edit the field itself. For fields with Interface Types that support options, a second circular button will appear on the far right of the row; this is for editing the options for a particular field.
- Selecting the second button will activate the temporary subpage: Field Options. This subpage is temporary because it is only active when specifically selected for a particular extra field. On this page, the administrator may add, delete or modify a field option. Options can also be reordered; they will be displayed to the customer in the same order as shown within the admin interface.
- To add a new option, select the circular button in the blue banner. Enter the desired Option Code and Option Prompt. The Option Code value needs to be unique for a given Extra Field. The Option Prompt will be displayed to the customer as an entry in a dropdown or select field, or as text beside a radio button.
How to Use Tokens in Templates
A token is a specific string of characters that the Extra Customer Fields module knows to replace with either the prompt or form element for both standard and extra fields. Extra Customer Fields tokens are identified by their surrounding percent signs ("%").
Standard fields are prefixed by "nbecf_". For example, the shipping first name field is represented by the token:
The prompt for the shipping first name field is represented by the token:
The following table lists all of the tokens for the standard customer fields.
| Field Name | Token for Prompt | Token for Field |
|---|---|---|
| Login | %prompt|nbecf_login% | %nbecf_login% |
| Email Lost Passwords To | %prompt|nbecf_lpemail% | %nbecf_lpemail% |
| Password | %prompt|nbecf_pw% | %nbecf_pw% |
| Confirm Password | %prompt|nbecf_verifypw% | %nbecf_verifypw% |
| Logout Link | N/A | %nbecf_logout% |
| Shipping First Name | %prompt|nbecf_fname_s% | %nbecf_fname_s% |
| Shipping Last Name | %prompt|nbecf_lname_s% | %nbecf_lname_s% |
| Shipping E-Mail | %prompt|nbecf_email_s% | %nbecf_email_s% |
| Shipping Phone Number | %prompt|nbecf_phone_s% | %nbecf_phone_s% |
| Shipping Fax Number | %prompt|nbecf_fax_s% | %nbecf_fax_s% |
| Shipping Company | %prompt|nbecf_company_s% | %nbecf_company_s% |
| Shipping Address | %prompt|nbecf_address_s% | %nbecf_address_s% |
| Shipping City | %prompt|nbecf_city_s% | %nbecf_city_s% |
| Shipping State/Province | %prompt|nbecf_state_s% | %nbecf_state_s% |
| Shipping Other State/Province | %prompt|nbecf_other_state_s% | %nbecf_other_state_s% |
| Shipping Zip Code | %prompt|nbecf_zip_s% | %nbecf_zip_s% |
| Shipping Country | %prompt|nbecf_country_s% | %nbecf_country_s% |
| Billing First Name | %prompt|nbecf_fname_b% | %nbecf_fname_b% |
| Billing Last Name | %prompt|nbecf_lname_b% | %nbecf_lname_b% |
| Billing E-Mail | %prompt|nbecf_email_b% | %nbecf_email_b% |
| Billing Phone Number | %prompt|nbecf_phone_b% | %nbecf_phone_b% |
| Billing Fax Number | %prompt|nbecf_fax_b% | %nbecf_fax_b% |
| Billing Company | %prompt|nbecf_company_b% | %nbecf_company_b% |
| Billing Address | %prompt|nbecf_address_b% | %nbecf_address_b% |
| Billing City | %prompt|nbecf_city_b% | %nbecf_city_b% |
| Billing State/Province | %prompt|nbecf_state_b% | %nbecf_state_b% |
| Billing Other State/Province | %prompt|nbecf_other_state_b% | %nbecf_other_state_b% |
| Billing Zip Code | %prompt|nbecf_zip_b% | %nbecf_zip_b% |
| Billing Country | %prompt|nbecf_country_b% | %nbecf_country_b% |
| Update Customer Information Checkbox | %prompt|nbecf_upd_info% | %nbecf_upd_info% |
| Save Button - Add Mode | N/A | %nbecf_save_a% |
| Save Button - Add Mode | N/A | %nbecf_save_e% |
| Save Button - Checkout Mode | N/A | %nbecf_save_c% |
Tokens for extra fields are built from the field name. For instance, if you create an extra field for a second address line and assign the name "Addr2", then the token will be:
The token for the field prompt will be:
Note that all tokens are case-sensitive. Tokens for standard fields are always lower case, and tokens for extra fields should have the same case as the field name.
Viewing/Editing Data
- Log into your Miva admin utility
- Expand the navigation tree next to Stores
- Expand the navigation tree for your store
- Click the "Customers" link
- Choose a customer and click the circular "Edit" button
- Click on the link for NetBlazon's Extra Customer Fields
- On the next page, click the link that says "Extra Customer Fields".
- The admin template will be displayed with the appropriate fields. An administrator may edit the value of extra fields. Because of the design of the Miva Merchant administrative interface, standard fields are shown as text only. The values for these fields may be changed on their corresponding tab ("Indentification" or "Shipping/Billing Information").
- Click the Update button to save changes
CSS Support
The module supports four class selectors on both prompts and fields. These selectors are:
- required - for required fields
- optional - for optional fields
- required_invalid - for required fields that were submitted as blank or with an invalid value
- optional_invalid - for optional fields that were submitted with an invalid value
These class selectors can be specified in an external stylesheet and linked to the store via standard CSS/HTML methods, or entered inside the HeadTag Insert section of the OpenUI Head / Body Tags screen. For the latter, the following example sets the prompts (which are set inside <span> tags) to bold for required, italics for optional, and red when invalid:
span.required {
font-weight: bold;
}
span.optional {
font-weight: italics;
}
span.required_invalid {
font-weight: bold;
color: red;
}
span.optional_invalid {
font-weight: italics;
color: red;
}
</style>
You can also affect the form inputs themselves by using select.required, select.optional, select.required_invalid, select.optional_invalid, input.required, input.optional, input.required_invalid, and input.optional_invalid.