Blog Magic

Introduction

The Blog Magic module allows your Miva store to generate blog feeds of new products or other information that you wish to publish. The module is easy to set up, and can generate a variety of different feeds with no additional editing or data entry:

• Newest products in the store
• Newest products in a specific category
• Multiple feeds of newest products in many categories
• Feeds of articles or other types of content

This document describes how to install, set up, and use the module. After reading the document, if you have additional questions, you can contact Magic Metal support at the Web site.

What is a blog feed, and why do I want one?

A blog is a sort of Web-based journal or diary. It's a way for an author to generate a series of articles or other content, without needing a lot of Web-design skills. Blogs are generally designed to make it easy to add new sections of content. The content sections have a fairly simple format: they typically consist of a title, some text, a single image, and possibly a link to some other Web page for more information. Articles are usually displayed to readers in reverse chronological order, so that the newest ones are displayed first. This is convenient for frequent readers, who can always get quick access to the latest articles.

For an on-line store, a blog is a good way to communicate with your customers. You can give them quick notifications about new products, without them having to browse through different categories. You can also use your blog to announce special discounts or promotions, and to publish news or other articles that may be of interest to your customers.

Some people read many different blogs on topics of interest; so they use a feed reader program to help them manage their blogs. These programs typically keep track of the last time the user read a blog, so they can quickly display only the latest content, the material thhat the user hasn't already seen. A feed reader can download articles from multiple blogs with one click, organize them, save some articles for later use, etc.

Most blogs can be read with a Web browser; but for feed-reader programs, there are other data formats that work better than the HTML language of Web pages. If a Web site displays a blog page, it probably also has a feed that provides the blog content in a different format, intended for use by feed readers. The most common feed formats are called RSS and Atom. The differences between them are minor; most feed readers support both types. Blog Magic comes with page templates for both RSS and Atom feeds, as well as an HTML template to create a blog page that Web browsers can read and display.

See Blog Magic in action

The Magic Metal Web site has a blog that is generated by Blog Magic. You can view it using your browser or a feed-reader program. You can view the RSS feed using a traditional long-form Miva URL:

http://themagicm.com/mm5/merchant.mvc?Screen=BLOG_RSS

Miva's URI Management features have been used to allow a shorter URL:

http://themagicm.com/rss

The Atom feed is available at http://themagicm.com/atom.

For users who prefer viewing the blog with a browser, an HTML blog page is available at:

http://themagicm.com/blog

The format of this page is extremely simple and "plain vanilla." It is generated by an unedited copy of the HTML feed template that is included with your copy of Blog Magic. If you use the template in your own store, of course, you can customize it with fonts, colors, page header and footer, etc., to make it look more professional and match the rest of your store.

Installation and setup

Several steps are required to get Blog Magic up and running in your store:

• Install the module.
• Create a feed page template.
• Set the module's admin settings as needed for your intended type of feed.
• Create links on your store pages so that users can access the feed.

Installing the module

The procedure for installing this module is the usual one for Miva Merchant modules: add the module to the Merchant domain ("mall"), and assign it to the store. You will also need to enter your license key code, and create one or more page templates for the module to use. The procedure is explained below in a bit more detail. If you need more information, see your Miva representative or documentation.

To install the module in your domain, follow the steps below:

1. Log in to the Miva Merchant Administration page, pull down the main menu, and select Modules. Your browser will display the Modules list page.
2. Click the + button near the upper right corner to add a new module to the store.
3. On the Add Module page, click the Upload button.
4. On the Upload pop-up, click the Browse button.
5. Use the File Upload dialog box to navigate to the folder on your computer where the module file is stored, and to select the file for uploading. The exact procedure for this will vary, depending on your computer's operating system and browser. When you have selected the file, the dialog box will close.
6. On the Upload pop-up, click the Upload button. Your browser will upload the file, and after a few moments, the pop-up will close.
7. On the Add Module page, click the Add button to add the module to your Miva domain.
8. Pull down the main menu, and select Utilities.
9. On the Utilities page, select Add/Remove Modules. (You may need to pull down the menu to see it.)
10. On the Add/Remove Modules page, find the entry for Blog Magic (you may need to scroll down to find it) and click the Install button. Your browser will display the module's settings page.
11. Near the top of the page, you will see the text box to enter your license key code. You should have received this code in an email when you purchased the module. Enter your key code in the text box, check the Agreement box, and click Update to register the module.
12. Check the Enable checkbox and click Update. With the other admin settings in their newly installed state, this will allow Blog Magic to generate a basic feed of the 20 newest active products in your store. You can now start testing the module and adding feed links to your store pages. Once you have verified that the module is working properly, you can change the admin settings to generate other types of feeds that you may prefer.

Creating feed pages

After installing the module, you will need to create one or more page templates for the module to use. Two page templates are included with the module: one for RSS format, and one for Atom.

