Nameless 2.0 Module Developer Documentation

Greetings, developer!

This guide assumes intermediate PHP knowledge. If you do not know PHP and want to make NamelessMC modules, we highly recommend you learn the basics first - rather than jumping right into this.

All modules require at least one file to work, named init.php. This file must be placed in modules/<your module name>/init.php. Each time a page loads, NamelessMC will detect this file and execute the code inside of it automatically. It is recommended to separate your init.php file and your module's main class, most people make the main class in a file called module.php.

In your init.php file, you must create a new instance of your module's main class, which must extend the Module class. For example:

<?php
// Demo module by Aberdeener
// init.php file

require_once ROOT_PATH . '/modules/DemoModule/module.php';
$module = new Demo_Module();

<?php
// Demo module by Aberdeener
// module.php file
// Absolute minimum in terms of code, this has no functionality

class Demo_Module extends Module {

    public function __construct() {

        $name = 'Demo Module';
	$author = 'Aberdeener';
	$module_version = '0.0.1';
	$nameless_version = '2.0.0-pr8';

	parent::__construct($this, $name, $author, $module_version, $nameless_version);
    }

    public function onInstall() {
    }

    public function onUninstall() {
    }

    public function onEnable() {
    }

    public function onDisable() {
    }

    public onPageLoad($user, $pages, $cache, $smarty, $navs, $widgets, $template) {
    }

}

You will notice that when your module's main class extends the Module class, it is required to have some functions in it. These functions are as follow:

• onInstall();
• onUninstall(); (Not used yet:tm:)
• onEnable();
• onDisable();
• onPageLoad();

Their names are fairly understandable, they will each be called when that action happens. Obviously, most of your module's core code will be in the onPageLoad(); function, as that is called every time a page is loaded.

In your module's constructor, this is where you will want to:

• Initiate your module's information variables (name, author, version, etc)
• Add your pages to NamelessMC's page system
• Set your module's required variables which are not provided in the onPageLoad(); function (Endpoints, Queries, etc)
• Add your module's hooks to NamelessMC's hook system

In the onPageLoad(); function, you will want to:

• Add your permissions to NamelessMC's permission system
• Add a sitemap method
• Add your pages to the navigation bars
• Initiate your module's widgets
• Initiate your module's API endpoints

More detail about your module's constructor:

• There are no required parameters.
• It must construct the parent Module class, and pass:
  • itself ($this)
  • the name of the module
  • the version of the module
  • the minimum NamelessMC version required (In the format 2.0.0-prX where X is the pre-release number), this is used to warn users if they have modules which may not work with their version of NamelessMC.
  • If you do not construct the parent class, your module will not be be registered and all your code will seem to have no effect.

Useful classes and some of their functions:

• Queries
  • More user friendly abstraction of the DB class to get and set data in the NamelessMC database.
  • Useful functions:
    • update($table, $id, $fields);
    • getWhere($table, $where);
• DB
  • "Raw" access to the NamelessMC database.
  • Useful functions:
    • getInstance();
      • Returns the current instance of the class, creates a new instance if there is not yet one.
    • insert($table, $fields);
      • Inserts a new row to $table using $fields.
      • $fields must be an array in the following format:

      // Column name => value
      $fields = array(
          'wiki_title' => 'First Wiki Article!',
          'wiki_content' => 'Greetings, everyone!',
          'wiki_author' => $user->data()->id
      );

• Cache
  • Store data in text files for specific periods of time for quicker and easier access when compared to the database.
  • Useful functions:
    • setCache($name);
      • Set your current $cache file. Useful for organizing data into different files, rather than one file for all information.
    • isCached($key);
      • Returns true/false depending if $key is cached in the current file (whatever was last set as the cache via setCache($name);).
    • retrieve($key);
      • Retrieves object under the key $key in the current cache file, or null if it does not exist.
    • store($key, $value, $expiration = 0);
      • Stores $value object with the key $key and sets it to expire in $expiration seconds in the current cache file.
      • If $expiration is not provided, it will never expire.
• Pages
  • todo
• Navigation
  • Often used in onPageLoad(); as an array of $navs, this let's your module add links to navigation sections.
  • Sections:
    • $navs[0] top navigation bar on frontend.
    • $navs[1] user dropdown on frontend.
    • $navs[2] StaffCP nav sidebar.
  • Useful functions:
    • add($name, $title, $link, $location = 'top', $target = null, $order = 10, $icon = '');
      • Adds a link to this navigation section (see above Sections)
