Ultimate Feed Generator - Miva Module

Introduction
Install
Module Settings
Feed Definitions
Tokens
Default Feeds
Template Library
How to get Support

Purpose of Module

Ultimate Feed Generator is a tool for generating product feeds, sitemaps, and more. It can be used to create feeds for:

The module provides tokens to display dynamic product and category data, such as name, price, description, weight, and other database fields. It also fully supports OpenTokens for users of OpenUI (although OpenUI is not required to use Ultimate Feed Generator). Feeds can be generated individually, or you can select multiple feeds and run them at once. (Check them all off and go to lunch while it processes, for instance.)

Ultimate Feed Generator comes with 5 pre-defined feeds, which can be edited as needed. You can create an unlimited number of feeds; the 5 default feeds simply provide a good starting point. These pre-defined feeds are:

For more information on the default feeds, see the Default Feeds section of this document.

* These default feeds use OpenTokens to NetBlazon's Extra Product Fields module, to support additional data that is not stored in default Miva Merchant Fields. For Froogle, this would be the preferred category the product is assigned to. PriceGrabber requires brand and vendor sku fields. If you use a different module to store this data (such as Additional Product Fields or OpenUI Custom Product Fields), you can change these tokens as needed.

Each feed has options that help define its output. You can limit the categories and products based on code, price, weight, cost, stock level, and whether they are active or inactive. See below for details.

How to Install

Using the module - Module Settings

To access the module's administration screens, click the triangle next to the Utilities link under your store. Make sure you are working with the Utilities that is underlined (not the one that is not underlined, which are domain-level utilities.) After you click the triangle, you will see a list of items below the word "Utilities", indented to the right. One of these will be a link labelled "Ultimate Feed Generator". Click that link.

The first screen that appears is the Feeds Definitions screen. This is discussed in the next section. Click the "Module Settings" link to view the overall settings for the module.

Module Administration - Module Settings

As of 4.912, the only option on this screen is the location under mivadata where your feed files are generated. By default, this is set to /Merchant2/0000000x/export, but you can change this if desired. If you enter a directory that does not exist, Ultimate Feed Generator will attempt to create it for you.

Note that the feed output files can be copied to your publicly-accessible scripts directory (such as html, httpdocs, www, etc) individually. This option is located on the create/edit feed page for each individual feed template.

Using the module - Feed Definitions

Module Administration - List of Feeds

The Feeds Definitions screen lists all of the feeds defined for this store. By default there are 5 feeds created, shown in the display above. On this screen, you can run an individual feed, run a group of feeds, delete feeds, or navigate to other screens to edit a feed or add a new one.

To run a single feed: Each feed has a "Run Feed" link next to the "Last Run" column. Click this link to begin generating a given feed.

To run a group of feeds: Select the feed(s) you wish to run. You can also use the +/- icons at the top of the table to select or deselect all rows. Then click the "Run Selected" button. The module will generate all feeds in the order shown.

To delete feed(s): Select the feed(s) you wish to delete. You can also use the +/- icons at the top of the table to select or deselect all rows. Then click the "Delete" button. All checked feeds will be deleted.

To begin editing a feed: Each feed has a circular button on the far right end of its row. Click this button to edit the feed's template and/or options.

To add a new feed: Click the circular icon in the navy blue header row to begin adding a new feed.

Creating a New Feed

Module Administration - Creating a New Feed

When you create a new feed, the Feed Template screen is displayed. Enter the following fields:

Where you are done entering your feed information, click the Save button. Note that you cannot add options to a new feed; instead, save the feed from this screen, then edit the newly-created template to set options.

Editing a Feed

Module Administration - Editing a Feed's Template

When you edit a feed, you can change the templates and/or the options. The first screen shown when you choose to edit a feed is the template screen (above). Here you can alter the main template, product template, and category template. You can also change the feed name, file name, and copy location. Finally, if you wish to generate this feed, you can click the "Run Feed" link from this screen. (To generate multiple feeds, return to the Feed Definitions screen by clicking the link in the navigation area.)

When the feed is generated, the main template is processed first, and only once. Therefore this template should contain any required header rows, or opening and closing text/html/xml. There are two special tokens for the main template. The token %categories% will call the "Categories Template" once for each category that meets the criteria defined under options. The token %products% will call the "Categories Template" once for each product that meets the criteria defined under options. You can omit %categories% or %products% if your feed requires only categories or only products.

The Categories Template is included once for each category in the store, provided that the category meets any criteria defined for this feed's options. There are a number of tokens used to include category data, as detailed below.

The Products Template is included once for each product in the store, provided that the product meets any criteria defined for this feed's options. There are a number of tokens used to include product data, as detailed below.

Module Administration - Editing a Feed's Options

To edit the options for a feed, from the Feed Template screen, click the link "Feed Options". As of version 4.912, there are two new fields on this screen: Product Throttle and Category Throttle. These are used for performance enhancement. The values here tell Ultimate Feed Generator how many products or categories to process before the module refreshes the page. (The page refreshes are done to avoid "Application Timeout" errors.) The default throttle values are 50 each. If, when running your feed, you get "Application Timeout" errors, then you should reduce the number to something smaller than 50. If you wish for your feed to be generated more quickly, you can increase these numbers above 50, as long as you don't get any "Application Timeout" errors. (Prior to 4.912, only one category or product was processed with each page refresh.)

