Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update Fieldtype and Inputfield interfaces to support getConfigArray(…
…) methods, as an alternative to getConfigInputfields(). Update ConfiguragbleModule interface to support getModuleConfigInputfields() as optionally being non-static (you decide whether to make it static or non-static, and PW will adjust as needed). Also updated ConfigurableModule interface to support getModuleConfigArray() method as an alternative to getModuleConfigInputfields(). This method may be static or non-static, you decide. Updated documentation in both Module.php and ConfigurableModule.php interface files. Updated PW's root index.php to extract API variables when its being included from other scripts, so that you can use $pages rather than wire('pages') for example. Fixed issue with double-inclusion of InputfieldFile.js when debug mode is off. This commit also contains several other phpdoc updates throughout as ongoing work continues on always improving the code documentation.
- Loading branch information
1 parent
b34da37
commit 81790c4
Showing
13 changed files
with
660 additions
and
151 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,154 @@ | ||
<?php | ||
|
||
/** | ||
* ProcessWire ConfigurableModule Interface | ||
* | ||
* Provides the base interfaces required by modules. | ||
* | ||
* ProcessWire 2.x | ||
* Copyright (C) 2015 by Ryan Cramer | ||
* Licensed under GNU/GPL v2, see LICENSE.TXT | ||
* | ||
* 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 ommitted, 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); | ||
* | ||
*/ | ||
|
||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
<?php | ||
|
||
/** | ||
* ProcessWire Fields Array | ||
* | ||
* WireArray of Field instances, as used by Fields class | ||
* | ||
* ProcessWire 2.x | ||
* Copyright (C) 2015 by Ryan Cramer | ||
* Licensed under GNU/GPL v2, see LICENSE.TXT | ||
* | ||
* http://processwire.com | ||
* | ||
*/ | ||
|
||
class FieldsArray extends WireArray { | ||
|
||
/** | ||
* Per WireArray interface, only Field instances may be added | ||
* | ||
*/ | ||
public function isValidItem($item) { | ||
return $item instanceof Field; | ||
} | ||
|
||
/** | ||
* Per WireArray interface, Field keys have to be integers | ||
* | ||
*/ | ||
public function isValidKey($key) { | ||
return is_int($key) || ctype_digit($key); | ||
} | ||
|
||
/** | ||
* Per WireArray interface, Field instances are keyed by their ID | ||
* | ||
*/ | ||
public function getItemKey($item) { | ||
return $item->id; | ||
} | ||
|
||
/** | ||
* Per WireArray interface, return a blank Field | ||
* | ||
*/ | ||
public function makeBlankItem() { | ||
return new Field(); | ||
} | ||
} |
Oops, something went wrong.