From ddcfcf7bed2220ae5786685c3c17fd493617d865 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Mon, 20 May 2013 22:18:07 +1200 Subject: [PATCH] Update @package, @subpackage labels Cleanup of framework's use of @package and @subpackage labels and additional of labels for classes missing packages. Moved all GridField related components to the one name. Countless spelling fixes, grammar for other comments. Link ClassName references in file headers. --- admin/code/LeftAndMain.php | 12 +- admin/code/LeftAndMainExtension.php | 4 +- admin/code/ModelAdmin.php | 4 +- control/PjaxResponseNegotiator.php | 13 +- control/RequestProcessor.php | 6 +- control/injector/AopProxyService.php | 5 +- control/injector/BeforeCallAspect.php | 4 +- control/injector/InjectionCreator.php | 26 ++ .../injector/ServiceConfigurationLocator.php | 15 ++ .../injector/SilverStripeInjectonCreator.php | 22 ++ ...ilverStripeServiceConfigurationLocator.php | 49 ++++ core/Config.php | 250 ++++++++++++------ forms/gridfield/GridField.php | 9 +- .../GridFieldAddExistingAutocompleter.php | 25 +- forms/gridfield/GridFieldAddNewButton.php | 15 +- forms/gridfield/GridFieldButtonRow.php | 11 +- forms/gridfield/GridFieldComponent.php | 115 +++++--- forms/gridfield/GridFieldConfig.php | 59 +++-- forms/gridfield/GridFieldDataColumns.php | 11 +- forms/gridfield/GridFieldDeleteAction.php | 21 +- forms/gridfield/GridFieldDetailForm.php | 16 +- forms/gridfield/GridFieldEditButton.php | 24 +- forms/gridfield/GridFieldExportButton.php | 10 +- forms/gridfield/GridFieldFilterHeader.php | 5 +- forms/gridfield/GridFieldFooter.php | 27 +- forms/gridfield/GridFieldLevelup.php | 11 +- forms/gridfield/GridFieldPageCount.php | 4 +- forms/gridfield/GridFieldPaginator.php | 6 +- forms/gridfield/GridFieldPrintButton.php | 4 +- forms/gridfield/GridFieldSortableHeader.php | 10 +- forms/gridfield/GridFieldToolbarHeader.php | 8 +- forms/gridfield/GridFieldViewButton.php | 5 +- forms/gridfield/GridState.php | 16 +- model/DataList.php | 5 +- model/DataModel.php | 44 ++- model/DataQuery.php | 19 +- model/HasManyList.php | 14 +- model/ManyManyList.php | 5 +- model/RelationList.php | 14 +- model/UnsavedRelationList.php | 18 +- oembed/Oembed.php | 23 +- 41 files changed, 707 insertions(+), 257 deletions(-) create mode 100644 control/injector/InjectionCreator.php create mode 100644 control/injector/ServiceConfigurationLocator.php create mode 100644 control/injector/SilverStripeInjectonCreator.php create mode 100644 control/injector/SilverStripeServiceConfigurationLocator.php diff --git a/admin/code/LeftAndMain.php b/admin/code/LeftAndMain.php index 8a5fd961d..39c9d5c1f 100644 --- a/admin/code/LeftAndMain.php +++ b/admin/code/LeftAndMain.php @@ -6,8 +6,8 @@ * This is essentially an abstract class which should be subclassed. * See {@link CMSMain} for a good example. * - * @package cms - * @subpackage core + * @package framework + * @subpackage admin */ class LeftAndMain extends Controller implements PermissionProvider { @@ -1769,6 +1769,9 @@ class LeftAndMainMarkingFilter { /** * Allow overriding finished state for faux redirects. + * + * @package framework + * @subpackage admin */ class LeftAndMain_HTTPResponse extends SS_HTTPResponse { @@ -1788,7 +1791,10 @@ class LeftAndMain_HTTPResponse extends SS_HTTPResponse { * Wrapper around objects being displayed in a tree. * Caution: Volatile API. * - * @todo Implement recursive tree node rendering + * @todo Implement recursive tree node rendering. + * + * @package framework + * @subpackage admin */ class LeftAndMain_TreeNode extends ViewableData { diff --git a/admin/code/LeftAndMainExtension.php b/admin/code/LeftAndMainExtension.php index 7efcdf886..5d632bb40 100644 --- a/admin/code/LeftAndMainExtension.php +++ b/admin/code/LeftAndMainExtension.php @@ -2,8 +2,8 @@ /** * Plug-ins for additional functionality in your LeftAndMain classes. * - * @package cms - * @subpackage core + * @package framework + * @subpackage admin */ abstract class LeftAndMainExtension extends Extension { diff --git a/admin/code/ModelAdmin.php b/admin/code/ModelAdmin.php index 065e04dee..66e73ba6f 100644 --- a/admin/code/ModelAdmin.php +++ b/admin/code/ModelAdmin.php @@ -26,8 +26,8 @@ * * @uses SearchContext * - * @package cms - * @subpackage core + * @package framework + * @subpackage admin */ abstract class ModelAdmin extends LeftAndMain { diff --git a/control/PjaxResponseNegotiator.php b/control/PjaxResponseNegotiator.php index b22779eee..bab51bf5d 100644 --- a/control/PjaxResponseNegotiator.php +++ b/control/PjaxResponseNegotiator.php @@ -1,14 +1,21 @@ * @package framework * @subpackage injector - * @license BSD http://silverstripe.org/BSD-license */ interface BeforeCallAspect { diff --git a/control/injector/InjectionCreator.php b/control/injector/InjectionCreator.php new file mode 100644 index 000000000..c521a68d1 --- /dev/null +++ b/control/injector/InjectionCreator.php @@ -0,0 +1,26 @@ +newInstanceArgs($params); + } + + return $reflector->newInstance(); + } +} \ No newline at end of file diff --git a/control/injector/ServiceConfigurationLocator.php b/control/injector/ServiceConfigurationLocator.php new file mode 100644 index 000000000..3bcc00404 --- /dev/null +++ b/control/injector/ServiceConfigurationLocator.php @@ -0,0 +1,15 @@ +newInstanceArgs($params); + } +} \ No newline at end of file diff --git a/control/injector/SilverStripeServiceConfigurationLocator.php b/control/injector/SilverStripeServiceConfigurationLocator.php new file mode 100644 index 000000000..faf86d755 --- /dev/null +++ b/control/injector/SilverStripeServiceConfigurationLocator.php @@ -0,0 +1,49 @@ +configs[$name])) { + return $this->configs[$name]; + } + + $config = Config::inst()->get('Injector', $name); + if ($config) { + $this->configs[$name] = $config; + return $config; + } + + // do parent lookup if it's a class + if (class_exists($name)) { + $parents = array_reverse(array_keys(ClassInfo::ancestry($name))); + array_shift($parents); + foreach ($parents as $parent) { + // have we already got for this? + if (isset($this->configs[$parent])) { + return $this->configs[$parent]; + } + $config = Config::inst()->get('Injector', $parent); + if ($config) { + $this->configs[$name] = $config; + return $config; + } else { + $this->configs[$parent] = false; + } + } + + // there is no parent config, so we'll record that as false so we don't do the expensive + // lookup through parents again + $this->configs[$name] = false; + } + } +} \ No newline at end of file diff --git a/core/Config.php b/core/Config.php index ad92f1cfc..10c00ed3c 100644 --- a/core/Config.php +++ b/core/Config.php @@ -10,166 +10,215 @@ * - An array * - A non-array value * - * If the value is an array, each value in the array may also be one of those three types + * If the value is an array, each value in the array may also be one of those + * three types. * - * A property can have a value specified in multiple locations, each of which have a hardcoded or explicit priority. - * We combine all these values together into a "composite" value using rules that depend on the priority order of the - * locations to give the final value, using these rules: + * A property can have a value specified in multiple locations, each of which + * have a hard coded or explicit priority. We combine all these values together + * into a "composite" value using rules that depend on the priority order of + * the locations to give the final value, using these rules: * - * - If the value is an array, each array is added to the _beginning_ of the composite array in ascending priority - * order. If a higher priority item has a non-integer key which is the same as a lower priority item, the value of - * those items is merged using these same rules, and the result of the merge is located in the same location the - * higher priority item would be if there was no key clash. Other than in this key-clash situation, within the - * particular array, order is preserved. + * - If the value is an array, each array is added to the _beginning_ of the + * composite array in ascending priority order. If a higher priority item has + * a non-integer key which is the same as a lower priority item, the value of + * those items is merged using these same rules, and the result of the merge + * is located in the same location the higher priority item would be if there + * was no key clash. Other than in this key-clash situation, within the + * particular array, order is preserved. * - * - If the value is not an array, the highest priority value is used without any attempt to merge + * - If the value is not an array, the highest priority value is used without + * any attempt to merge. * - * It is an error to have mixed types of the same named property in different locations (but an error will not - * necessarily be raised due to optimisations in the lookup code) + * It is an error to have mixed types of the same named property in different + * locations (but an error will not necessarily be raised due to optimizations + * in the lookup code). * - * The exception to this is "false-ish" values - empty arrays, empty strings, etc. When merging a non-false-ish value - * with a false-ish value, the result will be the non-false-ish value regardless of priority. When merging two + * The exception to this is "false-ish" values - empty arrays, empty strings, + * etc. When merging a non-false-ish value with a false-ish value, the result + * will be the non-false-ish value regardless of priority. When merging two * false-ish values the result will be the higher priority false-ish value. * - * The locations that configuration values are taken from in highest -> lowest priority order + * The locations that configuration values are taken from in highest -> lowest + * priority order. * - * - Any values set via a call to Config#update + * - Any values set via a call to Config#update. * - * - The configuration values taken from the YAML files in _config directories (internally sorted in before / after - * order, where the item that is latest is highest priority) + * - The configuration values taken from the YAML files in _config directories + * (internally sorted in before / after order, where the item that is latest + * is highest priority). * - * - Any static set on an "additional static source" class (such as an extension) named the same as the name of the - * property + * - Any static set on an "additional static source" class (such as an + * extension) named the same as the name of the property. * - * - Any static set on the class named the same as the name of the property + * - Any static set on the class named the same as the name of the property. * - * - The composite configuration value of the parent class of this class + * - The composite configuration value of the parent class of this class. * - * At some of these levels you can also set masks. These remove values from the composite value at their priority - * point rather than add. They are much simpler. They consist of a list of key / value pairs. When applied against the - * current composite value: + * At some of these levels you can also set masks. These remove values from the + * composite value at their priority point rather than add. They are much + * simpler. They consist of a list of key / value pairs. When applied against + * the current composite value: * - * - If the composite value is a sequential array, any member of that array that matches any value in the mask is - * removed + * - If the composite value is a sequential array, any member of that array + * that matches any value in the mask is removed. * - * - If the composite value is an associative array, any member of that array that matches both the key and value of - * any pair in the mask is removed + * - If the composite value is an associative array, any member of that array + * that matches both the key and value of any pair in the mask is removed. * - * - If the composite value is not an array, if that value matches any value in the mask it is removed + * - If the composite value is not an array, if that value matches any value + * in the mask it is removed. + * + * @package framework + * @subpackage core */ class Config { /** - * [A marker instance for the "anything" singleton value. Don't access directly, even in-class, always use - * self::anything() + * A marker instance for the "anything" singleton value. Don't access + * directly, even in-class, always use self::anything() + * * @var Object */ - static private $_anything = null; + private static $_anything = null; /** - * Get a marker class instance that is used to do a "remove anything with this key" by adding - * $key => Config::anything() to the suppress array + * Get a marker class instance that is used to do a "remove anything with + * this key" by adding $key => Config::anything() to the suppress array * - * @todo Does this follow the SS coding conventions? Config::get_anything_marker_instance() is a lot less elegant. * @return Object */ - static public function anything() { - if (self::$_anything === null) self::$_anything = new stdClass(); + public static function anything() { + if (self::$_anything === null) { + self::$_anything = new stdClass(); + } + return self::$_anything; } // -- Source options bitmask -- /** - * source options bitmask value - merge all parent configuration in as lowest priority + * source options bitmask value - merge all parent configuration in as + * lowest priority. + * * @const */ const INHERITED = 0; + /** - * source options bitmask value - only get configuration set for this specific class, not any of it's parents + * source options bitmask value - only get configuration set for this + * specific class, not any of it's parents. + * * @const */ const UNINHERITED = 1; + /** - * source options bitmask value - inherit, but stop on the first class that actually provides a value (event an - * empty value) + * source options bitmask value - inherit, but stop on the first class + * that actually provides a value (event an empty value). + * * @const */ const FIRST_SET = 2; - /** @const source options bitmask value - do not use additional statics sources (such as extension) */ + + /** + * @const source options bitmask value - do not use additional statics + * sources (such as extension) + */ const EXCLUDE_EXTRA_SOURCES = 4; // -- get_value_type response enum -- /** - * Return flag for get_value_type indicating value is a scalar (or really just not-an-array, at least ATM) + * Return flag for get_value_type indicating value is a scalar (or really + * just not-an-array, at least ATM) + * * @const */ const ISNT_ARRAY = 1; + /** - * Return flag for get_value_type indicating value is an array + * Return flag for get_value_type indicating value is an array. * @const */ const IS_ARRAY = 2; /** - * Get whether the value is an array or not. Used to be more complicated, but still nice sugar to have an enum - * to compare and not just a true/false value + * Get whether the value is an array or not. Used to be more complicated, + * but still nice sugar to have an enum to compare and not just a true / + * false value. + * * @param $val any - The value + * * @return int - One of ISNT_ARRAY or IS_ARRAY */ - static protected function get_value_type($val) { - if (is_array($val)) return self::IS_ARRAY; + protected static function get_value_type($val) { + if (is_array($val)) { + return self::IS_ARRAY; + } + return self::ISNT_ARRAY; } /** - * What to do if there's a type mismatch + * What to do if there's a type mismatch. + * * @throws UnexpectedValueException */ - static protected function type_mismatch() { + protected static function type_mismatch() { throw new UnexpectedValueException('Type mismatch in configuration. All values for a particular property must' . ' contain the same type (or no value at all).'); } - /* @todo If we can, replace next static & static methods with DI once that's in */ - static protected $instance; + /** + * @todo If we can, replace next static & static methods with DI once that's in + */ + protected static $instance; /** * Get the current active Config instance. * * Configs should not normally be manually created. - * In general use you will use this method to obtain the current Config instance. + * + * In general use you will use this method to obtain the current Config + * instance. * * @return Config */ - static public function inst() { - if (!self::$instance) self::$instance = new Config(); + public static function inst() { + if (!self::$instance) { + self::$instance = new Config(); + } + return self::$instance; } /** - * Set the current active Config instance. + * Set the current active {@link Config} instance. * - * Configs should not normally be manually created. - * A use case for replacing the active configuration set would be for creating an isolated environment for - * unit tests + * {@link Config} objects should not normally be manually created. + * + * A use case for replacing the active configuration set would be for + * creating an isolated environment for unit tests. * * @return Config */ - static public function set_instance($instance) { + public static function set_instance($instance) { self::$instance = $instance; + global $_SINGLETONS; $_SINGLETONS['Config'] = $instance; } /** - * Make the newly active Config be a copy of the current active Config instance. + * Make the newly active {@link Config} be a copy of the current active + * {@link Config} instance. * - * You can then make changes to the configuration by calling update and remove on the new - * value returned by Config::inst(), and then discard those changes later by calling unnest + * You can then make changes to the configuration by calling update and + * remove on the new value returned by Config::inst(), and then discard + * those changes later by calling unnest. */ - static public function nest() { + public static function nest() { $current = self::$instance; $new = clone $current; @@ -178,17 +227,21 @@ class Config { } /** - * Change the active Config back to the Config instance the current active Config object - * was copied from + * Change the active Config back to the Config instance the current active + * Config object was copied from. */ - static public function unnest() { + public static function unnest() { self::set_instance(self::$instance->nestedFrom); } + /** + * @var array + */ protected $cache; /** - * Each copy of the Config object need's it's own cache, so changes don't leak through to other instances + * Each copy of the Config object need's it's own cache, so changes don't + * leak through to other instances. */ public function __construct() { $this->cache = new Config_LRU(); @@ -198,21 +251,37 @@ class Config { $this->cache = clone $this->cache; } - /** @var Config - The config instance this one was copied from when Config::nest() was called */ + /** + * @var Config - The config instance this one was copied from when + * Config::nest() was called. + */ protected $nestedFrom = null; - /** @var [array] - Array of arrays. Each member is an nested array keyed as $class => $name => $value, - * where value is a config value to treat as the highest priority item */ + /** + * @var array - Array of arrays. Each member is an nested array keyed as + * $class => $name => $value, where value is a config value to treat as + * the highest priority item. + */ protected $overrides = array(); - /** @var [array] - Array of arrays. Each member is an nested array keyed as $class => $name => $value, - * where value is a config value suppress from any lower priority item */ + /** + * @var array $suppresses Array of arrays. Each member is an nested array + * keyed as $class => $name => $value, where value is a config value suppress + * from any lower priority item. + */ protected $suppresses = array(); + /** + * @var array + */ protected $staticManifests = array(); + /** + * @param SS_ConfigStaticManifest + */ public function pushConfigStaticManifest(SS_ConfigStaticManifest $manifest) { array_unshift($this->staticManifests, $manifest); + $this->cache->clean(); } @@ -596,6 +665,10 @@ class Config { } +/** + * @package framework + * @subpackage core + */ class Config_LRU { const SIZE = 1000; @@ -701,25 +774,54 @@ class Config_LRU { } } +/** + * @package framework + * @subpackage core + */ class Config_ForClass { + + /** + * @var string $class + */ protected $class; + /** + * @param string $class + */ public function __construct($class) { $this->class = $class; } + /** + * @param string $name + */ public function __get($name) { return Config::inst()->get($this->class, $name); } + /** + * @param string $name + * @param mixed $val + */ public function __set($name, $val) { return Config::inst()->update($this->class, $name, $val); } + /** + * @param string $name + * @param int $sourceOptions + * + * @return array|scalar + */ public function get($name, $sourceOptions = 0) { return Config::inst()->get($this->class, $name, $sourceOptions); } + /** + * @param string + * + * @return Config_ForClass + */ public function forClass($class) { return Config::inst()->forClass($class); } diff --git a/forms/gridfield/GridField.php b/forms/gridfield/GridField.php index eb18700e2..d529f51dd 100644 --- a/forms/gridfield/GridField.php +++ b/forms/gridfield/GridField.php @@ -16,7 +16,7 @@ * @see SS_List * * @package framework - * @subpackage fields-relational + * @subpackage fields-gridfield */ class GridField extends FormField { @@ -761,12 +761,11 @@ class GridField extends FormField { /** - * This class is the base class when you want to have an action that alters the state of the gridfield, - * rendered as a button element. + * This class is the base class when you want to have an action that alters + * the state of the {@link GridField}, rendered as a button element. * * @package framework - * @subpackage forms - * + * @subpackage fields-gridfield */ class GridField_FormAction extends FormAction { diff --git a/forms/gridfield/GridFieldAddExistingAutocompleter.php b/forms/gridfield/GridFieldAddExistingAutocompleter.php index 5db26cfa9..d1990ef07 100644 --- a/forms/gridfield/GridFieldAddExistingAutocompleter.php +++ b/forms/gridfield/GridFieldAddExistingAutocompleter.php @@ -1,14 +1,25 @@ canCreate()} for this record returns true. + * This component provides a button for opening the add new form provided by + * {@link GridFieldDetailForm}. + * + * Only returns a button if {@link DataObject->canCreate()} for this record + * returns true. * * @package framework - * @subpackage gridfield + * @subpackage fields-gridfield */ class GridFieldAddNewButton implements GridField_HTMLProvider { @@ -14,6 +17,7 @@ class GridFieldAddNewButton implements GridField_HTMLProvider { public function setButtonName($name) { $this->buttonName = $name; + return $this; } @@ -23,7 +27,10 @@ class GridFieldAddNewButton implements GridField_HTMLProvider { public function getHTMLFragments($gridField) { $singleton = singleton($gridField->getModelClass()); - if(!$singleton->canCreate()) return array(); + + if(!$singleton->canCreate()) { + return array(); + } if(!$this->buttonName) { // provide a default button name, can be changed by calling {@link setButtonName()} on this component diff --git a/forms/gridfield/GridFieldButtonRow.php b/forms/gridfield/GridFieldButtonRow.php index cb1cbdffe..376936530 100644 --- a/forms/gridfield/GridFieldButtonRow.php +++ b/forms/gridfield/GridFieldButtonRow.php @@ -1,14 +1,18 @@ "\$DefineFragment(buttons-{$this->targetFragment}-left)", "RightFragment" => "\$DefineFragment(buttons-{$this->targetFragment}-right)", )); + return array( $this->targetFragment => $data->renderWith('GridFieldButtonRow') ); diff --git a/forms/gridfield/GridFieldComponent.php b/forms/gridfield/GridFieldComponent.php index ac8c891c7..f4ddf7175 100644 --- a/forms/gridfield/GridFieldComponent.php +++ b/forms/gridfield/GridFieldComponent.php @@ -1,42 +1,58 @@ getDisplayFields()} and {@link GridFieldDataColumns}. + * + * @see {@link GridFieldDataColumns->getDisplayFields()} + * @see {@link GridFieldDataColumns}. * * @param GridField $gridField * @param array - List reference of all column names. @@ -83,16 +99,29 @@ interface GridField_ColumnProvider extends GridFieldComponent { } /** - * An action is defined by two things: an action name, and zero or more named arguments. + * An action is defined by two things: an action name, and zero or more named + * arguments. + * * There is no built-in notion of a record-specific or column-specific action, - * but you may choose to define an argument such as ColumnName or RecordID in order to implement these. - * Does not provide interface elements to call those actions, see {@link GridField_FormAction}. + * but you may choose to define an argument such as ColumnName or RecordID in + * order to implement these. + * + * Does not provide interface elements to call those actions. + * + * @see {@link GridField_FormAction}. + * + * @package framework + * @subpackage fields-gridfield */ interface GridField_ActionProvider extends GridFieldComponent { /** * Return a list of the actions handled by this action provider. - * Used to identify the action later on through the $actionName parameter in {@link handleAction}. - * There is no namespacing on these actions, so you need to ensure that they don't conflict with other components. + * + * Used to identify the action later on through the $actionName parameter + * in {@link handleAction}. + * + * There is no namespacing on these actions, so you need to ensure that + * they don't conflict with other components. * * @param GridField * @return Array with action identifier strings. @@ -100,9 +129,10 @@ interface GridField_ActionProvider extends GridFieldComponent { public function getActions($gridField); /** - * Handle an action on the given grid field. - * Calls ALL components for every action handled, so the component - * needs to ensure it only accepts actions it is actually supposed to handle. + * Handle an action on the given {@link GridField}. + * + * Calls ALL components for every action handled, so the component needs + * to ensure it only accepts actions it is actually supposed to handle. * * @param GridField * @param String Action identifier, see {@link getActions()}. @@ -113,14 +143,21 @@ interface GridField_ActionProvider extends GridFieldComponent { } /** - * Can modify the data list. - * For example, a paginating component can apply a limit, or a sorting component can apply a sort. - * Generally, the data manipulator will make use of to `GridState` variables to decide - * how to modify the data list (see {@link GridState}). + * Can modify the data list. + * + * For example, a paginating component can apply a limit, or a sorting + * component can apply a sort. + * + * Generally, the data manipulator will make use of to {@link GridState} + * variables to decide how to modify the {@link DataList}. + * + * @package framework + * @subpackage fields-gridfield */ interface GridField_DataManipulator extends GridFieldComponent { + /** - * Manipulate the datalist as needed by this grid modifier. + * Manipulate the {@link DataList} as needed by this grid modifier. * * @param GridField * @param SS_List @@ -130,21 +167,37 @@ interface GridField_DataManipulator extends GridFieldComponent { } /** - * Sometimes an action isn't enough: you need to provide additional support URLs for the grid. - * These URLs may return user-visible content, for example a pop-up form for editing a record's details, - * or they may be support URLs for front-end functionality. - * For example a URL that will return JSON-formatted data for a javascript grid control. + * Sometimes an action isn't enough: you need to provide additional support + * URLs for the {@link GridField}. + * + * These URLs may return user-visible content, for example a pop-up form for + * editing a record's details, or they may be support URLs for front-end + * functionality. + * + * For example a URL that will return JSON-formatted data for a javascript + * grid control. + * + * @package framework + * @subpackage fields-gridfield */ interface GridField_URLHandler extends GridFieldComponent { + /** - * Return URLs to be handled by this grid field, in an array the same form as $url_handlers. - * Handler methods will be called on the component, rather than the grid field. + * Return URLs to be handled by this grid field, in an array the same form + * as $url_handlers. + * + * Handler methods will be called on the component, rather than the + * {@link GridField}. */ public function getURLHandlers($gridField); } /** - * A component which is used to handle when a grid field is saved into a record. + * A component which is used to handle when a {@link GridField} is saved into + * a record. + * + * @package framework + * @subpackage fields-gridfield */ interface GridField_SaveHandler extends GridFieldComponent { diff --git a/forms/gridfield/GridFieldConfig.php b/forms/gridfield/GridFieldConfig.php index e8d026a5f..78895d542 100644 --- a/forms/gridfield/GridFieldConfig.php +++ b/forms/gridfield/GridFieldConfig.php @@ -1,21 +1,27 @@ setItemsPerPage()}. + * pagination on the listed records, and configure it through + * {@link GridFieldPaginator->setItemsPerPage()}. * - * In order to reduce the amount of custom code required, the framework provides - * some default configurations for common use cases: + * In order to reduce the amount of custom code required, the framework + * provides some default configurations for common use cases: + * * - {@link GridFieldConfig_Base} (added by default to GridField) * - {@link GridFieldConfig_RecordEditor} * - {@link GridFieldConfig_RelationEditor} + * + * @package framework + * @subpackage fields-gridfield */ class GridFieldConfig { + /** - * * @var ArrayList */ protected $components = null; @@ -129,12 +135,15 @@ class GridFieldConfig { } /** - * A simple readonly, paginated view of records, - * with sortable and searchable headers. + * A simple readonly, paginated view of records, with sortable and searchable + * headers. + * + * @package framework + * @subpackage fields-gridfield */ class GridFieldConfig_Base extends GridFieldConfig { + /** - * * @param int $itemsPerPage - How many items per page should show up */ public function __construct($itemsPerPage=null) { @@ -153,6 +162,9 @@ class GridFieldConfig_Base extends GridFieldConfig { /** * Allows viewing readonly details of individual records. + * + * @package framework + * @subpackage fields-gridfield */ class GridFieldConfig_RecordViewer extends GridFieldConfig_Base { @@ -166,7 +178,8 @@ class GridFieldConfig_RecordViewer extends GridFieldConfig_Base { } /** - * + * @package framework + * @subpackage fields-gridfield */ class GridFieldConfig_RecordEditor extends GridFieldConfig { /** @@ -195,22 +208,28 @@ class GridFieldConfig_RecordEditor extends GridFieldConfig { /** - * Similar to {@link GridFieldConfig_RecordEditor}, but adds features - * to work on has-many or many-many relationships. - * Allows to search for existing records to add to the relationship, - * detach listed records from the relationship (rather than removing them from the database), - * and automatically add newly created records to it. + * Similar to {@link GridFieldConfig_RecordEditor}, but adds features to work + * on has-many or many-many relationships. + * + * Allows to search for existing records to add to the relationship, detach + * listed records from the relationship (rather than removing them from the + * database), and automatically add newly created records to it. * - * To further configure the field, use {@link getComponentByType()}, - * for example to change the field to search. + * To further configure the field, use {@link getComponentByType()}, for + * example to change the field to search. + * * * GridFieldConfig_RelationEditor::create() - * ->getComponentByType('GridFieldAddExistingAutocompleter')->setSearchFields('MyField'); + * ->getComponentByType('GridFieldAddExistingAutocompleter') + * ->setSearchFields('MyField'); * + * + * @package framework + * @subpackage fields-gridfield */ class GridFieldConfig_RelationEditor extends GridFieldConfig { + /** - * * @param int $itemsPerPage - How many items per page should show up */ public function __construct($itemsPerPage=null) { diff --git a/forms/gridfield/GridFieldDataColumns.php b/forms/gridfield/GridFieldDataColumns.php index e3684c7c2..0749ac898 100644 --- a/forms/gridfield/GridFieldDataColumns.php +++ b/forms/gridfield/GridFieldDataColumns.php @@ -1,17 +1,20 @@ * $action = new GridFieldDeleteAction(); // delete objects permanently - * $action = new GridFieldDeleteAction(true); // removes the relation to object, instead of deleting + * + * // removes the relation to object instead of deleting + * $action = new GridFieldDeleteAction(true); * * * @package framework - * @subpackage gridfield + * @subpackage fields-gridfield */ class GridFieldDeleteAction implements GridField_ColumnProvider, GridField_ActionProvider { /** - * If this is set to true, this actionprovider will remove the object from the list, instead of - * deleting. In the case of a has one, has many or many many list it will uncouple the item from - * the list. + * If this is set to true, this {@link GridField_ActionProvider} will + * remove the object from the list, instead of deleting. + * + * In the case of a has one, has many or many many list it will uncouple + * the item from the list. * * @var boolean */ diff --git a/forms/gridfield/GridFieldDetailForm.php b/forms/gridfield/GridFieldDetailForm.php index 5eb9b6a00..9ba4500e6 100644 --- a/forms/gridfield/GridFieldDetailForm.php +++ b/forms/gridfield/GridFieldDetailForm.php @@ -1,14 +1,20 @@ /field//item/ * - /field//item//edit + * + * @package framework + * @subpackage fields-gridfield */ class GridFieldDetailForm implements GridField_URLHandler { @@ -183,6 +189,10 @@ class GridFieldDetailForm implements GridField_URLHandler { } } +/** + * @package framework + * @subpackage fields-gridfield + */ class GridFieldDetailForm_ItemRequest extends RequestHandler { /** diff --git a/forms/gridfield/GridFieldEditButton.php b/forms/gridfield/GridFieldEditButton.php index d2801d535..7aff78041 100644 --- a/forms/gridfield/GridFieldEditButton.php +++ b/forms/gridfield/GridFieldEditButton.php @@ -1,10 +1,17 @@ message = $message; + if($message) { + $this->message = $message; + } } @@ -36,7 +44,12 @@ class GridFieldFooter implements GridField_HTMLProvider { )); return array( - 'footer' => $forTemplate->renderWith('GridFieldFooter', array('Colspan'=>count($gridField->getColumns()))), + 'footer' => $forTemplate->renderWith( + 'GridFieldFooter', + array( + 'Colspan' => count($gridField->getColumns()) + ) + ) ); } } diff --git a/forms/gridfield/GridFieldLevelup.php b/forms/gridfield/GridFieldLevelup.php index 0e63e032b..d15ed27d1 100644 --- a/forms/gridfield/GridFieldLevelup.php +++ b/forms/gridfield/GridFieldLevelup.php @@ -1,10 +1,13 @@ $gridField->renderWith('GridFieldToolbarHeader') diff --git a/forms/gridfield/GridFieldViewButton.php b/forms/gridfield/GridFieldViewButton.php index 729196a6d..05a74ed19 100644 --- a/forms/gridfield/GridFieldViewButton.php +++ b/forms/gridfield/GridFieldViewButton.php @@ -1,9 +1,11 @@ null); } - } diff --git a/forms/gridfield/GridState.php b/forms/gridfield/GridState.php index 3716ab1f0..f94719a87 100644 --- a/forms/gridfield/GridState.php +++ b/forms/gridfield/GridState.php @@ -1,13 +1,14 @@ byID($itemID); - if($item) return $item->delete(); + + if($item) { + return $item->delete(); + } } /** diff --git a/model/DataModel.php b/model/DataModel.php index 54ac6cd49..2a2d07ac1 100644 --- a/model/DataModel.php +++ b/model/DataModel.php @@ -1,45 +1,73 @@ * $model = new DataModel; * $mainMenu = $model->SiteTree->where('"ParentID" = 0 AND "ShowInMenus" = 1'); + * + * + * @package framework + * @subpackage model */ class DataModel { + + /** + * @var DataModel + */ protected static $inst; + /** + * @var array $customDataLists + */ + protected $customDataLists = array(); + /** * Get the global DataModel. + * + * @return DataModel */ public static function inst() { - if(!self::$inst) self::$inst = new self; + if(!self::$inst) { + self::$inst = new self; + } + return self::$inst; } /** - * Set the global DataModel, used when data is requested from static methods. + * Set the global DataModel, used when data is requested from static + * methods. + * + * @return DataModel */ public static function set_inst(DataModel $inst) { self::$inst = $inst; } - //////////////////////////////////////////////////////////////////////// - - protected $customDataLists = array(); - + /** + * @param string + * + * @return DataList + */ public function __get($class) { if(isset($this->customDataLists[$class])) { return clone $this->customDataLists[$class]; } else { $list = DataList::create($class); $list->setDataModel($this); + return $list; } } + /** + * @param string + * @param DataList + */ public function __set($class, $item) { $item = clone $item; $item->setDataModel($this); diff --git a/model/DataQuery.php b/model/DataQuery.php index b32a50cac..4270f3597 100644 --- a/model/DataQuery.php +++ b/model/DataQuery.php @@ -14,7 +14,7 @@ class DataQuery { /** - * @var String + * @var string */ protected $dataClass; @@ -756,11 +756,16 @@ class DataQuery { /** * Represents a subgroup inside a WHERE clause in a {@link DataQuery} * - * Stores the clauses for the subgroup inside a specific {@link SQLQuery} object. + * Stores the clauses for the subgroup inside a specific {@link SQLQuery} + * object. + * * All non-where methods call their DataQuery versions, which uses the base * query object. + * + * @package framework */ class DataQuery_SubGroup extends DataQuery { + protected $whereQuery; public function __construct(DataQuery $base, $connective) { @@ -790,6 +795,7 @@ class DataQuery_SubGroup extends DataQuery { if($filter) { $this->whereQuery->addWhere($filter); } + return $this; } @@ -806,6 +812,7 @@ class DataQuery_SubGroup extends DataQuery { if($filter) { $this->whereQuery->addWhereAny($filter); } + return $this; } @@ -814,8 +821,14 @@ class DataQuery_SubGroup extends DataQuery { // We always need to have something so we don't end up with something like '... AND () AND ...' return '1=1'; } - $sql = DB::getConn()->sqlWhereToString($this->whereQuery->getWhere(), $this->whereQuery->getConnective()); + + $sql = DB::getConn()->sqlWhereToString( + $this->whereQuery->getWhere(), + $this->whereQuery->getConnective() + ); + $sql = preg_replace('[^\s*WHERE\s*]', '', $sql); + return $sql; } } diff --git a/model/HasManyList.php b/model/HasManyList.php index 8d30a5482..7b2159963 100644 --- a/model/HasManyList.php +++ b/model/HasManyList.php @@ -1,9 +1,13 @@ foreignKey = $foreignKey; } @@ -36,7 +41,9 @@ class HasManyList extends RelationList { /** * Adds the item to this relation. + * * It does so by setting the relationFilters. + * * @param $item The DataObject to be added, or its ID */ public function add($item) { @@ -66,11 +73,14 @@ class HasManyList extends RelationList { /** * Remove an item from this relation. + * * Doesn't actually remove the item, it just clears the foreign key value. - * @param $itemID The ID of the item to be removed + * + * @param $itemID The ID of the item to be removed. */ public function removeByID($itemID) { $item = $this->byID($itemID); + return $this->remove($item); } diff --git a/model/ManyManyList.php b/model/ManyManyList.php index a0c0d7b00..0f3b789ce 100644 --- a/model/ManyManyList.php +++ b/model/ManyManyList.php @@ -1,7 +1,10 @@ + * + * name: Oembed + * --- * Oembed: * providers: - * {pattern}: - * {endpoint}/true + * 'http://*.youtube.com/watch*': + * 'http://www.youtube.com/oembed/' * autodiscover: - * true/false + * true + * + * + * @package framework + * @subpackage oembed */ class Oembed { @@ -178,6 +187,10 @@ class Oembed { } } +/** + * @package framework + * @subpackage oembed + */ class Oembed_Result extends ViewableData { /** * JSON data fetched from the Oembed URL.