On this screen you can also define criteria to limit which categories and products are included in your feed. (Remember that categories are only included if your main template has the %categories% token, and products are only included if your main template has the %products% token. So, for example, if you don't want to include any categories, just don't put that token into the main template. You don't have to exclude EVERY category here on the options screen.) The following table describes the available options:

Exclude Inactive Categories and Products? Check this box to exclude categories and/or products marked as inactive. If this box is unchecked, ALL categories and/or products will be included, regardless of whether they are active or inactive.
Exclude Out-of-Stock Products? Check this box to exclude products that are out-of-stock. This option requires use of Miva Merchant's built-in inventory tracking system. It does not support third-party inventory tracking.
Include/Exclude Products In this box you can list one or more product codes which you want to include or exclude. If "Exclude these products" is checked, then products with these codes will be excluded from the feed output. If "Include only these products" is selected, then ONLY these products will be included in the feed output, and all other products will be omitted.
Include/Exclude Categories In this box you can list one or more category codes which you want to include or exclude. If "Exclude these categories" is checked, then categories with these codes will be excluded from the feed output. If "Include only these categories" is selected, then ONLY these categories will be included in the feed output, and all other categories will be omitted.
Include/Exclude Products by Category In this box you can list one or more category codes, and products assigned to these categories will be included or excluded. If "Exclude products in these categories " is checked, then products assigned to any of these categories will be excluded from the feed output. If "Include only products in these categories" is selected, then ONLY products assigned to one of these categories will be included in the feed output, and all other products will be omitted.
Maximum Price If desired, enter the maximum price allowed. Products whose price is greater than this will be omitted from the feed output.
Minimum Price If desired, enter the minimum price allowed. Products whose price is less than this will be omitted from the feed output.
Maximum Cost If desired, enter the maximum cost allowed. Products whose cost is greater than this will be omitted from the feed output.
Minimum Cost If desired, enter the minimum cost allowed. Products whose cost is less than this will be omitted from the feed output.
Maximum Weight If desired, enter the maximum weight allowed. Products whose weight is greater than this will be omitted from the feed output.
Minimum Weight If desired, enter the minimum weight allowed. Products whose weight is less than this will be omitted from the feed output.

Module Tokens

The following is a list of tokens available within the various templates. New tokens may be added in future releases of Ultimate Feed Generator. If you are reading this file on your computer, make sure to check for updates on the NetBlazon website. You can reach the latest documentation by clicking the "Documentation" link within the module itself.

Note that we do not provide tokens for Copernicus' Search Friendly Links, or other link styles such as those from Pixel Computer's modules or Phosphor Media's Merchant Optimizer. If you are using OpenUI, you can call any available OpenTokens from those modules, as all templates fully support OpenTokens. You can also build links of any sort by piecing together tokens. For instance, to make a Search Friendly Link to the product page, you would use the following within the Product template:

http://www.yoursite.com/page/%storecode%/PROD/%code%

This flexibility allows you to specify links of any style, regardless of what module, templating system, or mod_rewrite rules you may be using.

In All Templates:

%storecode% store code
%storename% store name
%storeurl% standard Merchant URL to the Storefront screen
%storeurl-ee% standard Merchant URL to the Storefront screen, after being run through the encodeentities function. (encodeentities converts all characters to their HTML entity equivalents. for example, "<" is converted to "&lt;". This is usually necessary for feeds whose output is XML.)
^T This special string represents a tab, and is especially useful for tab-delimited output files. Simply type in "^T" ("^" is above the "6" key) and when the feed runs, it will be replaced with a tab character.

In Product Template:

%code% product code
%name% product name as entered
%name-nohtml% product name stripped of html
%price% product price (unformatted)
%cost% product cost (unformatted)
%weight% product weight
%imagefull% url to full-sized image
%imagefull-ee% url to image after being run through encodeentities. (encodeentities converts all characters to their HTML entity equivalents. for example, "<" is converted to "&lt;". This is usually necessary for feeds whose output is XML.)
%imagethumb% url to thumbnail
%imagethumb-ee% url to thumbnail after being run through encodeentities. (encodeentities converts all characters to their HTML entity equivalents. for example, "<" is converted to "&lt;". This is usually necessary for feeds whose output is XML.)
%stockYN% whether product is in stock (Y), Out of Stock (N), or not tracked (Y)
%stockqty% number on hand if product is tracked
%stockcode% stock level code if product is tracked (in, low, out)
%desc% product description
%desc-nohtml% product description stripped of html
%produrl% standard Miva Merchant url to the product screen
%produrl-ee% standard Miva Merchant url to the product screen, after being run through encodeentities. (encodeentities converts all characters to their HTML entity equivalents. for example, "<" is converted to "&lt;". This is usually necessary for feeds whose output is XML.)
%catcode% code of the first category this product is assigned to (the first one found in the database catxprod.dbf)
%catname% name of the first category this product is assigned to (the first one found in the database catxprod.dbf)
%catname-nohtml% name of the first category this product is assigned to (the first one found in the database catxprod.dbf), stripped of HTML
%catcrumbs% breadcrumbs-style hierachy of categories (Cat1 > Cat2 > Cat3) based on the first category assignment in catxprod.dbf (created for Froogle compliance)
%header% OUI product header or MMUI product header, depending on which UI module is in use
%footer% OUI product footer or MMUI product footer, depending on which UI module is in use
%oui-prodalt1% url to product alternate image #1 (OpenUI only)
%oui-prodalt2% url to (OpenUI only)alternate image #2 (OpenUI only)
%oui-prodalt3% url to (OpenUI only)alternate image #3 (OpenUI only)

In Category Template:

%code% category code
%name% category name
%ctgyurl% standard Miva Merchant url to the category screen
%ctgyurl-ee% standard Miva Merchant url to the category screen, after being run through encodeentities. (encodeentities converts all characters to their HTML entity equivalents. for example, "<" is converted to "&lt;". This is usually necessary for feeds whose output is XML.)
%header% OUI category header or MMUI category header, depending on which UI module is in use
%footer% OUI category footer or MMUI category footer, depending on which UI module is in use
%oui-treeimg% url to Category Tree Image (OpenUI only)
%oui-titleimg% url to Category Title Image (OpenUI only)
%oui-catalt1% url to category alternate image #1 (OpenUI only)
%oui-catalt2% url to category alternate image #2 (OpenUI only)
%oui-catalt3% url to category alternate image #3 (OpenUI only)

Default Feeds

Ultimate Feed Generator comes with 5 pre-defined default feeds. Note that Price Grabber and Froogle have additional requirements as described below.

Google XML Sitemap: Google Sitemaps is a service from Google that allows webmasters to submit links to individual pages within their site for spidering. According to Google, "The Sitemap Protocol allows you to inform search engines about URLs on your websites that are available for crawling." More information on Google Sitemaps can be found at http://www.google.com/webmasters/sitemaps/docs/en/protocol.html

The format for a Google sitemap is an XML vocabulary that specifies each URL, the date last modified, how often the page changes, and the relative priority within all the pages of your website. (Some of this information is optional and not available through Miva Merchant, so not included - namely, last modified.) When you run the Google Sitemap Feed from within Ultimate Feed Generator, the output is the fully-formed and compliant XML file that should be submitted to Google.

Because the output is XML, entities must be encoded. Therefore you will notice the use of special tokens such as %ctgyurl-ee%, which runs the category url through MivaScript's encodeentities function.

Froogle: Froogle is a shopping portal offered by Google. You can find the homepage at http://froogle.google.com, and merchant information is located at https://www.google.com/froogle/merchants/welcome. At the time of this writing, Froogle is a free service.

The Froogle format is simply a tab-delimited list of fields. To specify a tab in any template, use the special code "^T". Froogle requires that for every product, you include a category. They recommend using your own category structure instead of trying to match theirs. The default feed definition in Ultimate Feed Generator assumes this field will be stored for each product within an Extra Product Field as defined in our Extra Product Fields module. In the product template, you will notice this:

%module|extrafields|PRIMARYCATEGORY%

This is an OpenToken that calls our Extra Product Fields module for the current product, and returns the value of the extra field called "PRIMARYCATEGORY". It also assumes that Extra Product Fields is registered as an OpenToken with the code "extrafields". This is simply a default configuration. You may wish to change this to refer to another developer's extra fields-style module, or you can even hardcode a value if all of your products can use the same category.

PriceGrabber: PriceGrabber (http://www.pricegrabber.com/) is one of many shopping portals on the internet. Merchants can list their products and are charged on a per-click basis; the click price is fixed but depends on what category your products are listed in. The file format, like Froogle, is a tab-delimited file.

PriceGrabber requires several pieces of data that are not built into Miva Merchant. These are vendor name, vendor sku, and category. Unlike Froogle, PriceGrabber requires you to use their categories. The feed definition for PriceGrabber assumes you are using NetBlazon's Extra Product Fields module to define these values for each product. Review the Froogle definition above for additional details on using this method, or alternative approaches.

HTML Site Map: The HTML Site Map produces an HTML page that links to each of your products and categories. It has a simple design using CSS for positioning, and can be customized as needed. The result is a single point for search engine spiders to easily find links to every category and every product in your store.

Yahoo Site Submit: Yahoo! Site Submit allows you to specify a list of URLS that they should spider for inclusion in their directory. The purpose is similar to that of Google Sitemaps, but whereas Google uses XML for the file, Yahoo's format is a simple list of URLs in text format. For more information see http://submit.search.yahoo.com/free/request

Feed Template Library

You may of course modify the default feeds as needed, as well as create your own feeds! Our feed template library contains other sample feeds provided by NetBlazon and by customers using Ultimate Feed Generator. Please visit the library to get other sample feeds and to contribute your own feeds.

Support

For questions or problems with your Ultimate Feed Generator module, please send email to support@netblazon.com.