1. Log in to the Miva Merchant Administration page, pull down the main menu, and select User Interface. Your browser will display the Pages list page.
2. Click the + button near the upper right corner to add a new page to the store.
3. Enter a code and name for the new page.
4. Copy and paste the text from one of the provided templates into the Template box.
5. Click the Add button to create the page.
6. Click the Items link near the top of the page, to view the Items list.
7. Pull down the View menu (the icon shaped like an eye, near the upper right corner of the page) and select View All.
8. Find the entry for the blog Item, by scrolling down or using the Search box.
9. Click the gray slider button. It will turn green to indicate that the Item is assigned to the page.

If you want to create additional templates, e.g. to support both Atom and RSS formats, repeat the above steps for each template.

Creating feed links

In order for customers to use your feeds, you need to create links to the feeds on your store pages. The basic format for one of these URLs is the same as for links to other store pages. The links will include the page code for the feed page that you created. For instance, if you created a page for an RSS feed, and you used the page code BLOG_RSS, then a link to the feed will use a URL something like:

http://YourStore.com/mm5/merchant.mvc?Screen=BLOG_RSS

(The exact form of the URL will depend on your store's configuration.)

If your store uses Miva's SEO Settings or URI Management, the URL may look more like:

http://YourStore.com/page/BLOG_RSS

Or something as simple as:

http://YourStore.com/rss

If you're not sure of the URL format, you can experiment by typing different URLs into your browser's address bar, until you get one that produces a result. (Be sure to complete the module setup before you try this, so that the module will be able to generate a feed.)

Once you have the correct URL, you can write a link into any page template. If you put the link in the global header or footer, it will automatically be displayed on most of your store's pages. If you put it on the Category (CTGY) page template, it will be displayed on all category pages.

The simplest format for a link is to use a word or phrase as the link content, such as:

<a href="http://YourStore.com/mm5/merchant.mvc?Screen=BLOG_RSS">Click here to view the RSS feed</a>

It's more common to use a small image for the link, instead of text:

<a href="http://YourStore.com/mm5/merchant.mvc?Screen=BLOG_RSS"><img src="rss_public_32.png"></a>

Tip: Blog Magic comes with several image files containing the orange and white "broadcast" logo that is commonly used to identify blog feeds. The image is provided in several small sizes, as well as a high-resolution 256 x 256 that will be a good image to start with if you want to create other sizes.

Creating links for multiple feeds

The above link format will work if your store only has a single feed. But Blog Magic lets you set up a separate feed for every category in your store. If you're going to use that feature, your feed links will need another URL parameter to specify the category.

You can choose the name of this URL parameter: a keyword such as blogcat, or an abbreviation such as BC or CAT, etc. Enter your chosen parameter name in the Category selection text box on the module's admin page, and check the Allow checkbox.

Once you've chosen your parameter name, you can write URLs that include it. For example, suppose your store sells DVDs, and one of the categories has the code DRAMA. You can write a URL that will feed this category in the form:

http://YourStore.com/mm5/merchant.mvc?Screen=BLOG_RSS&blogcat=DRAMA

The &blogcat=DRAMA parameter is added at the end of the URL. Instead of blogcat, of course, you will write whatever parameter name you entered on the module's admin page. In place of DRAMA, you will write one of your own category codes, or possibly a Miva template variable such as &mvt:category:code; or &mvt:global:Category_Code; .

Using the module

Blog Magic generates feeds that consist of the newest products in your store. But it can be used in several different ways, depending on the admin settings:

• One feed of newest products in the store: the simplest type of feed.
• One feed from a single category: you can set up a category specifically for New Products, Featured Products, or for articles, news updates, and other content.
• Separate feeds from multiple categories: let your customers subscribe to their favorite categories. Then they can get news of new products in just those categories, instead of the whole store. This option also allows you to set up one feed for new products, and another for articles.

Feeding articles and other non-product content

Blog Magic is intended mainly for generating feeds of products in your store; the text and images are the same as the ones displayed on your store's shopping pages. But you may prefer to generate a feed of articles, announcements, or some other type of content that's not ties to specific products.

Blog Magic supports this type of feed, with some creative use of admin settings. You can set up products which are not actually for sale; they are just "carriers" for blog articles.

• The product's name will be the title of the article.
• The product's description will contain the article text. You can use HTML formatting here to create subtitles, tables, etc.
• The product's main image will be displayed with the article.

To create a blog that consists entirely of non-product articles:

• Follow the above steps to create products that carry the content for each article.
• Create a new category for your articles, and assign all the article-carrying products to this category.
• Create a feed link that will generate a feed for this category, and put it on one or more page templates.

Once you've completed these steps, users who click the link will receive a feed of your articles.

Feeds with inactive products and categories

If you create non-product articles as described above, you might find that they cause some conflicts with other parts of the store. For instance, they may show up in search results; and if customers click on them, they may see the article displayed like a normal product, with an Add To Basket button on the page. To prevent this type of conflict, you can make your article-carrying products inactive (by un-checking the Active checkbox setting). Once you've done that, the store will not display them in search results, or on any other shopping pages.

Categories, like products, have a checkbox setting to make them active or inactive. If you set make your articles category inactive, it will not be displayed to customers, and there won't be any links to it in your store's navigation menus.

The decision to use inactive products or categories will depend on how you want to use your blog, and how much page editing you want to do. If article-carrying categories and products are active, they can be viewed on the shopping pages. As mentioned above, this might cause some odd behavior, such as displaying Add To Basket buttons. But you can write <mvt:if> and <mvt:else> elements in your page templates, so that they will change their appearance when displaying articles.

Having blog content available on the shopping pages can be helpful, but it takes more work to edit your page templates for that. You may prefer to just make the article-carrying products inactive, so that they're available only through the feeds. In that case, in order to make inactive products visible on the shopping pages, you can set up an HTML blog page using the template that was provided with Blog Magic.

Module settings

Blog Magic's admin page is in the Utilities section of the Miva admin pages. To get to it, pull down the main menu and select Utilities. You may see the "tab" link for Blog Magic at the top of the page; if not, you can find it by pulling down the menu.

This page contains the settings that control the module's overall operation. After making any changes, be sure to click the Update button at the top of the page.

The functions of the settings are described below. For more information on how to use the settings, see the section on Using the module.

Enable

This checkbox functions as a "master On/Off switch" for the entire module. If this box is unchecked, all module features will be disabled on the shopping pages, and no feeds will be generated. Check the box when you want the module to be operational for customers.

Default category

If you want to use the module to generate a feed from a single category, enter the category code here. If you leave this box empty, the module will generate a feed of all products in the store, or of specific categories selected by a URL parameter.

Category selection

If you want to allow the module to generate multiple feeds, selected by a URL parameter, check the Allow checkbox, and enter the name of the parameter in the text box. If the box is unchecked, the module will not use a URL parameter for category selection; in that case, the selection is controlled by the Default category setting above.

Number of products

Enter the number of products that you want to include in each feed.

Include inactive products

The module can generate feeds that include all products, or only active products, depending on these setting. There are three options.

• No: feeds will only include active products.
• Yes: feeds will include active and inactive products.
• Only for specified categories: inactive products will be included in feeds from the categories listed in the text box. For other categories, or for an all-products feed, only active products will be included.

Default selected products

As a convenience, the module displays a list of the newest products in the store. The list will be filtered by the settings for the default category and inactive products. So it will show the products that feed will display (except when a URL parameter is used to select specific categories for feeds).

Testing and debugging settings

These settings are intended for use when there are problems related to the module. You probably won't need to use them at all; but if any problems develop, these settings will help a developer to solve them. The descriptions below are somewhat sketchy, intended mainly for use by experienced developers.

Write log file

If this box is checked, the module will write a log of its activities in a plain-text file. The file's exact name and folder location are displayed next to the checkbox. You can read this file with FTP.

Testing mode

This dropdown menu has options for Normal and Restricted. In Restricted mode, the module will only generate feeds for registered test users (see below). For other customers, the module will be inactive. In Normal mode, the module will generate feeds for all users.

Debugging messages

The module has the ability to produce "dumps" of internal data on the browser screen. These data dumps can disrupt the page layout, so they should not be seen by your customers.

This dropdown menu has three options. In Normal mode, the module doesn't display any debugging messages. In Restricted mode, the module displays debugging messages only for registered test users, and on the admin pages. In Verbose mode, the module displays debugging messages for all users.

Error messages

The module has a number of options for handling internal error messages. These are messages that refer to corrupted data or other problems within the module, not the messages that are displayed to customers for errors such as an incorrect password or missing Zip code.

• The module can write the errors to its standard log file, or to a special log file just for error messages.
• The module can display the error messages on the browser screen. This is helpful during testing and debugging. For normal operation, you probably shouldn't display these error messages on the screen, because they may be confusing to customers.
• The module can send an email to notify you or your staff of the error.

Test users

To register yourself as a test user, enter your IP address or customer-account login in the text box. If you enter a login, of course, you must log in to that account to be recognized as a test user. For convenience, your IP address is displayed to the right of the text box; and there's an Add Me to the List button that you can click instead of typing.

Page template variables

Blog Magic provides a number of variables that can be used in page templates. These variables contain the article text and images, as well as other information about the blog and other features of your store.

The variables are lsited below. Some of them may or may not be needed for your store; that will depend on what format you choose, and whether you are displaying regular products or non-product content such as articles. You can find examples of the variables' usage in the three feed templates (RSS, Atom, and HTML) that were provided with Blog Magic.