MrRat's Amazon Products Feed
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
For the more technically minded here is the science (code actually):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.
| 1. Upon loading | The script retrieves a list of all the mod files stored previously by the config_script into the @mod_files array. |
| Line 1: | This piece of voodoo retrieves the name of the current sub: $this_function = (caller(0))[3]) =~ s/[^:]+:://; |
| line 2: | Each sub that is plug-in enabled cycles through each named modfile in the @mod_files array. |
| Line 3: | The script identifies a hash with the name 'subs__' followed by the name of the modfile. This is basically a list of subs which the modfile wants to hook into. |
| Line 4: | [$mod_use is created and managed by the config script] If the the current mod being checked was enabled by the admin from the config script - and that mod is set to hook into this sub then the sub named name-of-original-sub '__' the-name-of-the-mod-file (within the mod file) is run Then: IF the mod is enabled (by the config script??) AND the mod file identifies This current Sub as one to be hooked into ( ${$hash_name}{$this_function} eq "Yes" ) THEN run a sub named name_of_original_sub '__' followed by the name of the mod file. |
Which parts of MrRat's script can we hook into.
Main Control Structure of MrRat's Script.
| # make it so | |
| get_url_input(); | # Yes - if there is a query string. |
| initialize_locale(); | # Yes |
| load_language(); | # Yes |
| initialize_hashes(); | # Yes |
| START_PROCESSING_LABEL: | |
| calculate_initial_variables(); | # Yes |
| build_products(); | # No |
| build_the_page__main(); | # Yes - just before HTML is printed. # but too late for automatic inclusion of changed or new $MY_variables. |
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.
