Extending the Entity Class

To create a new type of data object in Nymph, you extend the Entity class. This is similar to creating a new table in a relational database. If you are going to use the class on the client side, you also need to create a corresponding JavaScript class. Below are two examples, one in PHP, and one in JavaScript. A more in depth explanation follows the examples.

Extending Entity in PHP

/**
 * @property string $name The todo's text.
 * @property bool $done Whether it's done.
 */
class Todo extends \Nymph\Entity {
	const etype = 'todo';
	protected $clientEnabledMethods = ['archive'];
	protected $whitelistData = ['name', 'done'];
	protected $protectedTags = ['archived'];
	protected $whitelistTags = [];

	public function __construct($id = 0) {
		$this->done = false;
		parent::__construct($id);
	}

	public function info($type) {
		if ($type == 'name' && isset($this->name)) {
			return $this->name;
		} elseif ($type == 'type') {
			return 'todo';
		} elseif ($type == 'types') {
			return 'todos';
		}
		return null;
	}

	public function archive() {
		if ($this->hasTag('archived')) {
			return true;
		}
		$this->addTag('archived');
		return $this->save();
	}
}

Extending Entity in JavaScript

// Uses AMD or browser globals.
(function (factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD. Register as a module.
        define('NymphTodo', ['NymphEntity'], factory);
    } else {
        // Browser globals
        factory(Entity);
    }
}(function(Entity){
	Todo = function(id){
		this.constructor.call(this, id);
		this.data.done = false;
	};
	Todo.prototype = new Entity();

	var thisClass = {
		// === The Name of the Class ===
		class: 'Todo',

		// === Class Variables ===
		etype: "todo",

		// === Class Methods ===

		archive: function(){
			return this.serverCall('archive', arguments);
		}
	};
	for (var p in thisClass) {
		if (thisClass.hasOwnProperty(p)) {
			Todo.prototype[p] = thisClass[p];
		}
	}

	return Todo;
}));

In both cases, defaults are set in the constructor. In this case, the 'todo' tag is added, and the 'done' property is set to false.

The first difference between the two versions to take note is the order of the statements in the constructor. In the PHP class, parent::__construct($id); comes at the end of the constructor. This is necessary because any defaults set before this call will be overwritten by the parent constructor loading the entity. In the JavaScript class, this.constructor.call(this, id); comes at the beginning of the constructor. This is necessary because the class variables are set by the Entity class's constructor. Also, defaults will be overwritten when the AJAX call completes, meaning it is fine to set them after the parent constructor.

In both cases, the etype is set to "todo". The etype of an entity (specifically the one on the PHP class) determines which table the entity will be placed in. When you search for an entity, you give Nymph a class name. Nymph will use that class's etype to determine which table to search for entities. If you don't provide a class name, the Entity class and the "entity" etype will be used.

The info method in PHP is used to provide information about an entity. The standard pieces of information an entity can provide are:

• name - The name of the object.
• type - The type of data this object represents. (E.g., "user", "customer", "page".) This can be localized.
• types - The same as above, but pluralized. (E.g., "users".)
• url_view - The URL where this object can be viewed. If the currently logged in user doesn't have the ability to view it, or there is no URL to view it, this should return null.
• url_edit - The same as above, but for editing.
• url_list - The URL where this object, and others like it, can be found. (E.g., to a list of users.)
• icon - The class to apply for an icon representing this object. (Generally a Font Awesome or Bootstrap class.)
• image - The URL to an image representing this object.

The $clientEnabledMethods property in PHP determines which methods can be called from the client side using serverCall. In the JavaScript class, the return this.serverCall('archive', arguments); statement takes advantage of this feature.

In JavaScript, AMD modules for Nymph entities are named with the "Nymph" prefix. Our example is named "NymphTodo" by the define('NymphTodo', ['NymphEntity'], factory); statement.

If you need access to the Nymph object in your JavaScript class, you must change three lines:

• define('NymphMyClass', ['NymphEntity'], factory);
  • define('NymphMyClass', ['NymphEntity', 'Nymph'], factory);
• factory(Entity);
  • factory(Entity, Nymph);
• }(function(Entity){
  • }(function(Entity, Nymph){

In JavaScript, it is impossible to determine which class an object is an instance of programmatically, so we include the name of the class on the class itself. It's the class: 'Todo', line.

The archive method is an example of how you add custom methods to a class. This particular method is available both in PHP and JavaScript via serverCall.

Unfortunately, there are a lot of places where you need to place your class name ("Todo" in this case) in JavaScript. You can use a case sensitive search/replace feature on the Todo class code.

Eventually, we will include a code generator tool which will generate both classes for you. Until then, we can pretend we're in the early days, when men were men and wrote their own device drivers.