Events

An event is a little blob of data saying "something happened", possibly "something happened, here's the specific data". Events are sent with the send_event() function. Since events can store data, they can be used to return data to the extension which sent them, for example:

$tfe = new TextFormattingEvent($original_text);  // create an empty event
send_event($tfe);                                // broadcast it to the world
$formatted_text = $tfe->formatted;               // see what it brought home

Extensions

An extension is something which is capable of reacting to events.

// ext/make_text_bold/main.php
class MakeTextBold extends Extension {
    public function onTextFormatting(TextFormattingEvent $event) {
        $event->formatted = "<b>" . $event->formatted . "</b>";
    }
}

Configuration

// ext/make_text_bold/config.php
class MakeTextBoldConfig extends ConfigGroup
{
    // must match the KEY in Extension / ExtensionInfo
    public const KEY = "make_text_bold";

    // ConfigMeta is used to automatically generate the Board Config page.
    // The const name is how to refer to this setting within the code.
    // The string can be anything unique, but shouldn't be changed because
    // it ends up being written to and read from the database.
    #[ConfigMeta("Font Size", ConfigType::INT, default: 10)]
    public const FONT_SIZE = 'make_text_bold_font_size';
}

Useful Variables

There are a few global variables which are pretty essential to most extensions:

• $config -- some variety of Config subclass
• $database -- a Database object used to get raw SQL access
• $page -- a Page to hold all the loose bits of extension output
• $user -- the currently logged in User
• $cache -- an optional Cache for fast key / value lookups (eg Memcache)

Each of these can be imported at the start of a function with eg "global $page, $user;"

The Hello World Extension

Here's a simple extension which listens for PageRequestEvents, and each time it sees one, it sends out a HelloEvent.

// ext/hello/main.php
public class HelloEvent extends Event {
    public function __construct(string $username) {
        $this->username = $username;
    }
}

public class Hello extends Extension {
    public function onPageRequest(PageRequestEvent $event) {   // Every time a page request is sent
        global $user;                                          // Look at the global "currently logged in user" object
        send_event(new HelloEvent($user->name));               // Broadcast a signal saying hello to that user
    }
    public function onHello(HelloEvent $event) {               // When the "Hello" signal is received
        $this->theme->display_hello($event->username);         // Display a message on the web page
    }
}

// ext/hello/theme.php
public class HelloTheme extends Themelet {
    public function display_hello(string $username) {
        global $page;
        $block = new Block("Hello!", DIV("Hello there $username"));
        $page->add_block($block);
    }
}

// themes/my_theme/hello.theme.php
public class MyThemeHelloTheme extends HelloTheme {     // MyThemeHelloTheme overrides HelloTheme
    public function display_hello(string $username) {   // the display_hello() function is customised
        global $page;
        $page->add_block(new Block(
            "Hello!",
            DIV("Hello there $username, look at my snazzy custom theme!")
        );
    }
}