Initial commit to new repo (carried over from: https://github.com/ryancramerdesign/ProcessWire/tree/devns)

wire/core/ConfigurableModule.php

@@ -0,0 +1,154 @@
+<?php namespace ProcessWire;
+
+/**
+ * ProcessWire ConfigurableModule Interface
+ *
+ * Provides the base interfaces required by modules.
+ * 
+ * This file is licensed under the MIT license
+ * https://processwire.com/about/license/mit/
+ *
+ * ProcessWire 3.x, Copyright 2016 by Ryan Cramer
+ * https://processwire.com
+ *
+ * 
+ * About the ConfigurableModule interface
+ * ======================================
+ * ConfigurableModule is an interface that indicates the module is configurable by providing
+ * __get() and __set() methods for getting and setting config values. Modules implementing 
+ * this interface are assumed to also implement the 'Module' interface.
+ * 
+ * The module must also provide one (1) of the following:
+ *
+ * 1. A getModuleConfigInputfields([$data]) method (static or non-static); OR
+ * 2. A separate ModuleName.config.php file that just populates $config array; OR
+ * 3. A separate ModuleNameConfig.php file that contains a ModuleConfig class.
+ *
+ * For more details about the above options, see the commented methods within
+ * the interface.
+ *
+ * When you use this as an interface, you MUST also use 'Module' as an interface,
+ * i.e. "class Something implements Module, ConfigurableModule"
+ *
+ * Hint: Make your ConfigurableModule classes inherit from WireData, which already has
+ * the get/set required methods.
+ *
+ * You may optionally specify a handler method for configuration data: setConfigData().
+ * If present, it will be used. See commented function reference in the interface below.
+ * 
+ *
+ */
+interface ConfigurableModule {
+
+	/**********************************************************************************
+	 * getModuleConfigInputfields method (static or non-static)
+	 *
+	 * Return an InputfieldWrapper of Inputfields used to configure the class. This may
+	 * be specified either as a static method or a non-static method.
+	 *
+	 * Benefits of static version
+	 * ===========================
+	 * 1. The module does not need to be instantiated in order to configure it, which
+	 *    means that unnecessary hooks won't get attached and unnecessary assets won't
+	 *    be triggered to load.
+	 * 2. It is supported by all versions of ProcessWire.
+	 *
+	 * Drawbacks of static version
+	 * ===========================
+	 * 1. You cannot pull config values directly from the module since it isn't
+	 *    instantiated, and thus you must use the provided $data array. This $data array
+	 *    only contains values if the module has been configured before.
+	 * 2. You can't access $this or anything you'd typically pull from it, like API vars
+	 *    or translation methods.
+	 *
+	 * Benefits of non-static version
+	 * ==============================
+	 * 1. You are working with the module in the same context that it is when running,
+	 *    thus you can pull config values and API vars directly from $this->something.
+	 * 2. It can be extended in descending classes.
+	 * 3. The $data argument can be omitted, as you don't need it since all config
+	 *    properties can be accessed directly from $this->[any property]. 
+	 * 4. You can specify an optional $inputfields argument in your function definition
+	 *    and if present, ProcessWire will prepare an InputfieldWrapper for you, saving
+	 *    a step. When present, you can optionally omit the return statement at the 
+	 *    bottom of the method as well. 
+	 *
+	 * Drawbacks of non-static version
+	 * ================================
+	 * 1. It is supported only in ProcessWire versions 2.5.27 or newer.
+	 * 2. The module must be instantiated in order to configure it, so it may trigger
+	 *    load of any used assets or attachment of any hooks unnecessarily.
+	 *
+	 * @param array $data Array of config values indexed by field name (static version only)
+	 * 	Note that this array will be empty if the module has not been configured before.
+	 * @return InputfieldWrapper
+	 *
+	 *  
+	 * // static version
+	 * public static function getModuleConfigInputfields(array $data); 
+	 * 
+	 * // non-static version
+	 * public function getModuleConfigInputfields(); 
+	 *  
+	 * // non-static version with optional $data array, if you want it for some reason
+	 * public function getModuleConfigInputfields(array $data); 
+	 *  
+	 * // non-static version with optional InputfieldWrapper as a convenience
+	 * // note that the "return" statement may be omitted when using the $inputfields param.
+	 * public function getModuleConfigInputfields($inputfields); 
+	 * 
+	 */
+
+	/*********************************************************************************
+	 * Return an array defining Inputfields (static or non-static)
+	 * 
+	 * You should use either getModuleConfigArray() or getModuleConfigInputfields(),
+	 * do not use both, as ProcessWire will only recognize one or the other. Likewise,
+	 * you should either use the static version of non-static version, not both. 
+	 *
+	 * See notes for getModuleConfigInputfields() above for benefits and drawbacks
+	 * of static vs. non-static versions. The primary difference between this method
+	 * and that method is that this one returns an array. The format of the array should
+	 * be as shown in InputfieldWrapper::importArray (see InputfieldWrapper.php).
+	 * 
+	 * Whether static or non-static, your 'value' attributes in the array need only 
+	 * represent the default values. ProcessWire will populate the actual values 
+	 * to the resulting Inputfields after the method has been called. This is a benefit
+	 * over the getModuleConfigInputfields() methods. 
+	 *
+	 * @return array
+	 *
+	 * public static function getModuleConfigArray(); // static version
+	 * public function getModuleConfigArray(); // non-static version
+	 */
+
+	/**
+	 * Get a module config property
+	 *
+	 * @param string $key
+	 * @return mixed
+	 *
+	 */
+	public function __get($key);
+
+	/**
+	 * Set a module config property
+	 *
+	 * @param $key
+	 * @param $value
+	 * @return mixed
+	 *
+	 */
+	public function __set($key, $value);
+
+	/**
+	 * An optional method you may include in your ConfigurableModule to have ProcessWire
+	 * send the configuration data to it rather than populating the properties individually.
+	 *
+	 * @param array $data Array of data in $key => $value format.
+	 *
+	 * public function setConfigData(array $data);
+	 *
+	 */
+
+}