Chapter 23. Custom Product Attributes and Miscellaneous Items
Prev   Next

Chapter 23. Custom Product Attributes and Miscellaneous Items

Table of Contents

Using Custom Product Attributes
What types of Custom Attributes can be added to a product?
Creating a Custom Attribute Definition and adding it to a Template
Entering Template based Custom Attribute data for a Product
Displaying the custom data in the storefront Application
Miscellaneous Items
Product Description Custom Fields

This chapter describes how to use Custom Attributes, Miscellaneous Items and Product Description Custom Fields

Using Custom Product Attributes

This section shows you how to create manage and display custom product attributes.

What types of Custom Attributes can be added to a product?

Every product in KonaKart can be assigned two types of custom attributes and an array of miscellaneous items. The custom attributes may be maintained in the Custom tab folder of the Edit Product Panel. The attributes in the Custom Attributes sub folder are mapped to database table attributes in the product table. This means that they can be added as constraints to product search queries and used to order the result of a search. The custom attributes consist of 10 strings, 2 integers and 2 decimal fields. Note that in the Admin App the labels for the entry fields may be customized using the message catalog.

The attributes in the Template Attributes sub folder are defined using the Custom Attributes and Custom Attribute Templates panels. These attributes have associated metadata which is used to:

  • Decide what widget to use when entering data using the Admin App

  • Store validation rules used by the Admin App to validate entered data.

  • Store a message catalog key for each attribute.

  • Store an attribute type and template used by the storefront application to dynamically detect the type of data being displayed and how to display it using the template.

  • Custom fields which may be used by the storefront application to display the data. i.e. to group the custom attributes.

When saved, these attributes are encoded into an XML structure and saved within a single database attribute of the product table. This means that they may not be used as constraints for searching for products or ordering the array of products returned by a search.

Whenever a product is returned by an API call of the Admin or Application engine, these attributes are attached to the product within an array. Each element within the array contains the name, type and value of the attribute. It may also contain the template, message catalog key and custom fields if these have been defined.

The miscellaneous items are objects that have a type and a type description as well as a value. They can be used to add an array of items to any product or category. For example you may want to associate a product with a number of documents. In this case you define a "document" miscellaneous item type and a miscellaneous item (of type document) for each document.

Creating a Custom Attribute Definition and adding it to a Template

Custom attributes definitions may be managed using the Custom Attributes panel of the Admin App. The panel allows you to create new and manage existing attributes. Each custom attribute definition has the following attributes:

  • Name: The unique name of the custom attribute which is a compulsory field. i.e. ScreenSize or MegaPixels etc.
  • Type: You may choose types from a drop list. This information may be used by the storefront application when displaying the attribute value. i.e. If it knows the type of attribute it may decide what template to use in order to display it.
  • Set Function: This is used by the Admin App when creating a UI widget to insert the custom attribute value once it has been added to a product. Valid Set Functions are:
    • integer(min,max) where min and max may be numbers or set to null. i.e. integer(10,null) checks that the integer has a minimum value of 10 or above. integer(null,null) just checks that the value entered is an integer without doing any range checking.
    • double(min,max) using the same logic as explained above for decimal numbers.
    • string(min,max) using the same logic as explained above for the length of the string.
    • choice('true','false') creates a radio button panel with the options of true and false.
    • choice('label.small','label.medium','label.large') creates 3 radio buttons where the labels are looked up in a message catalog. In this case, the text displayed is looked up from the message catalog, whereas the values saved are always label.small, labl.medium and label.large regardless of the language.
    • choice('S'='label.small','L'='label.large') creates 2 radio buttons where the labels are looked up in a message catalog. In this case, the text displayed is looked up from the message catalog, whereas the values saved are the associated values (eg. 'M' or 'L' in this example).
    • option(0=date.day.long.Sunday,1=date.day.long.Monday,2=date.day.long.Tuesday) creates a drop list for the first 3 days of the week. The text of the days displayed is retrieved from the message catalog whereas the saved data is 0 for Sunday, 1 for Monday and 2 for Tuesday.
    • multiselect(0=date.day.long.Sunday,1=date.day.long.Monday,2=date.day.long.Tuesday) creates a group of check boxes for the first 3 days of the week. The text of the days displayed is retrieved from the message catalog. The difference between multiselect and option is that with the multiselect multiple options are saved in a comma-separated list. For example in this case the saved data would be 0 for Sunday, 0,1 for Sunday and Monday and 1,2 for Monday and Tuesday etc.
    • RichText(x) where x defines the vertical size (in elements) of the Rich Text data entry widget. (e.g. RichText(10) for a size of 10em)
  • Template: The template contains a string that may be used by the storefront application to display the value. i.e. In the case of a date, the storefront application could detect that it is a date from the type and then use the template to display the date correctly.
  • Msg Cat Key: This is used by the storefront and Admin applications to look up the label from the message catalog. If not present, the name may be used.
  • Validation: This may contain regular expression such as true|false or [0-9]* which will be used by the admin app to validate the attribute.
  • Custom Fields: The custom fields may contain any metadata for the attribute which can be used by the storefront application. i.e. A custom field may contain data useful for grouping custom attributes.

The default demo database comes complete with a number of example custom attribute definitions.

Custom attribute definitions may be used by more than one template. In order to assign an attribute to a product, it first needs to be added to a template since a product is assigned a template and not an array of custom attributes. Templates are managed using the Custom Attribute Templates panel. Once a template has been created, it may be assigned a number of custom attributes using a pop-up select panel. The order in which the attributes are assigned to the template is important since this will be the order of the custom attributes within the attribute array attached to a product.

Entering Template based Custom Attribute data for a Product

In the Details folder of the Edit Product Panel, through the use of a pop-up panel, one or more templates may be chosen for a product. Note that the changes only take effect once the pop-up panel has been closed and the save button has been clicked. If any of the chosen templates has a number of custom attribute definitions then an equivalent number of custom fields will appear in the Template Attributes sub folder of the Custom folder. These entry fields which may include drop lists and radio buttons, allow you to enter the custom values for each product. The entry fields for the first template in the list are displayed first, followed by those of the second template etc.

When the product is saved, the custom field data is encoded within an XML structure and saved within an attribute of the product table in the database.

Displaying the custom data in the storefront Application

If a product includes custom template data, when fetched from the KonaKart Application engine, it will contain an instantiated customAttrArray with the custom attribute values and metadata. Note that the product will also contain an attribute called customAttrs that represents the XML of the custom data. If preferred, you may display the custom data directly from the XML.

Prev   Next
Custom Validation for the Admin Application Home Miscellaneous Items