Mod Manager Overview

The TNG 10.1 Mod Manager uses an object oriented programming (OOP) strategy consisting of top-level control files and a library of supporting class definitions.

In PHP a class refers to a code structure similar to a standard function -- but it contains other protected functions, code and data within it. Invoking a class using the keyword "new," creates an "object" in memory and assigns a handle to it that is used to access all of its internal functions and data.

For those who are new to OOP, we will compare Mod Manager class files to TNG files later on, and you will see that Modbase and modparser classes serve the same purpose as TNG library files -- globallib.php and genlib.php.

A single object (in memory) may contain any number of classes. In the graphic, a modlister object is created by extending the modparser class and adding new functionality. Modparser is created by extending modbase and adding more new functionality.

A Word About Object Oriented Programming

A PHP class is executable code that creates a useful object in memory.

An object is an "instantiation" of a class in memory. It contains all the data and functions necessary to achieve some desired goal. An object can contain more than one class. This happens when you create a new class by extending an existing class. The new class object will have all the capabilities of its "parent" class, but will "extend" it with new capabilities and data. All functions and data will be accessed when the object is created. Here is an entire example of how the modinstaller is used:

   include 'classes/modlister.class.php';
   $oModlist = new modlister( $objinits );
   $oModlist->filter = $filter;
   $oModlist->fbox_checked = $fbox_checked;
   $oModlist->set_options( $options );
   $oModlist->list_mods();

The first line gets the relevant class definition script
The second line creates a new modlister object with handle $oModlist
Third line tells the object what filter is currently applied.
Fourth line tells it whether the filter check box is ticked.
Fifth line sets user options.
Last line lists the mods.

From a top level perspective, that's all it takes to create the main listing page. Notice that the class modinstaller, like all Mod Manager classes, requires an argument -- $objinits, which is an array of information needed to initialize the object. You can see what the array consists of by looking at admin_modmanager.php.

By the way, "Instantiation" is a word intended to impress your less knowledgeable friends. Use it as often as possible. It refers to a class whose code has been installed in memory and has a handle ready for your program to use.

Object oriented programming has been around a long time because it provides some useful benefits. By design, an object encapsulates (protects) all of its data and methods (functions). It prevents collisions with other external functions or variables that might have the same names.

OOP is often used by large teams of programmers working on a common project. If you are leading such a team, you might issue classes with generalized functionality and instruct your programmers to extend those classes as needed, but never ever modify them. If they modify the base classes, their own code may continue to work, but code created by others using those classes will likely fail.

Mod Manager v10.1.0 uses this ability to extend base classes as if they were php libraries to share data and reuse common code. Its lowest level class, Modbase, is extended to created Modparser, a new class which has all the common data and functions of Modbase, plus new functions to parse mod configuration files. The Modparser class is extended further by Modlister, which adds functions to display the Mod Manager main page. Likewise, Modinstaller extends the parser class to install mods

OOP Classes vs. Old Style Modules

Caption

Relationship Comparison of OOP Mod Manager and TNG Files

The control file, admin_modhandler.php, is found in the TNG root directory. It is the master script that orchestrates all the functionality of Mod Manager.

Mod Manger Control Files

Control files exist in the TNG root directory and are as follows:

admin_modmanager.php	Provides the main page with mod listing.
admin_showmodslog.php	Display the MM results log.
admin_showmodoptions.php	Editor for MM configuration options.
admin_analyzemods.php	Optional tool for mod developers.
admin_updatemodoptions.php	Updates configuration file when options are changed.

Mod Manager Classes

Class definition files are together in the classes folder in the TNG root directory. They are used by first "instantiating" or creating them as objects using the "new" keyword, setting options, and calling on their available functions to perform Mod Manager tasks.

Some Comparisons with OOP

Functional programming	Object Oriented Programming
No functional programming eqivalent	A class object is "instantiated" -- created in memory -- and its handle is used to access its functions. For example, $obj = new modlister, creates a new modlister object with handle "$obj."
Common functions can be made available by including a library like genlib.php in TNG.	Common library functions can be part of a "base" class, which is "extended" by other classes that need them.
Invoking a function is familiar to all of us; for example set_options($options).	Outside the object a function is invoked using the object handle: $obj->set_options($options); inside the class: $this->set_options($options);
A global variable must be declared in every function that uses it.	A public OOP variable can be accessed outside the object using $obj->myvar; or anywhere internally using $this->myvar.
Scope or visibility of functions and variables is determined by the rules of PHP	Scope of functions and variables, both internal and external to the object, is determined by the programmer: Public - available externally, and internally by all classes Protected - shared internally by all extended classes; not visible externally Private - only available within the class; other classes in the object do not see them

