Skip to content
Andreas Rønning edited this page Nov 27, 2013 · 8 revisions

DConsole supports plugins of varying complexity. These are intended to allow users to wrap commonly useful functionality in a portable package for reuse across projects.

To enable a plugin, call DConsole.registerPlugin(...), where ... is one or more class types.

DConsole.registerPlugin(MyPluginType,MyOtherPluginType);

A wide array of built-in plugins are offered under the com.furusystems.dconsole2.plugins package, and most of them can be quickly loaded using the AllPlugins plugin bundle.

DConsole.registerPlugin(AllPlugins);

Commonly useful, low-impact plugins include LogFileUtil, JSONParserUtil, ClassFactoryUtil, MeasurementBracketUtil, StatsOutputUtil and ControllerUtil.

Creating a plugin

To create a plugin, one of several interfaces must be implemented. Depending on the kind of interface used, varying access and functionality is achieved. Plugins can be ranked by complexity according to the interface they implement.

Type 1: IDConsolePlugin

The least complex plugin, this type is given access to the console internals, and has initialize and shutdown functions for managing lifetime, as well as a function returning a description text that gets output when users list the plugin by calling the built-in "plugins" command. Plugins support dependencies, which can be returned as a vector of Classes implementing IDConsolePlugin or its derivatives. Dependency plugins are loaded and initialized prior to the depending plugin (no duplicate plugins are allowed so don't worry about redundant dependencies). If the plugin has no dependencies, return null here.

Simple example:

package {
	import com.furusystems.dconsole2.core.plugins.IDConsolePlugin;
	import com.furusystems.dconsole2.core.plugins.PluginManager;
	import com.furusystems.logging.slf4as.ILogger;
	import com.furusystems.logging.slf4as.Logging;
	import flash.utils.getTimer;
	
	/**
	 * Example DConsole plugin
	 * This plugin maintains commands implementing a simple stopwatch functionality
	 * @author Andreas Rønning
	 */
	public class TimerUtil implements IDConsolePlugin {
		private var mStartTime:int;
		//It's good practise for a plugin's log messages to go through an ILogger
		private static const L:ILogger = Logging.getLogger(TimerUtil);
		
		public function TimerUtil() {
			//You should do most init in initialize(). Avoid constructor if possible.
		}
		
		private function stopTimer():void {
			var deltaMS:int = getTimer() - mStartTime;
			L.info("Timer stopped at : " + deltaMS + "ms / " + (deltaMS / 1000) + "s");
		}
		
		private function beginTimer():void {
			L.info("Timer started..");
			mStartTime = getTimer();
		}
		
		/* INTERFACE com.furusystems.dconsole2.core.plugins.IDConsolePlugin */
		
		/**
		 * This is where the plugin is first set up.
		 * PluginManager is every plugin's entrypoint into the console internals
		 * Commonly a plugin only needs a reference to the console itself, but sometimes
		 * grab instances of its initialized dependencies.
		 */
		public function initialize(pm:PluginManager):void {
			
			pm.console.createCommand("beginTimer", beginTimer);
			pm.console.createCommand("stopTimer", stopTimer);
		}
		
		/**
		 * Should the user decide to disable a plugin, this is where it does
		 * its cleanup.
		 */
		public function shutdown(pm:PluginManager):void {
			pm.console.removeCommand("beginTimer");
			pm.console.removeCommand("stopTimer");
		}
		
		/**
		 * Return a short description here
		 */
		public function get descriptionText():String {
			return "Simple stopwatch";
		}
		
		/**
		 * This plugin has no dependencies, so return nothing
		 */
		public function get dependencies():Vector.<Class> {
			return null;
		}
	
	}

}

Type 2: IUpdatingDConsolePlugin extends IDConsolePlugin

This plugin is offered a frame update event by implementing the function "update", in the case that it needs to perform a routine update in sync with the console's frame update frequency. This event is only received while the console is visible.

Type 3: IFilteringDConsolePlugin extends IDConsolePlugin

These plugins additionally function as message filters by implementing the filter function. When a new console message is created, it is passed to every filter plugin which evaluates its content with the filter function. If filter returns false, that message is rejected from the log.

Type 4: IParsingDConsolePlugin extends IDConsolePlugin

These plugins allow you to build on the command string parser. When a new command literal is input and the user presses the enter key, DConsole builds a list of the command's arguments, and iterates over every parsing plugin prior to running its own internal parser, passing each parser each argument. If the parser recognizes the arg and wishes to execute on it, it returns some value which is returned as the value of that argument for the purposes of executing the command. If the parser does not recognize the arg, it should return null to pass-through. See com.furusystems.dconsole2.plugins.JSONParserUtil for an example.

Type 4: IDConsoleInspectorPlugin extends IUpdatingDConsolePlugin

//TODO: Big topic, and the API needs lots of work