From 71a9ff089d436ba4949d93443c80ae99f328f78a Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Sun, 11 Jul 2010 10:44:59 +0000 Subject: [PATCH] MINOR Moved class-specific documentation from doc.silverstripe.org back into class-level PHPDoc git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/branches/2.4@107725 467b73ca-7a2a-4603-9d3b-597d59a354a9 --- api/RestfulServer.php | 10 ++++- core/ManifestBuilder.php | 8 ++++ core/Session.php | 64 ++++++++++++++++++++++++++- dev/MigrationTask.php | 42 +++++++++++++++++- forms/CustomRequiredFields.php | 63 ++++++++++++++++++++++++++- forms/DropdownField.php | 67 +++++++++++++++++++++++++++++ forms/FieldGroup.php | 36 ++++++++++++++++ forms/FileField.php | 28 ++++++++++++ forms/FormAction.php | 17 ++++++++ forms/GroupedDropdownField.php | 25 +++++++++++ forms/HasManyComplexTableField.php | 26 +++++++++++ forms/HasOneComplexTableField.php | 29 +++++++++++++ forms/ImageField.php | 15 +++++++ forms/ListboxField.php | 16 +++++++ forms/LiteralField.php | 9 ++++ forms/ManyManyComplexTableField.php | 29 +++++++++++++ forms/OptionsetField.php | 45 +++++++++++++++++++ forms/SimpleImageField.php | 45 ++++++++++++++++++- forms/Tab.php | 12 ++++++ forms/TabSet.php | 23 +++++++++- forms/TextareaField.php | 12 ++++++ forms/TreeDropdownField.php | 24 ++++++++++- forms/TreeMultiselectField.php | 29 ++++++++++++- parsers/ShortcodeParser.php | 48 +++++++++++++++++++-- tasks/ScheduledTask.php | 33 +++++++++++++- 25 files changed, 740 insertions(+), 15 deletions(-) diff --git a/api/RestfulServer.php b/api/RestfulServer.php index ad9fb66ad..d64c38218 100644 --- a/api/RestfulServer.php +++ b/api/RestfulServer.php @@ -29,7 +29,8 @@ * } * * - * Supported operations: + * Supported operations + * * - GET /api/v1/(ClassName)/(ID) - gets a database record * - GET /api/v1/(ClassName)/(ID)/(Relation) - get all of the records linked to this database record by the given reatlion * - GET /api/v1/(ClassName)?(Field)=(Val)&(Field)=(Val) - searches for matching database records @@ -43,17 +44,22 @@ * * - POST /api/v1/(ClassName)/(ID)/(MethodName) - executes a method on the given object (e.g, publish) * + * Search + * * You can trigger searches based on the fields specified on {@link DataObject::searchable_fields} and passed * through {@link DataObject::getDefaultSearchContext()}. Just add a key-value pair with the search-term * to the url, e.g. /api/v1/(ClassName)/?Title=mytitle. * - * Other url-modifiers: + * Other url-modifiers + * * - &limit=: Limit the result set * - &relationdepth=: Displays links to existing has-one and has-many relationships to a certain depth (Default: 1) * - &fields=: Comma-separated list of fields on the output object (defaults to all database-columns). * Handy to limit output for bandwidth and performance reasons. * - &sort=&dir= * - &add_fields=: Comma-separated list of additional fields, for example dynamic getters. + * + * Access control * * Access control is implemented through the usual Member system with Basicauth authentication only. * By default, you have to bear the ADMIN permission to retrieve or send any data. diff --git a/core/ManifestBuilder.php b/core/ManifestBuilder.php index a9fbd321f..fdc936cff 100644 --- a/core/ManifestBuilder.php +++ b/core/ManifestBuilder.php @@ -17,6 +17,14 @@ if(!defined('MANIFEST_FILE')) define("MANIFEST_FILE", TEMP_FOLDER . "/manifest-" * This information is cached so that it need not be regenerated on every * pageview. * + * Autoloading + * + * Sapphire class autoloader. Requires the ManifestBuilder to work. + * $_CLASS_MANIFEST must have been loaded up by ManifestBuilder for this to successfully load classes. + * Classes will be loaded from any PHP file within the application. If your class contains an underscore, + * for example, Page_Controller, then the filename is expected to be the stuff before the underscore. + * In this case, Page.php. + * * @see main.php, __autoload(), SSViewer, Requirements::themedCSS() * @package sapphire * @subpackage core diff --git a/core/Session.php b/core/Session.php index 683fb4f9e..859e8b9d0 100644 --- a/core/Session.php +++ b/core/Session.php @@ -10,7 +10,69 @@ * each with their own session. * * The instance object is basically just a way of manipulating a set of nested maps, and isn't specific to session data. - * This class is currently really basic and could do with a more well-thought-out implementation + * + * Saving Data + * + * You can write a value to a users session from your PHP code using the static function {@link Session::set()}. You can add this line in any function or file you wish to save the value. + * + * + * Session::set('MyValue', 6); + * + * + * Saves the value of "6" to the MyValue session data. You can also save arrays or serialized objects in session (but note there may be size restrictions as to how much you can save) + * + * + * // save a variable + * $var = 1; + * Session::set('MyVar', $var); + * + * // saves an array + * Session::set('MyArrayOfValues', array('1','2','3')); + * + * // saves an object (you'll have to unserialize it back) + * $object = new Object(); + * + * Session::set('MyObject', serialize($object)); + * + * + * Accessing Data + * + * Once you have saved a value to the Session you can access it by using the {@link Session::get()} function. + * Like the {@link Session::set()} function you can use this anywhere in your PHP files. + * + * The values in the comments are the values stored from the previous example. + * + * + * function bar() { + * $value = Session::get('MyValue'); // $value = 6 + * $var = Session::get('MyVar'); // $var = 1 + * $array = Session::get('MyArrayOfValues'); // $array = array(1,2,3) + * $object = Session::get('MyObject', unserialize($object)); // $object = Object() + * } + * + * + * You can also get all the values in the session at once. This is useful for debugging. + * + * + * Session::getAll(); // returns an array of all the session values. + * + * + * Clearing Data + * + * Once you have accessed a value from the Session it doesn't automatically wipe the value from the Session, you have to specifically remove it. To clear a value you can either delete 1 session value by the name that you saved it + * + * + * Session::clear('MyValue'); // myvalue is no longer 6. + * + * + * Or you can clear every single value in the session at once. Note SilverStripe stores some of its own session data including form and page comment information. None of this is vital but clear_all will clear everything. + * + * + * Session::clearAll(); + * + * + * @see Cookie + * @todo This class is currently really basic and could do with a more well-thought-out implementation. * * @package sapphire * @subpackage control diff --git a/dev/MigrationTask.php b/dev/MigrationTask.php index 26a00ef57..ff3bd861e 100644 --- a/dev/MigrationTask.php +++ b/dev/MigrationTask.php @@ -2,7 +2,47 @@ /** * A migration task is a build task that is reversible. * - * Up and Down methods must be implemented. + * Creating Migration Tasks + * + * To create your own migration task all you need to do is define your own subclass of MigrationTask and define the following functions + * + * mysite/code/MyMigrationTask.php + * + * + * class MyMigrationTask extends BuildTask { + * + * protected $title = "My Database Migrations"; // title of the script + * protected $description = "Description"; // description of what it does + * + * function run($request) { + * if ($request->param('Direction') == 'down') { + * $this->down(); + * } else { + * $this->up(); + * } + * } + * + * function up() { + * // do something when going from old -> new + * } + * + * function down() { + * // do something when going from new -> old + * } + * } + * + * + * Running Migration Tasks + * To run any tasks you can find them under the dev/ namespace. To run the above script you would need to run + * the following and note - Either the site has to be in [devmode](debugging) or you need to add ?isDev=1 to the URL + * + * + * // url to visit if in dev mode. + * http://www.yoursite.com/dev/tasks/MyMigrationTask + * + * // url if you are in live mode but need to run this + * http://www.yoursite.com/dev/tasks/MyMigrationTask?isDev=1 + * * * @package sapphire * @subpackage dev diff --git a/forms/CustomRequiredFields.php b/forms/CustomRequiredFields.php index b34268623..2d4c26dff 100755 --- a/forms/CustomRequiredFields.php +++ b/forms/CustomRequiredFields.php @@ -1,6 +1,67 @@ requireField('FieldName') is the php equivalent) + * + * An example for creating required fields only if payment type is CreditCard: + * + * + * new CustomRequiredFields( + * array( + * "PaymentMethod", + * array( + * "js" => " + * for( var i = 0; i <= this.elements.PaymentMethod.length -1; i++){ + * if(this.elements.PaymentMethod[i].value == 'CC' && this.elements.PaymentMethod[i].checked == true){ + * require('CardHolderName'); + * require('CreditCardNumber'); + * require('DateExpiry'); + * } + * } + * + * ", + * "php" => 'if($data[PaymentMethod] == "CC") { + * $this->requireField($field,"$field is required","required"); + * $this->requireField("CardHolderName", $data); + * $this->requireField("CreditCardNumber", $data); + * $this->requireField("DateExpiry", $data); + * }', + * ) + * ) + * ); + * + * + * And example for confirming mobile number and email address: + * + * + * $js = << $js, 'php' => 'return true;'), array('js' => $js2, 'php'=>'return true;'))); + * + * * @package forms * @subpackage validators */ diff --git a/forms/DropdownField.php b/forms/DropdownField.php index d35be2e1c..6994f7bf9 100755 --- a/forms/DropdownField.php +++ b/forms/DropdownField.php @@ -1,6 +1,73 @@ tag. + * + * Setting a $has_one relation + * + * Using here an example of an art gallery, with Exhibition pages, + * each of which has a Gallery they belong to. The Gallery class is also user-defined. + * + * static $has_one = array( + * 'Gallery' => 'Gallery', + * ); + * + * public function getCMSFields() { + * $fields = parent::getCMSFields(); + * $galleries = DataObject::get('Gallery'); + * if ($galleries) { + * $galleries = $galleries->toDropdownMap('ID', 'Title', '(Select one)', true); + * } + * $fields->addFieldToTab('Root.Content.Main', new DropdownField('GalleryID', 'Gallery', $galleries), 'Content'); + * + * + * As you see, you need to put "GalleryID", rather than "Gallery" here. + * + * Populate with Array + * + * Example model defintion: + * + * class MyObject extends DataObject { + * static $db = array( + * 'Country' => "Varchar(100)" + * ); + * } + * + * + * Exampe instantiation: + * + * new DropdownField( + * 'Country', + * 'Country', + * array( + * 'NZ' => 'New Zealand', + * 'US' => 'United States' + * 'GEM'=> 'Germany' + * ) + * ); + * + * + * Populate with Enum-Values + * + * You can automatically create a map of possible values from an {@link Enum} database column. + * + * Example model definition: + * + * class MyObject extends DataObject { + * static $db = array( + * 'Country' => "Enum('New Zealand,United States,Germany','New Zealand')" + * ); + * } + * + * + * Field construction: + * + * new DropdownField( + * 'Country', + * 'Country', + * singleton('MyObject')->dbObject('Country')->enumValues() + * ); + * + * * @package forms * @subpackage fields-basic */ diff --git a/forms/FieldGroup.php b/forms/FieldGroup.php index 27c87d503..1090d05f7 100755 --- a/forms/FieldGroup.php +++ b/forms/FieldGroup.php @@ -5,6 +5,42 @@ * * Note: the child fields within a field group aren't rendered using FieldHolder(). Instead, * SmallFieldHolder() is called, which just prefixes $Field with a