Create a Content Entity Example

@cgalli: looks like you managed to create windows file endings again :)

Attaching the same patch, just with unix line endings, converted with dos2unix.

Ossum, thanks. :-)

1. +++ b/content_entity_example/content_entity_example.module
   @@ -0,0 +1,48 @@
   + */
   +function content_entity_example_permission() {
   +  return array(
   

   Permissions are usually readable strings, like administer content_entity_example entity.

2. +++ b/content_entity_example/lib/Drupal/content_entity_example/ContentEntityExampleInterface.php
   @@ -0,0 +1,48 @@
   +  /**
   +   * Returns the identifier.
   +   *
   +   * @return int
   +   *   The entity identifier.
   +   */
   +  public function id();
   +  /**
   +   * Returns the entity UUID (Universally Unique Identifier).
   +   *
   +   * The UUID is guaranteed to be unique and can be used to identify an entity
   +   * across multiple systems.
   +   *
   +   * @return string
   +   *   The UUID of the entity.
   +   */
   +  public function uuid();
   +  /**
   +   * Return the Value of ContentEntityExample Field.
   +   *
   +   * @return string
   +   *   The content of the field.
   +   */
   +  public function getContentEntityExampleField();
   +  /**
   +   * Defines the base fields of the entity type.
   +   *
   +   * @param string $entity_type
   +   *   Name of the entity type
   +   *
   +   * @return \Drupal\Core\Field\FieldDefinitionInterface[]
   +   *   An array of entity field definitions, keyed by field name.
   +   */
   +  public static function baseFieldDefinitions(EntityTypeInterface $entity_type);
   

   No need to repeat these methods, they exist in the parent. You should however extend from ContentEntityInterface.

   You only want to add method for your own fields, when useful.

3. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -0,0 +1,144 @@
   + *     "translation" = "Drupal\content_translation\ContentTranslationController"
   ...
   + *   translatable = TRUE,
   

   If you actually want to support translations, you should provide a per-translation table. See EntityTestMul for an example. See also the corresponding table definitions. Most of your fields will move to the _field_data table.

4. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -0,0 +1,144 @@
   +    $fields['ceeid'] = FieldDefinition::create('integer')
   +      ->setLabel(t('ID'))
   +      ->setDescription(t('The ID of the ContentEntityExample entity.'))
   +      ->setReadOnly(TRUE);
   

   I would name this just "id". Then you also don't need to override the id() method (will not be necessary anymore after #2182239: Improve ContentEntityBase::id() for better DX anyway)

   The definitions are IMHO betterreadable with an empty line between them.

5. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -0,0 +1,144 @@
   +      ->setPropertyConstraints('value', array('Length' => array('max' => 32)))
   ...
   +        'max_length' => 255,
   +        'text_processing' => 0,
   

   Conflicting length definitions, you only need one of those (max_length easier).

6. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -0,0 +1,144 @@
   +    $fields['type'] = FieldDefinition::create('string')
   +      ->setLabel(t('Type'))
   +      ->setDescription(t('The bundle of the ContentEntityExample entity.'))
   +      ->setRequired(TRUE);
   

   You don't have bundles, so I would leave this out.

   I think it's easier to have an example with bundles and one with, to see the difference. So let's add one without bundles first.

7. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -0,0 +1,144 @@
   +    $fields['user_id'] = FieldDefinition::create('entity_reference')
   +      ->setLabel(t('User ID'))
   +      ->setDescription(t('The ID of the associated user.'))
   +      ->setSettings(array('target_type' => 'user'))
   +      ->setTranslatable(TRUE);
   

   Your entity (the interface) should implement EntityOwnerInterface in this case, then you'll need to implement the corresponding methods (setOwnerId() and so on). Other modules can then rely on that (comment does and entity_reference for example).

   WE should also add changed and created fields, there are special field types for that that just work, see Node.

8. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -0,0 +1,144 @@
   +    $fields['content_entity_example_field'] = FieldDefinition::create('string')
   +      ->setLabel(t('First ContentEntityExample Field'))
   +      ->setDescription(t('One field of the ContentEntityExample entity.'))
   +      ->setTranslatable(TRUE)
   +      ->setPropertyConstraints('value', array('Length' => array('max' => 32)))
   +      ->setSettings(array(
   +        'default_value' => '',
   +        'max_length' => 255,
   +        'text_processing' => 0,
   +      ))
   +      ->setDisplayOptions('view', array(
   +        'label' => 'Above',
   +        'type' => 'string',
   +        'weight' => -5,
   +      ))
   +      ->setDisplayOptions('form', array(
   +        'type' => 'string',
   +        'weight' => -5,
   +      ))
   +      ->setDisplayConfigurable('form', TRUE)
   +      ->setDisplayConfigurable('view', TRUE);
   +
   +    return $fields;
   

   Not sure how useful this really is?

   Maybe if you use a different field type, like a text field with a text that has a format?

   I would also give it a real name, maybe "description"?

9. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/Controller/ContentEntityExampleListController.php
   @@ -0,0 +1,38 @@
   +    $row['label'] = l($this->getLabel($entity), 'content-entity-example/' . $entity->id());
   

   Should use \Drupal:l() and the route name instead of the path.

1. +++ b/content_entity_example/lib/Drupal/content_entity_example/ContentEntityExampleInterface.php
   @@ -5,44 +5,12 @@
   +interface ContentEntityExampleInterface extends ContentEntityInterface, EntityOwnerInterface {
   

   You can add EntityChangedInterface to the list now.

2. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -44,51 +43,78 @@ use Drupal\content_entity_example\ContentEntityExampleInterface;
   -    $fields['langcode'] = FieldDefinition::create('language')
   -      ->setLabel(t('Language code'))
   -      ->setDescription(t('The language code of ContentEntityExample entity.'));
   

   Hm, having a langcode is very common for content entities, even if they're not translatable. Fine, though.

3. +++ b/content_entity_example/lib/Drupal/content_entity_example/Entity/ContentEntityExample.php
   @@ -106,38 +132,18 @@ class ContentEntityExample extends ContentEntityBase implements ContentEntityExa
   -    $fields['user_id'] = FieldDefinition::create('entity_reference')
   +    $fields['uid'] = FieldDefinition::create('entity_reference')
   

   Why this rename? I actually liked user_id more :)

You can add EntityChangedInterface to the list now.

It'd be great to have some explanation of each of these interfaces, and what they deliver to the implementation.

+1 on langcode. Seems like a best practice, and best practices are what we're here to explain.

+1 on user_id as well. Descriptive and readable is better.

There was some discussion in email about what to name the entities. I like that the config entity example has 'Robot,' which is distinct and understandable. 'content_entity_example' is the same name as the module, leading to confusion. Let's dream up something that we're modeling here, so that we can then explain how our model maps into an entity implementation.

About naming, I agree that something specific would be nicer, the downside is that it then violates the module namespace. But maybe we can solve that by adding a comment on the entity class and state that real entities must live within the namespace of out their module?

Because we'll eventually need 3 different entity types, the idea is to have this as starting point for simple content entities and a more complex one with translatable storage, revisions, bundles (which will need a config entity) and so on. I thought about relying on the config_entity_example module for that, but robots isn't really a good example for that ;)

Well my point is that there's presumably a design phase where you discover that you need to make an entity in order to represent something. So, for instance, an address book where you have to represent people and their addresses. This gives the reader something to hang it all on, rather than simply 'this is an example of a content_entity_bundle_thingie_example_no_clue_why_i_need_it.'

The module namespace isn't so relevant as the class namespace. Drupal\content_entity_example\Entity\Robot tells the whole story, and is how sane people should name things anyway. :-)

In an actual module, it would still be required to use content_entity_example_robot as the entity type ID. (Just like all other plugins, machine names, routes, ...) Namespaces don't solve that problem. But yes, naming the class like that is perfectly fine.

Entity type ID is an arbitrary string, right? So 'content_entity_example.robot' or however you want?

No, only lowercase and _ is allowed, and there will be a length limit, although it's not exactly clear yet how long that should be but likely 32 or 50 characters. That string is used for table names for fieldable entities, needs to match variable names so that upcasting works and so on.

We just tried to make that module prefix official and standardized, but it has too many dependencies, see #1862600: Entity type names/IDs are not properly namespaced by owner (e.g., taxonomy.term vs. taxonomy_term).

#1862600: Entity type names/IDs are not properly namespaced by owner (e.g., taxonomy.term vs. taxonomy_term) confirms for me why the idea of distributed all-at-once development of complex systems should induce panic attacks. :-)

Anyway, yah, now that I understand the problem, please go with 'content_entity_example_[type]' for the time being.

1. +++ b/content_entity_example/lib/Drupal/content_entity_example/Tests/ContentEntityExampleTest.php
   @@ -0,0 +1,45 @@
   +  /**
   +   * Implements getinfo().
   +   */
   +  public static function getInfo() {
   

   This doesn't actually implement getInfo(). :-) Use {@inheritdoc} instead.

2. +++ b/content_entity_example/lib/Drupal/content_entity_example/Tests/ContentEntityExampleTest.php
   @@ -0,0 +1,45 @@
   +  public function testContentEntityExample() {
   +
   +    // Listing menu not visible without permission.
   +    $this->assertNoText('Content Entity Example Listing',
   +      'The listing menu appears on the page');
   

   You have to do a drupalGet() before there's content to test.

Added some stuff based on comments and work on the config entity example. Fixed list builder (nee controller) due to https://drupal.org/node/2200867.

Wow. Just. And I thought I manually tested it too.

36: content_entity_example_36.patch queued for re-testing.

+++ b/content_entity_example/content_entity_example.module
@@ -0,0 +1,37 @@
+/**
+ * @defgroup content_entity_example Example: Content Entity
+ * @ingroup examples
+ * @{
+ * Example of how to define a content entity.
+ * }
+ */

Still would be great to have some info about what a content entity is, and why you'd use it and so forth. The whole module is kind of sparse on inline comments and other didactic stuff.

Great to have the example, though.

I'd like to keep these modules as simple as possible. Remember they're more for new people than for someone who wants to re-implement node.

Chunking out some of those other APIs into other example modules would keep things clear, I think.

Yeah, defining an entity involves a number of different API's, so we have to cover them to provide a real example. Views data is useful because that's going to be the common way to display lists of content entities and the views data integration will hopefully be provided by default at some point.

A preprocess and a twig template is currently also necessary, all core entities do that, #2023571: Support preprocessing in EntityViewBuilder would cover the default preprocess stuff while there's no issue seriously trying to add a default template for entities like entity.module in 7.x had.

36: content_entity_example_36.patch queued for re-testing.

See the issue for a more complex content entity: #2280723: Create a bundled Content Entity Example for D8

So I applied #36 and installed it.

Everything seems to work except for deletion... It gives the white screen of death, unable to show me the confirm form.

Also, we don't need hook_schema() any more, thanks to this issue: https://drupal.org/node/2259243

And it would be great if we could stop here for this example and work on the documentation. The goal here isn't to have a complete implementation, but to give people something to read so they can understand how all the pieces interact.

Fixed issue with getCancelRoute() for https://drupal.org/node/2189619

Timeline: FINISH NOW! :-)

Examples is always in a dev state; there aren't any releases. The things that matter are: 1) Whether the documentation is accurate, and 2) whether the tests pass.

Changed menu link name to reference the example module. Added hook_help() to give some context to the contact listing, and a link to the admin page.

The last patch file is empty :)

Woops... Seems like the testbot would fail that. Guess not.

Here's #56 with the interdiff from #58.

Still needs a ton of documentation. Look at other examples, especially config_entity_example, to see what's needed.

Basically, Examples are a how-to tutorial that you can run.

When I try to enable the module "content_entity_example" of the #61 patch

This message appear and drupal8 fail

Error

Status message The configuration options have been saved.
The website has encountered an error. Please try again later.

Ah, more branch blockers. Yay.

Looks like another branch blocker.

Like this: https://twitter.com/socketwench/status/485812535455526913

randomName() got renamed to randomMachineName()...

Now that the branch blocker is out of the way... :-)

