EDK3 Modding

[mastergamer]

**If you don't care how it works, and just want to see how to make mods, skip down to the 'Creating a mod' section below.**

Some Background
EDK3 contains a brand new way to add, remove and replace content on the core pages. You no longer have to worry about choosing between two mods that affect the same page, or merging the changes from one into the other so they'll both work together.

The core pages now use what's called pageAssembly to arrange their content in a way that makes it much easier for mod developers to customise. The pageAssembly system works by building a list of all the content that the core wants to put on the page, firing an event saying "I'm done, do any mods want to change anything?", and then generating and outputting the page's HTML. Each page will generally do this twice; once for the content and once for the context (menus, top killer boxes etc).

If you look at common/home.php, near the top you'll see a block of code that looks like this:

Code: Select all

class pHome extends pageAssembly
{
	function __construct()
	{
		parent::__construct();
		$this->queue('start');
		$this->queue('summaryTable');
		$this->queue('campaigns');
		$this->queue('contracts');
		$this->queue('killList');
		$this->view = preg_replace('/[^a-zA-Z0-9_-]/','',$_GET['view']);
		$this->viewList = array();

		$this->menuOptions = array();
	}

All core pages now subclass pageAssembly, and use the inherited functions to queue up content.

Code: Select all

$this->queue('summaryTable');

The order that the queue() calls appear is important - the content will be placed on the page in that order. The above line of code tells the assembler that the second content block on the page is referenced by the ID 'summaryTable', and it's content is generated by calling $this->summaryTable().

Creating a mod
You need to know two things before you start. First, you need to know what page (and thus event) you want to hook into, and second you need to know which content block you want to add content before/after/on top of.

To find the event name you want to hook into, simply open the php file for the page and scroll down to the bottom. You'll see two (or one) lines like this:

Code: Select all

event::call("home_assembling", $pageAssembly);
event::call("home_context_assembling", $pageAssembly);

There is also a list of events maintained here: http://eve-id.net/forum/viewtopic.php?f=1012&t=17006.

For this tutorial I'm going to assume that you want to add a graph to the Home page's content (rather than context) right after the summaryTable. That means the event you're after is 'home_assembling', and the content block is 'summaryTable'.

Something that you should know about mods is that every mod can have an init.php file that is executed every time any page is loaded. The init.php file for your mod is where you will hook into the desired event.

The Code

I'll show you the code now and then explain it. Note that the graph generation code is taken from the inet_mod.

Code: Select all

<?php
event::register("home_assembling", "GraphMod::addHome");

class GraphMod
{
    function addHome($home)
    {
        $home->addBehind("summaryTable", "GraphMod::graphHome");
    }
    
    function graphHome($home)
    {
        if (file_exists("charts/MSColumn3DLineDY.swf"))
        {
            require_once('mods/graph/grafico.inc.php');

            $html = VisualizzaGrafico(GeneraDatiGrafico($home->getWeek(), $home->getYear()));
        }
        return $html;
    }
}
?>

The first line registers the GraphMod::addHome() function to the home_assembling event (the assembler will always make static calls to your functions, so DON'T use $this in them). When the Home page fires it's home_assembling event the assembler will look at the list of functions registered to it and call them in turn.

Any function registered to an event can have one optional argument. All core pages will pass a reference to their pageAssembly object when they fire events.

Code: Select all

$home->addBehind("summaryTable", "GraphMod::graphHome");

This line tells the assembler that you want to add content behind (after) the 'summaryTable' block, and that content is returned by calling the GraphMod::graphHome() function.

Functions that will be called by the assembler can also take one optional argument which will always be a reference to the assembler instance that calls your function (a page in most cases).

The graphHome() function simply includes the code that contains the graph generation functions and then generates the graph HTML. Any function that is called by the assembler is expected to return some HTML that will be added to the page.

Some Extras
If you want to use Smarty in your mod then you should do something like this:

Code: Select all

function generateSomeContent($forThisPage)
{
	global $smarty;
	
	$smarty->assign("yourTemplateVar", "Some sample content.");
	$html .= $smarty->fetch("../../../mods/your_mod/your_template.tpl");
	return $html;
}

There are other methods other than addBehind(). There's addBefore() that rather unsurprisingly adds content before another block, replace() which will replace the block with your own, delete() which deletes a block, and filter() which allows you to edit the content of a block (such as underlining everything or removing a certain word etc).


Hopefully this makes modding for EDK3 somewhat clearer and highlights the benefits of this new system. If you've got any questions then post them here and I'll do my best to answer them.

[beansman]

Nice post.

Someone else made a post with all the events and where they occur, might be worth including:

http://eve-id.net/forum/viewtopic.php?f=1012&t=17006

[mastergamer]

Added.