diff --git a/config_entity_example/config_entity_example.info.yml b/config_entity_example/config_entity_example.info.yml index 56127ec..c40afb6 100644 --- a/config_entity_example/config_entity_example.info.yml +++ b/config_entity_example/config_entity_example.info.yml @@ -3,5 +3,3 @@ type: module description: 'TODO: Description of module' package: Example modules core: 8.x -files: - - tests/config_entity_example.test diff --git a/config_entity_example/config_entity_example.local_actions.yml b/config_entity_example/config_entity_example.local_actions.yml index 79dd2a6..b8d8f5b 100644 --- a/config_entity_example/config_entity_example.local_actions.yml +++ b/config_entity_example/config_entity_example.local_actions.yml @@ -1,5 +1,15 @@ +# Add some local task links to facilitate navigation. + config_entity_example_add_action: route_name: robot.add title: 'Add robot' appears_on: - robot.list + +config_entity_example_list_action: + route_name: robot.list + title: 'List Robots' + appears_on: + - robot.add + - robot.edit + - robot.delete diff --git a/config_entity_example/config_entity_example.module b/config_entity_example/config_entity_example.module index a59d14b..08bcdc4 100644 --- a/config_entity_example/config_entity_example.module +++ b/config_entity_example/config_entity_example.module @@ -6,10 +6,21 @@ */ /** + * @defgroup config_entity_example Example: Config Entity + * @ingroup examples + * @{ + * Implement a Config Entity. + * + * This module demonstrates implementing a Config Entity. + * + * TODO: More and better documentation here. + */ + +/** * Implements hook_permission(). * * @return array - * An associative array containing module permissions. + * An associative array containing module permissions. */ function config_entity_example_permission() { // Define the administer permission for the robot config entity. @@ -21,4 +32,8 @@ function config_entity_example_permission() { ); return $permissions; -} \ No newline at end of file +} + +/** + * @} End of "defgroup config_entity_example". + */ diff --git a/config_entity_example/config_entity_example.routing.yml b/config_entity_example/config_entity_example.routing.yml index 066be4f..9adbcc6 100644 --- a/config_entity_example/config_entity_example.routing.yml +++ b/config_entity_example/config_entity_example.routing.yml @@ -5,7 +5,8 @@ robot.list: path: '/examples/config_entity_example' defaults: - # TODO: explain by what magic '_entity_list' turns into using the entity list controller. + # '_entity_list' tells Drupal to use an entity list controller. + # This makes it easy to generate lists of entities. _entity_list: 'robot' _title: 'Config Entity Example' requirements: diff --git a/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php b/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php index 2e153e5..7df7d8a 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php +++ b/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php @@ -3,6 +3,7 @@ * @file * Contains Drupal\config_entity_example\Controller\RobotListController. */ + namespace Drupal\config_entity_example\Controller; use Drupal\Core\Config\Entity\ConfigEntityListController; @@ -10,7 +11,12 @@ use Drupal\Core\Entity\EntityInterface; /** * Class RobotListController + * + * @TODO: Explain how routing's '_entity_list' uses the entity list controller. + * * @package Drupal\config_entity_example\Controller + * + * @ingroup config_entity_example */ class RobotListController extends ConfigEntityListController { @@ -18,7 +24,7 @@ class RobotListController extends ConfigEntityListController { * Builds the header row for the entity listing. * * @return array - * A render array structure of header strings. + * A render array structure of header strings. */ public function buildHeader() { $header['label'] = $this->t('Robot'); @@ -30,10 +36,10 @@ class RobotListController extends ConfigEntityListController { * Builds a row for an entity in the entity listing. * * @param EntityInterface $entity - * The entity for which to build the row. + * The entity for which to build the row. * * @return array - * A render array of the table row for displaying the entity. + * A render array of the table row for displaying the entity. */ public function buildRow(EntityInterface $entity) { $row['label'] = $this->getLabel($entity); diff --git a/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php b/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php index cc97403..8da9bb6 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php +++ b/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php @@ -13,9 +13,6 @@ namespace Drupal\config_entity_example\Entity; use Drupal\Core\Config\Entity\ConfigEntityBase; -use Drupal\Core\Entity\EntityStorageControllerInterface; -use Drupal\Core\Entity\Annotation\EntityType; -use Drupal\Core\Annotation\Translation; /** * Defines the robot entity. @@ -24,7 +21,6 @@ use Drupal\Core\Annotation\Translation; * entity type manager. * * The properties in the annotation are as follows: - * TODO: add a @see to the annotation docs, assuming these exist!!! * - id: The machine name of the entity type. * - label: The human-readable label of the entity type. * TODO: explain @Translation. @@ -38,6 +34,11 @@ use Drupal\Core\Annotation\Translation; * 'config_entity_example.robot.marvin.yml'. * - entity_keys: TODO. * + * + * @see annotation + * + * @ingroup config_entity_example + * * @ConfigEntityType( * id = "robot", * label = @Translation("Robot"), diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php index 055b457..da39b7e 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php +++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php @@ -13,6 +13,8 @@ namespace Drupal\config_entity_example\Form; * Provides the add form for our Robot entity. * * @package Drupal\config_entity_example\Form + * + * @ingroup config_entity_example */ class RobotAddForm extends RobotFormBase { @@ -22,11 +24,12 @@ class RobotAddForm extends RobotFormBase { * For our add form, we only need to change the text of the submit button. * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. + * An associative array containing the current state of the form. * * @return array + * An array of supported actions for the current entity form. */ protected function actions(array $form, array &$form_state) { $actions = parent::actions($form, $form_state); diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php index 5625478..73f6634 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php +++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php @@ -19,55 +19,67 @@ use Drupal\Core\Entity\EntityConfirmFormBase; * EntityConfirmFormBase instead. * * @package Drupal\config_entity_example\Form + * + * @ingroup config_entity_example */ class RobotDeleteForm extends EntityConfirmFormBase { /** + * Gather a confirmation question. + * * The question is used a a title in our confirm form. For delete confirm * forms, this typically takes the form of "Are you sure you want to * delete...", including the entity label. * * @return string + * Translated string. */ public function getQuestion() { - return t('Are you sure you want to delete robot %label?', array( + return $this->t('Are you sure you want to delete robot %label?', array( '%label' => $this->entity->label() )); } /** + * Gather the confirmation text. + * * The confirm text is used as a the text in the button that confirms the * question posed by getQuestion(). * * @return string + * Translated string. */ public function getConfirmText() { - return t('Delete Robot'); + return $this->t('Delete Robot'); } /** + * Get the cancel route. + * * Provides the route name to go to if the user cancels the action. For entity * delete forms, this is typically the route that points at the list * controller. * * @return array + * The route to go to if the user cancels the deletion. The key is + * 'route_name'. The value is the route name. */ public function getCancelRoute() { return array( - 'route_name' => 'robot_list', + 'route_name' => 'robot.list', ); } /** - * The submit handler for the confirm form. For entity delete forms, you use - * this to delete the entity in $this->entity. + * The submit handler for the confirm form. + * + * For entity delete forms, you use this to delete the entity in + * $this->entity. * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. - * - * @return \Drupal\Core\Entity\EntityInterface|void + * An associative array containing the current state of the form. */ public function submit(array $form, array &$form_state) { // Delete the entity. @@ -79,7 +91,7 @@ class RobotDeleteForm extends EntityConfirmFormBase { ))); // Redirect the user to the list controller when complete. - $form_state['redirect_route']['route_name'] = 'robot_list'; + $form_state['redirect_route']['route_name'] = 'robot.list'; } } diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php index e342f73..c866153 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php +++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php @@ -13,6 +13,8 @@ namespace Drupal\config_entity_example\Form; * Provides the edit form for our Robot entity. * * @package Drupal\config_entity_example\Form + * + * @ingroup config_entity_example */ class RobotEditForm extends RobotFormBase { @@ -22,11 +24,12 @@ class RobotEditForm extends RobotFormBase { * For the edit form, we only need to change the text of the submit button. * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. + * An associative array containing the current state of the form. * * @return array + * An array of supported actions for the current entity form. */ protected function actions(array $form, array &$form_state) { $actions = parent::actions($form, $form_state); diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php index 1709b31..c1b43d0 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php +++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php @@ -19,21 +19,23 @@ use Drupal\Core\Entity\EntityFormController; * but instead through the child classes of RobotAddForm and RobotEditForm. * * @package Drupal\config_entity_example\Form + * + * @ingroup config_entity_example */ class RobotFormBase extends EntityFormController { /** * Overrides Drupal\Core\Entity\EntityFormController::form(). * - * Build the entity add/edit form. + * Builds the entity add/edit form. * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. + * An associative array containing the current state of the form. * * @return array - * An associative array containing the robot add/edit form. + * An associative array containing the robot add/edit form. */ public function buildForm(array $form, array &$form_state) { // Get anything we need form the base class. @@ -74,11 +76,12 @@ class RobotFormBase extends EntityFormController { * To set the submit button text, we need to override actions(). * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. + * An associative array containing the current state of the form. * * @return array + * An array of supported actions for the current entity form. */ protected function actions(array $form, array &$form_state) { // Get the basic actins from the base class. @@ -95,9 +98,9 @@ class RobotFormBase extends EntityFormController { * Overrides Drupal\Core\Entity\EntityFormController::validate(). * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. + * An associative array containing the current state of the form. */ public function validate(array $form, array &$form_state) { parent::validate($form, $form_state); @@ -114,9 +117,9 @@ class RobotFormBase extends EntityFormController { * for entity form controllers. * * @param array $form - * An associative array containing the structure of the form. + * An associative array containing the structure of the form. * @param array $form_state - * An associative array containing the current state of the form. + * An associative array containing the current state of the form. */ public function save(array $form, array &$form_state) { // Get the entity from the class variable. We don't need to do this, but diff --git a/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php b/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php index f5c2ebc..ef31a3a 100644 --- a/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php +++ b/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php @@ -17,6 +17,8 @@ use Drupal\Core\Session\AccountInterface; * The access controller determines access to Robot entities. * * @see \Drupal\config_entity_example\Entity\Robot. + * + * @ingroup config_entity_example */ class RobotAccessController extends EntityAccessController {