This is great and I appreciate the effort!

A few things:

1. +++ b/content_entity_example/content_entity_example.module
   @@ -0,0 +1,62 @@
   \ No newline at end of file
   

   Ewps.

2. +++ b/content_entity_example/src/ContactAccessController.php
   @@ -0,0 +1,52 @@
   +/**
   + * Access controller for the comment entity.
   + *
   + * @see \Drupal\comment\Entity\Comment.
   + */
   

   I'm sure there's more to say about how an access controller works.

3. +++ b/content_entity_example/src/ContactInterface.php
   @@ -0,0 +1,18 @@
   +use Drupal\user\EntityOwnerInterface;
   +/**
   + * Provides an interface defining a Contact entity.
   + * @ingroup content_entity_example
   + */
   +interface ContactInterface extends ContentEntityInterface, EntityOwnerInterface {
   

   Formatting error, and also tell me why you create an interface and what it gets used for.

4. +++ b/content_entity_example/src/Entity/Contact.php
   @@ -0,0 +1,216 @@
   +use Drupal\user\UserInterface;
   +/**
   

   Formatting.

5. +++ b/content_entity_example/src/Entity/Contact.php
   @@ -0,0 +1,216 @@
   +/**
   + * Defines the ContentEntityExample entity.
   + *
   + * @ingroup content_entity_example
   + *
   + * @ContentEntityType(
   + *   id = "content_entity_example_contact",
   

   Walk us through the annotations and why you set them the way you did.

6. +++ b/content_entity_example/src/Entity/Contact.php
   @@ -0,0 +1,216 @@
   + *   label = @Translation("ContentEntityExample entity"),
   

   Wouldn't that be 'Contact'?

7. +++ b/content_entity_example/src/Entity/Contact.php
   @@ -0,0 +1,216 @@
   +  /**
   +   * {@inheritdoc}
   +   */
   +  public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
   

   We really need some explanation of how this fielding system works, and why we need it even though we have all the annotations.

8. +++ b/content_entity_example/src/Form/ContactSettingsForm.php
   @@ -0,0 +1,55 @@
   +    // Empty implementation of the abstract submit class.
   

   "..abstract submitForm() method."

9. +++ b/content_entity_example/src/Tests/ContentEntityExampleTest.php
   @@ -0,0 +1,114 @@
   +/**
   + * Class ContentEntityExampleTest.
   + * @package Drupal\content_entity_example\Tests
   + *
   + * @ingroup content_entity_example
   + */
   

   Also @group content_entity_example and @group examples

5. It is not possible to add inline comments on annotations. What I'd suggest is a short summary of the interesting parts and then add a reference to \Drupal\Core\Entity\EntityType, where the properties are documented. One important part there is the admin-form thing.

That's basically what I meant: A piece in the docblock explaining some of the options and the decision process.

I just fixed the same problem in the branch last night: https://www.drupal.org/node/2200867 "Entity "controllers" are renamed"

Getting close... :-)