• Language
  • Allows modules to get/set phrases in a specific locale.
  • Useful functions:
    • get($file, $term);
      • Returns the string with the key $term in the specified language file $file.
      • If the $term is not in the $file, it will try to find it in the EnglishUK file (as this is the default language used by NamelessMC developers. If it is not in the EnglishUK file, it will return "Term $term not set".
    • set($file, $term, $value);
      • Set (or update) the $term in $file to $value.
      • Used internally for email message editing via StaffCP.
• Widgets
  • Allows modules to add widgets to NamelessMC's widget system.
  • Useful functions:
    • add($widget);
      • Add $widget to the widget system.
      • $widget must be an instance of a class which extends the WidgetBase class.
      • Widget developer documentation is coming soon:tm:.
    • getPages($name);
      • Returns an array of page names that the widget named $name is enabled on.
• Endpoints
  • todo
• PermissionHandler
  • Register and get permissions from NamelessMC's core permission system.
  • Useful functions:
    • registerPermissions($section, $permissions);
      • Add permissions to the $section section. $section is used to separate permissions into different groups in StaffCP. Feel free to make $section the name of your module, or set it to $language->get('moderator', 'staff_cp') so your permissions fit in with all default permissions.
      • $permissions must be an array in the following format:

      // Permission value => Friendly title
      $permissions = array(
          'demo_module.add_user' => 'Add user',
          'demo_module.delete_user' => 'Delete user'
      );

• User
  • Refers to a user on the NamelessMC website.
  • Usually the logged-in user accessible via $user.
  • Useful functions:
    • data();
      • Returns an object of all the columns in nl2_users with the id of the current $user.
      • Often used to get their username: $user->data()->username
    • hasPermission($permission);
      • Returns true/false if the $user has the $permission.

Updated module main class - using classes shown above as an example:

<?php
// Demo module by Aberdeener
// module.php file

class Demo_Module extends Module {

    protected 
        $_language,
        $_cache,
        $_queries;  

    public function __construct($language, $cache, $queries) {

        $name = 'Demo Module';
	$author = 'Aberdeener';
	$module_version = '0.0.2';
	$nameless_version = '2.0.0-pr8';

	parent::__construct($this, $name, $author, $module_version, $nameless_version);

        $this->_language = $language;
        $this->_cache = $cache;
        $this->_queries = $queries;

	$pages->add('Demo Module', '/wiki', 'pages/wiki.php');
	$pages->add('Demo Module', '/panel/wiki', 'pages/panel/wiki.php');
    }

    public function onInstall() {
        $queries = $this->_queries;
        if (!count($queries->tableExists('wiki_articles'))) {
            $queries->createTable('wiki_articles', "`id` INT(11) NOT NULL AUTO_INCREMENT, `content` VARCHAR(102) NOT NULL, `user_id` INT(11) NOT NULL", "");
        }
        if (!count($queries->tableExists('wiki_user_stats'))) {
            $queries->createTable('wiki_user_stats', "`id` INT(11) NOT NULL AUTO_INCREMENT, `user_id` INT(11) NOT NULL, `wiki_articles` INT(11) NOT NULL", "");
        }
    }

    public function onUninstall() {
    }

    public function onEnable() {
    }

    public function onDisable() {
    }

    public onPageLoad($user, $pages, $cache, $smarty, $navs, $widgets, $template) {

        PermissionHandler::registerPermissions('Demo Module', array(
            'demo_module.view_wiki' => 'View the wiki',
            'demo_module.create_wiki_page' => 'Create wiki page',
            'demo_module.delete_wiki_page' => 'Delete wiki page',
        ));
        
        $cache = $this->_cache;

	$cache->setCache('navbar_order');
	if(!$cache->isCached('wiki_order')){
	    $order = 3;
	    $cache->store('wiki_order', $order);
	} else {
	    $order = $cache->retrieve('wiki_order');
	}

	$cache->setCache('navbar_icons');
	if(!$cache->isCached('wiki_icon')) {
            $icon = 'fa fas-book';
            $cache->store('wiki_order', $icon);
        } else {
            $icon = $cache->retrieve('wiki_icon');
        }

	$language = $this->_language;

        // Add a page to the top navigation bar
        $navs[0]->add('wiki', $language->get('wiki', 'wiki'), URL::build('/wiki'), 'top', null, $order, $icon);

        if ($user->hasPermission('demo_module.create_wiki_page')) {
            // Add page to user dropdown
            $navs[2]->add('create_wiki', $language->get('wiki', 'create_wiki'), URL::build('/wiki/create'));
        }

        require_once ROOT_PATH . '/modules/DemoModule/widgets/DemoWidget.php';
	$widget_pages = $widgets->getPages('Demo Widget');
        $demo_widget = new Demo_Widget($widget_pages);
        $widgets->add($demo_widget);

        $queries = $this->_queries;
        $wiki_article_count = count($queries->getWhere('wiki_articles', array('user_id', '=', $user->data()->id)));

        $fields = array(
            'user_id' => $user->data()->id,
            'wiki_articles' => $wiki_article_count
        );
        DB::getInstance()->insert('wiki_user_stats', $fields);
    }

}