APF Modification File System

In this document I will attempt to expain the new external modification system that MrRat, the developer of Amazon Products Feed, has integrated into the newly released APF Version 4.

Background to this document:

I have been programming with PERL for maybe 6-8 weeks, so when OneClick showed me the code snippet that appears below by way of an introduction to the system of modification files or Mod files that MrRat is implementing in APF4, I was stopped dead in my tracks.

I set about analysing the code line by line in order to pose more questions. By the time I had a handle on what the code was doing, I was sure that many others would have questions to ask.

This document is intended to introduce the Mod file system to people who can already program in PERL. You do not need to be an 'advanced' level programmer like MrRat, but if you have hacked around in other people's PERL scripts in the past, then this document should be enough to get you started.

If you still have questions at the end, post them in the Mods forum at this address: http://www.absolutefreebies.com/phpBB2/ we will do our best to answer them, and if necessary alter / modify this document to clarify any issues arising.

Below we will look at the following questions:

• What are mod files Why would you want to build / use a mod?
• How are mod files implemented?
• Which parts of MrRat's script can we hook into?
• What variables are available for use in mod files?
• I didn't understand any of that - can you explain some PERL to me?

What are mod files Why would you want to build / use a mod?

A mod file or modification file is a piece of code that alters the way that MrRat's APF script works.
Why would anyone want to change the way mrRat's script works?
Well, there are only two reasons really, but they are good ones:
The primary reason is to add extra functionality.
Possible implementations:

• Logging pages / products viewed.
• Reformatting ALL the URLs on a page - to support Apache server's MOD_ReWrite
• To create extra elements to add to the page - eg recently viewed products.
  • eg 1. you could have a different stylesheet for each locale, or each SearchIndex (Electronics,DVD)
  • eg 2. you could have a descriptive piece of text that varied by locale or SearchIndex (Books, Music, etc.)

The second reason is to easing the process of upgrading from one version of the script to another where modifications have been made. With previous versions people would invest a lot of time and energy editing the main script file with their own modifications. Then when the next bug fix or upgrade was released they would have to replicate all of those changes in the new script. The new system externalises this process - making modifications modular. The core script can be upgraded as many times as is necessary without losing any modifications - or sleep.

So how is this done.

As each of the subs within MrRat's APF script executes, it checks whether any of the loaded mod files want to hook into the process at that point. Any correctly constructed Mod file can hook into any number of subs as long as the subs themselves are enabled.

Warning Technobable ahead

Many areas of MrRat's code contain this piece of code
Line 1:  (my $this_function = (caller(0))[3]) =~ s/[^:]+:://;
Line 2:  foreach my $item (@mod_files) {
Line 3:      my $hash_name = qq[subs__$item];
     3+           my $sub_name = $this_function . "__" . $item;
Line 4:      if ($mod_use{$item} eq "Yes" and ${$hash_name} 
     4+    {$this_function}  eq "Yes") {&{$sub_name}; }
Line 5:  }
 

Let me try and walk you through what is going on here - anyone who wants to correct me can feel free to jump in here.

Which parts of MrRat's script can we hook into.

Main Control Structure of MrRat's Script.

Variables available to mod file builders:

%MY_variables;
%AWS_variables;
%Internal_variables;
%FORM;
%store_to_browse;
%catalog_to_mode;
%lookup_store;
%lookup_browse_id;
%$level_1;
%$level_2;
%$level_3;
%$level_4;
%no_image_image_hash;
@mod_files;
@months;

%MY_variable     TYPE: hash or associative array
This is the main mechanisms for storing HTML and text for display 
in the final page. Anything created in here is available for use 
in templates
 
$MY_variables{name-of-variable} can be used in templates as 
%%name-of-variable%%
 
%Internal_variables
 
Holds control variables - FLAGs, and other vars used to 
store info.
eg. location of the MODS directory is 
$Internal_variables{mods_directory}
 
@mod_files - Type Array.
 
Holds a list of mod files found in the mods_directory.

I didn't understand any of that - can you explain some PERL to me?

There is not room here for a full tutorial on PERL programming.

If you know what a hash or associative array is then you are good to go. If not, then try these resources for more in-depth information on PERL programming.

A fairly complete list of Perl functions and keywords

The Perl Cookbook - code snippets that complete specified tasks, together with some useful commentary. Type perl tutorial into your favourite search engine.

Related links

If you want to see an example of a Mod file click here.
Read the Mod file tutorial click and build your first mod file.
See documentation on my Mod files.
See the central repository for Mod and Template files - APFMods.com .
Latest version of MrRat's APF - details: MrRat.com/aws file: here.
Support for MrRat's APF and ALL available Mods and Templates click here.