1. +++ b/content_entity_example/src/ContactAccessController.php
   @@ -0,0 +1,56 @@
   +use Drupal\Core\Entity\EntityAccessController;
   

   This API changed: https://www.drupal.org/node/2200867

2. +++ b/content_entity_example/src/Entity/Contact.php
   @@ -0,0 +1,311 @@
   + * Defines the ContentEntityExample entity.
   + *
   + * @ingroup content_entity_example
   + *
   + * This is the main definition of the entity type. From it, an entityType is
   + * derived. The most important properties in this example are:
   + *
   + * - id:          The unique identifier of this entityType. It follows the
   + *                pattern 'moduleName_xyz' to avoid naming conflicts.
   + *
   + * - label:       Human readable name of the entity type.
   + *
   + * - controllers: Controller classes are used for different tasks. You can use
   + *                standard controllers provided by D8 or build your own
   + *                controller, most probably derived from the standard class.
   + *
   + *                view_builder: we use the standard controller to view an
   + *                              instance. It is called when a route lists an
   + *                              '_entity_view' default for the entityType
   + *                              (see routing.yml for details. The view can be
   + *                              manipulated by using the standard drupal tools
   + *                              in the settings.
   

   Thanks for the huge improvement in the docs.

   Just to let you know, though: We can do nested lists in doxy. Otherwise this will get parsed into a bunch of paragraphs. https://www.drupal.org/coding-standards/docs#lists

Moved hook_help() content to the list builder.

Added some tests for the paths.

I'm not really sure how we're supposed to be using @package, so I left that in.

Fixed a few formatting errors.

And with that... We're done!

Thanks, everyone, but especially cgalli for sticking with it. :-)

It seems that Views integration should be added here since all core content entities do.

views integration was postponed on the EntityViewsData handler to land, which is being worked on now: #1740492: Implement a default entity views data handler

And we should do that in a new issue I think.

There was a change in entity annotation: Entity controller admin-form annotation replaced by field_ui_base_route
Should we post required changes into the current issue or open new issues when core api changes happen (like this one)?

New issues, please.

Thanks.