From 894f574d29a45e884235c4046ac7433c806d4097 Mon Sep 17 00:00:00 2001 From: Roy Segall Date: Mon, 4 Aug 2014 09:22:05 +0300 Subject: [PATCH 1/5] Improve the readme file. --- README.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6cdc2e9..48300dd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,41 @@ [![Build Status](https://travis-ci.org/Gizra/entity_validator.svg?branch=7.x-1.x)](https://travis-ci.org/Gizra/entity_validator) # Entity Validator +The entity validator try to solve a simple problem in Drupal 7: validate the +entity object before they written into the DB. -Programmatically validate entities. +The first thought that cross your head is: "When is submit a node's form i get +errors. What's the problem?". The problem is that the validation is done in the +form level. If you take for example the feed module you can understand the issue +a little bit more. The feed module can create nodes without titles. This is +wrong since the node title is a required field. + +## The basics +*All the example are taken form the entity validator example module.* + +You'll first need to declare a ctools plugin directory for you module: +```php +/** + * Implements hook_ctools_plugin_directory(). + */ +function entity_validator_example_ctools_plugin_directory($module, $plugin) { + if ($module == 'entity_validator') { + return 'plugins/' . $plugin; + } +} + +``` + +After that you'll need to create a the next structure: +|- validator + +|-- *entity_type* + +|---- *entity_bundle* + +|------ *entity_type*__*entity_bundle*.inc + +|------ *name_of_class*.class.php ## Credits From 9aa2015e83137ce6e7d5dd00aa43a98f6818df12 Mon Sep 17 00:00:00 2001 From: Roy Segall Date: Mon, 4 Aug 2014 10:02:58 +0300 Subject: [PATCH 2/5] More documentation. --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/README.md b/README.md index 48300dd..d95521b 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,75 @@ After that you'll need to create a the next structure: |------ *name_of_class*.class.php +If we look on the entity_validator_example module you'll see a file called +*node__article.inc*. This is the plugin definition: +```php +$plugin = array( + 'label' => t('Article'), + 'description' => t('Validate the article content type.'), + 'entity_type' => 'node', + 'bundle' => 'article', + 'class' => 'EntityValidatorExampleArticleValidator', +); + +``` +In this case we validate a node article. The validator handler, +*EntityValidatorExampleArticleValidator*, is in the file +*EntityValidatorExampleArticleValidator.class.php*. + +## Start validating +After defining the validator handler we can start and set the method for that: +```php + /** + * Overrides EntityValidateBase::getFieldsInfo(). + */ + public function getFieldsInfo() { + $fields = parent::getFieldsInfo(); + + $fields['title']['validators'][] = 'validateTitleText'; + $fields['body']['validators'][] = 'validateBodyText'; + + return $fields; + } +``` + +In this method we are defining the fields and properties handlers. There are two +type of handlers: + - Validator - In a validator method you can set errors according to the + value the the field/property have. + - Pre-process - Although this is not in use you can change the field/property + value. + +The example above validate the title property and the body field. Although +required fields or a mandatory properties are automatically checked they not +empty, the example module add another validators as a proof of concept: +```php + /** + * Validate the title is at least 3 characters long. + */ + public function validateTitleText($field_name, $value) { + if (strlen($value) < 3) { + $this->setError($field_name, 'The @field should be at least 3 characters long.'); + } + } + + /** + * Validate the description has the word "Gizra". + */ + public function validateBodyText($field_name, $value) { + if (empty($value['value']) || strpos($value['value'], 'Drupal') === FALSE) { + $this->setError($field_name, 'The @field should have the word "Drupal".'); + } + } +``` + +You can see that the *validateTitleText* method checked the length of the +string. +You can also see that the the text we set as an error did not pass +through a t() function. That's correct. When displaying the errors to the user, +by default, the text is passed via t(). We get to this part later. + + ## Credits * Developerd by [Gizra](http://gizra.com) From 7d8764959f8cf1341d72e2a7487e0c1d1a0a839b Mon Sep 17 00:00:00 2001 From: Roy Segall Date: Tue, 5 Aug 2014 09:29:05 +0300 Subject: [PATCH 3/5] More doc! --- README.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index d95521b..f3d16f6 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,18 @@ # Entity Validator The entity validator try to solve a simple problem in Drupal 7: validate the -entity object before they written into the DB. +entity object before written them into the DB. That problem solved in Drupal 8 +due to the OOP approach and the understanding that the written data to the DB +need to be valid. -The first thought that cross your head is: "When is submit a node's form i get +The first thought that cross your head is: "When is submit the node's form i get errors. What's the problem?". The problem is that the validation is done in the form level. If you take for example the feed module you can understand the issue a little bit more. The feed module can create nodes without titles. This is wrong since the node title is a required field. ## The basics -*All the example are taken form the entity validator example module.* +*All the example are taken from the entity validator example module.* You'll first need to declare a ctools plugin directory for you module: ```php @@ -26,7 +28,7 @@ function entity_validator_example_ctools_plugin_directory($module, $plugin) { ``` -After that you'll need to create a the next structure: +After that you'll need to create the next files structure: |- validator |-- *entity_type* @@ -69,16 +71,17 @@ After defining the validator handler we can start and set the method for that: } ``` -In this method we are defining the fields and properties handlers. There are two +In this method we defining the fields and properties handlers. There are two type of handlers: - Validator - In a validator method you can set errors according to the - value the the field/property have. - - Pre-process - Although this is not in use you can change the field/property + value the field/property have. + - Pre-process - Although this is not in use, you can change the field/property value. -The example above validate the title property and the body field. Although -required fields or a mandatory properties are automatically checked they not -empty, the example module add another validators as a proof of concept: +The next example set validators to the title property and the body field. +Although required fields or a mandatory properties are automatically checked +for not being empty, the example module add another validators as a proof of +concept: ```php /** * Validate the title is at least 3 characters long. @@ -99,11 +102,13 @@ empty, the example module add another validators as a proof of concept: } ``` -You can see that the *validateTitleText* method checked the length of the -string. +You can see that the *validateTitleText* method checking the length of the +string. You can also see that the the text we set as an error did not pass -through a t() function. That's correct. When displaying the errors to the user, -by default, the text is passed via t(). We get to this part later. +through t(). That's correct. When displaying the errors to the user, by default, +the text is passed via t(). We get to this part later. + + ## Credits From 46b33db3011a3d8dfb75788a4912693744ff5394 Mon Sep 17 00:00:00 2001 From: Roy Segall Date: Tue, 5 Aug 2014 10:01:49 +0300 Subject: [PATCH 4/5] More doc! --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/README.md b/README.md index f3d16f6..43b9d51 100644 --- a/README.md +++ b/README.md @@ -108,8 +108,83 @@ You can also see that the the text we set as an error did not pass through t(). That's correct. When displaying the errors to the user, by default, the text is passed via t(). We get to this part later. +Another handler is the pre-process handler: +```php + /** + * Overrides EntityValidateBase::getFieldsInfo(). + */ + public function getFieldsInfo() { + $fields = parent::getFieldsInfo(); + + $fields['title']['preprocess'][] = 'preprocessTitleText'; + + return $fields; + } + + /** + * Altering the title of the node. + */ + public function preprocessTitleText($field_name, $value) { + return 'This is a new title'; + } +``` + +## Interact with the entity validator +After setting the methods you, or of your modules, need to validate an object. +First initialize the object it self: +```php +$handler = entity_validator_get_validator_handler('node', 'article'); +``` + +You can validate an object in three ways: +1. With exceptions: +```php +$handler->validate($node); +``` +If there any errors set by the methods you'll get them as an exceptions. + +2. If you just want to see if there any error, without getting exceptions, you +can use a silent mode: + +```php +$result = $handler->validate($node, TRUE); +``` +The $result will be a boolean variable. + +3. You can handle the errors by your self. You'll need first to validate the +object in a silent way, exactly like in 2. You can get the errors squashed, all +the placeholders from the errors replaced by the real value, i.e: @field +replaced with the name of the field: + +```php + $result = $handler->validate($node, TRUE); + if($result) { + drupal_set_message(t('Validate in silent mode did not throw an exception.'), 'error'); + } +``` +You can get the errors without being squashed. This will return an array in the +next format: +```php + $result = $handler->getErrors(FALSE); + $expected_result = array( + 'title' => array( + array( + 'message' => 'The field @field cannot be empty.', + 'params' => array( + '@field' => 'title', + ), + ), + array( + 'message' => 'The @field should be at least 3 characters long.', + 'params' => array( + '@field' => 'title', + ), + ), + ), + ); +``` ## Credits From 8b80ae8668bad16e677ebde8ff0b64d70382d84d Mon Sep 17 00:00:00 2001 From: Roy Segall Date: Wed, 6 Aug 2014 09:49:41 +0300 Subject: [PATCH 5/5] A lot more doc! --- README.md | 67 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 43b9d51..3a4e219 100644 --- a/README.md +++ b/README.md @@ -2,20 +2,20 @@ # Entity Validator The entity validator try to solve a simple problem in Drupal 7: validate the -entity object before written them into the DB. That problem solved in Drupal 8 +entity object before it's written into the DB. That problem solved in Drupal 8 due to the OOP approach and the understanding that the written data to the DB need to be valid. -The first thought that cross your head is: "When is submit the node's form i get -errors. What's the problem?". The problem is that the validation is done in the -form level. If you take for example the feed module you can understand the issue -a little bit more. The feed module can create nodes without titles. This is -wrong since the node title is a required field. +The first thought that cross your mind is: "When i submit a node's form i get +errors. What's the problem?". The problem is that the validation process done at +the form level. If you take for example the feeds module you can understand the +issue a little bit more: feeds can create nodes without titles. This is wrong +since the node's title is a required field. ## The basics -*All the example are taken from the entity validator example module.* +*All the examples are taken from the entity validator example module.* -You'll first need to declare a ctools plugin directory for you module: +You'll first need to declare a ctools plugin directory for your module: ```php /** * Implements hook_ctools_plugin_directory(). @@ -29,6 +29,7 @@ function entity_validator_example_ctools_plugin_directory($module, $plugin) { ``` After that you'll need to create the next files structure: + |- validator |-- *entity_type* @@ -40,7 +41,7 @@ After that you'll need to create the next files structure: |------ *name_of_class*.class.php If we look on the entity_validator_example module you'll see a file called -*node__article.inc*. This is the plugin definition: +*node__article.inc* ```php $plugin = array( 'label' => t('Article'), @@ -51,12 +52,12 @@ $plugin = array( ); ``` -In this case we validate a node article. The validator handler, +This is a validator for a node article. The validator handler, *EntityValidatorExampleArticleValidator*, is in the file *EntityValidatorExampleArticleValidator.class.php*. ## Start validating -After defining the validator handler we can start and set the method for that: +After defining the validator handler we can start and set the methods: ```php /** * Overrides EntityValidateBase::getFieldsInfo(). @@ -71,16 +72,16 @@ After defining the validator handler we can start and set the method for that: } ``` -In this method we defining the fields and properties handlers. There are two -type of handlers: - - Validator - In a validator method you can set errors according to the - value the field/property have. +The method defines the fields and properties handlers. There are two type of +handlers: + - Validator - You'll set errors according to the value the field/property + have. - Pre-process - Although this is not in use, you can change the field/property value. The next example set validators to the title property and the body field. -Although required fields or a mandatory properties are automatically checked -for not being empty, the example module add another validators as a proof of +Although required fields or mandatory properties are automatically checked for +not being empty, the example module add another validators as a proof of concept: ```php /** @@ -102,13 +103,12 @@ concept: } ``` -You can see that the *validateTitleText* method checking the length of the -string. -You can also see that the the text we set as an error did not pass -through t(). That's correct. When displaying the errors to the user, by default, -the text is passed via t(). We get to this part later. +The *validateTitleText* method checking the length of the string. +You can see that the text we set as an error did not passed through t(). That's +correct. When displaying the errors to the user, by default, the text will +passed through t(). We'll get to this part later. -Another handler is the pre-process handler: +Another handler type is the pre-process handler: ```php /** * Overrides EntityValidateBase::getFieldsInfo(). @@ -130,9 +130,7 @@ Another handler is the pre-process handler: ``` ## Interact with the entity validator -After setting the methods you, or of your modules, need to validate an object. -First initialize the object it self: - +Validating an object is pretty easy. First initialize the handler: ```php $handler = entity_validator_get_validator_handler('node', 'article'); ``` @@ -142,26 +140,31 @@ You can validate an object in three ways: ```php $handler->validate($node); ``` -If there any errors set by the methods you'll get them as an exceptions. +If there any errors set by the methods they will be thrown as an exception. 2. If you just want to see if there any error, without getting exceptions, you can use a silent mode: ```php -$result = $handler->validate($node, TRUE); + $result = $handler->validate($node, TRUE); + if ($result) { + drupal_set_message(t('Validate in silent mode did not throw an exception.'), 'error'); + } ``` The $result will be a boolean variable. 3. You can handle the errors by your self. You'll need first to validate the -object in a silent way, exactly like in 2. You can get the errors squashed, all +object in a silent way, exactly like in 2. You can get the errors squashed - all the placeholders from the errors replaced by the real value, i.e: @field replaced with the name of the field: ```php $result = $handler->validate($node, TRUE); - if($result) { - drupal_set_message(t('Validate in silent mode did not throw an exception.'), 'error'); + if ($result) { + $params['errors'] = $handler->getErrors(TRUE); + drupal_set_message(t('Validate in silent mode did not throw an exception but there are some errors: !errors', $params), 'error'); } + ``` You can get the errors without being squashed. This will return an array in the @@ -185,6 +188,8 @@ next format: ), ); ``` +This is useful when you want to handle the placeholders by your self, similar to +the [Restful](http://github.com/gizra/restful) module. ## Credits