Creating entities programmatically

Using the Entity API module makes this fairly straightforward. Let's say there's an entity type called "Contact" [contact] and a bundle called 'contact_simple'.

Creating new entities is as easy as:

  $entity_type = 'contact';
  $entity = entity_create($entity_type, array('type' => 'contact_simple'));
  $wrapper = entity_metadata_wrapper($entity_type, $entity);

Once the entity is created the properties can be changed:

Naming conventions

When it comes to entity labels, there are no worries. However, take special care when choosing your ECK entity's 'machine name'. ECK will check to make sure no other entities with the same 'machine name' conflict before allowing you to create it; however, there are aspects that cannot be checked for.

There have been several reported cases of other conflicts happening. See #1345264: Protect against reserved entity type names. In this example an entity of type category was defined using ECK; however, the user module has a function called user_category_load(). So, when the entity API tries to call the load hook for the category entity, it checks for all modules essentially calling a hook_category_load which conflicts with the user modules completely separate use of that function name.

Another example is if I were to define an entity called user_profile, it would seem a valid entity name and, thus, would get created. However, again the user module has a template file user-profile.tpl.php that requires certain variables and gets triggered on the path /user-profile. The same path is used by default for the user_profile entity I created using ECK. This again results in a conflict and it all breaks down.

Creating a property behavior

Creating a property behavior is done by implementing the plugin architecture from the CTools module. For any developer to add new "property behavior", all they have to do are two things:

  1. Let the plugin system know that you want to provide some property behaviors.
  2. Create one file per behavior you want to provide.

Ok, so let's go into a little more detail on what each of these steps entail. We will use the code already in ECK to demonstrate how everything works.

Inform the plugin system

To let the plugin system know that you are providing a plugin, all you have to do is implement the hook: hook_ctools_plugin_directory().

Here is what that implementation looks like in ECK:

function eck_ctools_plugin_directory($owner, $plugin_type) {
  if ($owner == 'eck' && $plugin_type == 'property_behavior') {
    return 'plugins/' . $plugin_type;

ECK for Site Builders

ECK wants to make creating entities and using the entity system as easy as possible. For this, it exposes many tasks like creating and managing entity types, bundles and entities through the UI. Because ECK is a new project, there are a few things that might not be very intuitive when dealing with the UI. We obviously want to correct these things but, until then, we will try to expose everything in as clear a way as possible through this documentation.

Subscribe with RSS Subscribe to RSS - ECK