Reference Guide

Utilities

Custom Field Groups

Custom Field Groups make it easier to organize and view your custom fields.

We created two custom field groups: "Motherboard Spec Fields" and "Tower Cases", and assigned each field to a group. Now we can sort the custom fields by clicking on the Group column title.

To Create a Custom Field Group

1. Go to > Utilities > Custom Field Groups tab.
2. Click Add Group .
• Enter a Code: the code uniquely identified the group in your store
• Enter a Name: the name is a more user friendly description of the group.
3. Click Save Group .

To Assign a Custom Field to a Group

1. Go to > Utilities > Custom Fields tab.
2. Edit a custom field.
3. In the Edit Custom Field dialog box, select your group from the Group list box, and click Save.

Example: Adding and Using a Custom Category Field

In this example we'll create a custom category field that allows us to display or hide categories in the category tree.

1. Go to > Utilities > Custom Fields tab.
2. Create a custom field of type Category.



3. Edit the value of the custom field.

3.1. Go to > Catalog > Categories tab > (edit a Category) > Custom Fields tab.

4. When you edit a category now, you'll see that there is a new tab called "Custom Fields". In this new tab is the custom category field that you created.

After you create a custom field of type "Category", you'll see a new tab "Custom Fields" when you edit a category. The new tab shows the custom field that you created. For our example, we'll set the value of this field to "False".

5. Add category tree template code. In our example we'll use the custom field to control whether a category is displayed in the category tree. If the value of the custom field is "true", the category will be displayed in the on-line store.

5.1. Go to > User Interface > Settings tab > Category Tree Template tab.

5.2. Add the field. In the Custom Fields section, click on the field named "Display", then click the Select button. (To reduce overhead in the admin interface, only custom fields that have been selected can be referenced in the template code.)

5.3. Edit the template code. In the category tree template code we'll add code to scan the value of the "Display" field for each category. Categories where the Display field contains the string "true" will be shown in the category tree.



5.4. The new code we'll add to the template field is:

6. When you've finished making your changes to the Category Tree Template tab, click the Update button.

Example: Adding and Using a Custom Product Field

This example shows how to create a custom product field and one example of how such a field can be used.

1. Go to > Utilities > Custom Fields tab.
2. Create a custom field of type Product. We'll call ours "MSRP".



3. Edit the value of the custom field.

3.1. Go to > Catalog > Products tab > (edit a product) > Custom Fields tab.

When you edit a product now, you'll see that there is a new tab called "Custom Fields". In this new tab is the custom product field that you created.

The custom field that we created, "MSRP", now shows up when we edit a product. We'll set the value of this field to "$25.00".

4. Add the custom field to the product page. There are many different things you could do with a custom product field. As a simple example, we'll have our custom field show up in product pages in our on-line store.

4.1. Go to > User Interface > Pages tab > (edit page PROD) > Page tab > Product Display Layout section.

4.2. Click on the custom field ("MSRP" in our example), then click the Select button. (To reduce overhead in the admin interface, only custom fields that have been selected can be referenced in the template code.)



4.3. In the Page tab, click Update.

5. Now let's look at a product page in our on-line store:





In our example the custom product field automatically showed up in our on-line store because we had not modified our product page template code. If you have modified your product page template code, you must:

1. Select the custom field in the > User Interface > Pages tab > (edit page PROD) > Page tab > Product Display Layout section.
2. In the Product Display Layout section, click on the link to view the Product Display Template code.
3. Manually add the code that will display the custom field.

Example: Adding a Custom Field with Image Upload

In this example we'll show how to use the Image Upload field type to add content to your store pages that customers can download.

1. Make sure that the file type that you want to use is supported by the admin interface. For example, if you want to add a PDF to a store page that your customers can download:

1.1. Go to > Domain Settings > Domain Details tab > Upload Settings section.

1.2. In the Upload Settings section, add "PDF" to the Image Extension Types field:



2. Create a custom field group called "Manuals".
3. Create a custom field called "User Manual 01" with a Field Type of "Upload Image".



4. Edit a product.

4.1. There is now a tab called "Manuals", created by our custom field group.

4.2. The Manuals tab contains our custom field: "User Manual 01"



5. In the Manuals tab, click on the Upload button to upload your document to your server. If you wanted to attach a PDF to a large number of products, you could upload the PDF once, and then add the server file path of the PDF to a product import spreadsheet (see Data Management > Import/Export Tab).
6. Go to > User Interface > Pages tab > (edit page PROD) > Page tab > Product Display Layout section.
7. Add the custom field to the page.

7.1. Click on the custom field.

7.2. Click Select.

7.3. Click Update.



8. Modify the template code to reference the custom field.

8.1. If you haven't already, click on the link so that you can see the template code.

8.2. Look for the template code:

&mvt:product:customfield_values:customfields:user_manual_01;

and change it to:

9. Click Update.
10. If we go to our online store and select the product page for the Basic Tower Kit, we'll see that our user manual shows up as a hyperlink. If the customer clicks on the link, their browser will either open the PDF in a new browser window, or ask the user to save the PDF, depending on how their browser is configured.

Example: Custom Basket Fields

There are times when you might want to capture information while a customer is shopping in your store and save that information to your store database. For example, you might want to capture the customer's IP address and save it with the order record. In releases before PR8 Update 9, you could capture the information, but to save it to the database you had to use a third party module.

PR8 Update 9 added 16 new read/write template functions that let you attach information that you've captured to different types of records. You can use these functions to save and display a wide variety of data:

• Agent string fields
• The customer's IP address
• The referrer page
• Any information about the customer's basket, items, costs, etc.

In this example, we'll show how to put a drop-down list on the OSEL page (Checkout: Shipping/Payment Selection) and save the customer's selection to the basket record.

• Write_Basket: creates a custom basket field and writes a value to it.
• Read_Basket: reads the value from a custom basket field.

Normally, the custom fields that you attach to a basket record are lost when the basket is deleted. However, there is a way to "convert" the information and permanently save it in the database with the customer's order. Baskets are deleted when:

• They expire. See Basket Timeout.
• The customer completes the checkout process.
1. Make sure that you have enabled custom fields. See To Enable Custom Fields.

Custom fields are added to a page with the "customfields" item. The customfields item is already enabled on every default page in your store (every page in an "out of the box" store). If you want to use custom fields on a new page that you've created, you have to add the customfields item manually. See Editing Items.

2. Go to > User Interface > Pages tab > (edit page OSEL) > Page tab > Details section. We'll add some code to create a drop-down list box on the OSEL. Our code goes right above the "</form>" tag.



3. Click Update to save your changes.
4. Here's how the template code looks in our store:



5. The template code that we added displays a drop-down list on the OSEL page. Now we'll capture the customer's selection from the drop-down list, and display it on the next checkout page, OPAY (Checkout: Payment Information).

5.1. Go to > User Interface > Pages tab > (edit page OPAY) > Page tab > Header and Footer section.

5.2. Add the code shown in the figure below.



• The call to Write_Basket creates a new custom basket field called "hear-about-us" and gives it the value of "g.add1". We used the "add1" variable to store the customer's selection from the dropdown list box in the previous step. The call to Write_Basket saves the value of g.add1 for as long as the basket persists.
• The call to Read_Basket reads the value in the variable in 'hear-about-us' and prints it to the screen using &mvt:customfields

When the customer gets to the Invoice screen (INVC), the basket record is converted to an order record. The basket record, along with any custom basket fields, are deleted. However, if you create custom order fields that have the same names as your custom basket fields, the values in the custom basket fields are written to the custom order fields with the same name, and will be saved with the order record. You can then view the custom fields by editing the record.