Class Functions

The Mod Manager class names suggest their functions

• Modbase is a common, low level library of functions and data available to all other mod handling classes when they extend themselves from it.

• Modparser is responsible for parsing Mod Manager configuration (cfg) files. It creates various tables with parsing results, warnings and errors for use by any class that extends from it. Modparser extends from the Modbase class.

• Modlister is responsible for creating the main Mod Manager listing page. It parses each file in the "mods" directory and displays them with their mod name, file name, version number and operational status. Modlister extends the Modparser class.

• Modinstaller is responsible for installing a TNG Mod, either singly or as a batch. Modinstaller extends the Modparser class.

• Modremover is responsible for removing all the components of a TNG Mod, either singly or as a batch. Modremover extends the Modparser class.

• Modeditor is responsible for allowing users to change installed mod configuration options. Modeditor extends the Modparser class.

• Moddeleter is responsible for deleting mod (cfg) files from the server. Since no content parsing is necessary it extends directly from the Modbase class without useing the Modparser.

Processing Config Files

First, modparser reads a config file into a string buffer. Then all the various forms of line endings are converted to the mod manager standard -- CRLF. Modparser breaks the string into an array of lines, each one still containing the CRLF at the end.

Modparser then goes line by line and creates a list of all the config file tags -- each tag record includes the line number, raw code, tag name, and the associated arguments. Arguments may be file names or blocks of code that follow a %location:% or follow an operational tag such as %triminsert:%. All tags are listed in the order encountered in the config file.

Modparser also places required info header items like %name:%, %version:% and %description:% in persistent memory and creates lists of warnings and fatal errors.

Anything in the warnings list gets displayed by modlister if the option is set to report them; otherwise it is ignored.

In processing parse tables (lists), only three kinds of mod manager tags are processed:

1. %target:%
2. %location:% and
3. file ops copyfile, %copyfile2:% and %newfile:%

%target:%

When a %target:filname% tag is encountered:

• the file is opened and put into a string buffer;
• all the line endings in the buffer are standardized as CRLF
• a flag is set indicating there is an active target file open.

%location:%

When a %location:% tag is encountered the module looks to see if there is an open target file, then processes the target code block and the insertion or replacement code block according to the op directive.

File Operations

Whenever a file copy or newfile tag is encountered it is processed.

Parameters

Mod Manager uses tag %parameter:% to set up variable values in one or more target files that control behavior of the mod. For example, a variable $no_border in a file that displays a screen of information may have values 0 or 1, depending on whether the user wants to display a border or not.

The %parameter:% tag is always placed inside a %target:% section. It gives the variable name and reflects it's current value.

It must be followed by a %desc:% tag containing a description of what the variable does, what different settings might mean and a default value in parentheses. Obviously nothing else inside the %desc:% tag text may be surrounded by parentheses.

On installation nothing is actually done with this pair of tags. If present, Modlister provides a button to "Edit Options" in the status panel. When clicked it brings up the Mod Editor feature. The editor reads the config file and gathers information about the parameter for each target. Then it goes to the target files and finds the current values of the parameter variables and displays them for modification. If the user modifies a parameter, the Mod Editor replaces its value in the target file. It also replaces its value in the cfg file to prevent bad target errors if the variable itself was installed by the mod.

Logging

Errors and status information is collected during the processing and written to the log by the high-level Mod Manager Functions.

Related Links

Mod Manager

• Overview
• Why Use It ?
• Installing Config Files
• Batch Updates
• Interpreting Status
• Editing Parameters
• Deleting Mods

Mod Manager Controls

• Mod Manager Options

For Mod Developers

• Mod Guidelines
• Mod Manager Syntax
• Creating Config Files
• Config File Creation Example
• Avoiding Mod Conflicts
• Using the TNG File Analyzer
• Mod_Manager_Enhancements_TNG_v12

Technical

• Technical Overview
• Technical Directives
• Quick Reference
• Inside Mod Manager v12

Developer Tools

• Notepad++ Mod Manager Language

Example Mods

• Managing Configuration Files
• Managing Stylesheet Overrides