Creating a Resource Class

This tutorial is part of a Series:

Part I: Creating a Custom Resource Class
Part II: Handling our CRC Behavior
Part III: Customizing the Controllers
Part IV: Customizing the Processors

We're going to create a sample Custom Resource Class (CRC) that does a very simple task - it outputs a copyright on the bottom of a page with the current date. Yes - this is much more easily done in a Snippet in your Template, and is much better to do it that way. But this is a tutorial illustrating the concept of CRCs, so bear with it.

This page deals with Step 1 - creating the actual Custom Resource Class itself. Step 2 will actually implement the behavior of appending the copyright. Step 3 will deal with overriding the Controllers, and Step 4 will deal with overriding the Processors. The files used in this tutorial can be found on GitHub for reference: https://github.com/modxcms/CopyrightedResource

Step 1. Creating your Class

First off, create a xPDO package using a schema (if you're not familiar on how to do this, please read the Developing an Extra in MODX Revolution tutorial and/or the xPDO Defining a Schema tutorial):

<?xml version="1.0" encoding="UTF-8"?>
<model package="CopyrightedResource" baseClass="xPDOObject" platform="mysql" defaultEngine="MyISAM">
    <object class="CopyrightedResource" extends="modResource" />
</model>

Then generate the maps and classes for the model. This should give you a class that looks like this:

class CopyrightedResource extends modResource {
}

Simple, eh? Now we want to force the class_key of the resource, and ensure that it shows up in the Resource Create context menu (which we'll configure later on):

class CopyrightedResource extends modResource {
    public $showInContextMenu = true;
    function __construct(xPDO & $xpdo) {
        parent :: __construct($xpdo);
        $this->set('class_key','CopyrightedResource');
    }
}

This forces the class_key to "CopyrightedResource", which is our class, and ensures our Resource class shows up in the left-hand tree's context menu.

You should never add fields to the modResource table (yes, there were Extras that did this, but it's not the proper way). Rather, create a separate related table to join into, or use Revolution 2.2.1+'s new properties field to store extra data.

Getting Familiar with the modResourceInterface Interface class

If you look in the modResource class file, you'll see at the top a PHP Interface that defines what methods must be defined for a CRC to work:

interface modResourceInterface {
    public static function getControllerPath(xPDO &$modx);
    public function getContextMenuText();
    public function getResourceTypeName();
}

We'll now go into detail on each of these methods and how they implement our CRC.

Adding the getControllerPath Method

We're going to add the getControllerPath method to our class, but first, make sure you create a Namespace called "copyrightedresource" that points to your CRC's model directory. Once you've done that, then you can add this to your class:

public static function getControllerPath(xPDO &$modx) {
    return $modx->getOption('copyrightedresource.core_path',null,$modx->getOption('core_path').'components/copyrightedresource/').'controllers/';
}

What this method does is tell MODX that hey, look for my manager controllers in this directory that I return. This allows us to override the controllers for our CopyrightedResource CRC. The line first checks for a custom System Setting that shows where our CRC core directory path is (which is optional), and if it's not set, looks for our CRC path in 'core/components/copyrightedresource/'. It then appends "controllers/" to it (you could make this whatever you want, but the standard path for controllers is, strangely enough, "controllers/".

Great! MODX will now look for our controllers in that directory. We'll get into creating those in Step 2 of the tutorial.

Adding the getContextMenuText Method

Go ahead and add this method to your class:

public function getContextMenuText() {
  $this->xpdo->lexicon->load('copyrightedresource:default');
  return array(
    'text_create' => $this->xpdo->lexicon('copyrightedresource'),
    'text_create_here' => $this->xpdo->lexicon('copyrightedresource_create_here'),
  );
}

This returns two translated strings that MODX will insert into the "Create" context menu when right-clicking on a node in the Resource tab on the left-hand tree.

Obviously, you don't need to use the MODX lexicon here. You could simply return the text like so:

public function getContextMenuText() {
  return array(
    'text_create' => 'Copyrighted Page'
    'text_create_here' => 'Create a Copyrighted Page Here',
  );
}

And that'd work fine. But MODX allows you to load a Lexicon Topic so that you can translate the strings for your worldwide users.

Adding the getResourceTypeName Method

This final method tells MODX what the translated "name" of your CRC is. We probably don't want to call it "CopyrightedResource", so we're going to plop in this method:

public function getResourceTypeName() {
  $this->xpdo->lexicon->load('copyrightedresource:default');
  return $this->xpdo->lexicon('copyrightedresource');
}

Again, this could just return a string:

public function getResourceTypeName() {
  return 'Copyrighted Page';
}

This tells MODX to call it a "Copyrighted Page", rather than its class name, when dealing with it in the manager.

Adding the Class to Extension Packages

To load the CRC properly, you'll need to add it to the Extension Packages. Why? Well, MODX needs to load your CRC when it loads, so that it has a "library" of sorts of all the loaded Resource Classes available to it. MODX 2.2 provides you with an assistance method to add your package to the Extension Packages dataset:

$modx->addExtensionPackage('copyrightedresource','/path/to/copyrightedresource/model/');

Simply run this code once and MODX will automatically add it to the Extension Packages. There's also a removeExtensionPackage as well for removing the package from MODX.