What Is A Mod File

APF Modification File System

In this document I will attempt to explain the external modification system that MrRat, the developer of the Amazon Products Feed perl script, has integrated into APF since the release of 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 and 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:

Add extra functionality.
Change current functionality

Possible implementations:

Logging pages / products viewed.
Reformatting ALL the URLs on a page - to support Apache server's ModRewrite
To create extra elements to add to the page - eg truncate longer elements to create custom template variables.

Because a mod file is a piece of script it can evaluate options and produce output based on an:

If ... then ... else ... structure.

Think of the possibilities - if I can grab this variable I can have different output conditional upon the value of xyz. Just think of the possibilities:

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.)

Another benefit of the mod file system - externalise your edits

Previously if you wanted to edit the output of the APF script you would 'hack' the script with your custom code - but if you changed to a new version you lost your edits or you had to spend hours (or days) combing through the old code to identify your edits ready for copying them across to the new version. Hacking the script created an obvious impedement to upgrading.

Implementing edits via mod files overcame this impediment. You simply install your mod file into the new version of the script and activate it in the config screen and it continues to work - usually.

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 modification file 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 do mod files work?

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

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.

get_url_input(); # Yes - if there is a query string.initialize_locale(); # Yesload_language(); # Yesinitialize_hashes(); # YesSTART_PROCESSING_LABEL:
calculate_initial_variables(); # Yesbuild_products(); # Nobuild_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 - the main data structure for template variables and script output
%AWS_variables - the data structure that holds raw data sent by Amazon
%Internal_variables - mainly internal variables and flags used within the script itself
%FORM - the query string and form submission data passed to the script

%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.

APF 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.

APF Bridge Demo And Development Site