As we decided last week, I've put together some basic documentation to be used for introducing people to this new API in Drupal 8.

The documentation lives here: http://drupal.org/node/1794140

It's currently bundled together all in one page, for sake of review. I'll split up the documentation on child-pages as it makes sense later.

While writing the documentation and trying to explain things in words you get a very good overview that one sometimes misses while coding. So I ran into some parts that could use some more renaming (like if we haven't done that before ;)).

Here are the things I think we should rename/adjust (the documentation already assumes that these will be renamed, because it makes the documentation a lot clearer already):

Please discuss the renaming in the respective issue. Let's keep $this issue about the actual documentation.

Comments

fago’s picture

I've taken a look and added in some small corrections and improvements, please see http://drupal.org/node/1794140/revisions/view/2367666/2368024

With this new API, both properties and fields are be based on the same API, hence it was decided to call everything properties on an API level. However, the notion of a field still exist as definition of end-user created properties (and also not to change terminology for end-users).

This paragraph is not clear to me as I don't know which new API is talked about. Generally, what about splitting the docs out into typed data API docs and entity property API docs. I don't think it makes sense t o force people to understand the in and outs of the typed data API to be able to work with entities. Having a simple page describing the data model of entities (entity, item lists, items, values) and noting that is built upon the typed data API should suffice. Then, we could link to the typed data API page which explains the relationhip in detail. What do you think?

Understanding the problem

From a documentation reader I don't think understanding the problem is really wanted, but understanding *why* we need this API probably is. So maybe we could rephrase this a bit to something like "Why do we need a typed data API?"

dixon_’s picture

Status: Needs review » Needs work

This paragraph is not clear to me as I don't know which new API is talked about. Generally, what about splitting the docs out into typed data API docs and entity property API docs. I don't think it makes sense t o force people to understand the in and outs of the typed data API to be able to work with entities.

Yes, that makes sense. I will split it up before the meeting we have tonight.

From a documentation reader I don't think understanding the problem is really wanted, but understanding *why* we need this API probably is. So maybe we could rephrase this a bit to something like "Why do we need a typed data API?"

Yes, I will rephrase that section to focus more on the why. Makes a lot of sense.

dixon_’s picture

Title: Review documentation of Typed Data API » Documentation of Typed Data API
dixon_’s picture

I've updated the documentation with some of the feedback. Mainly what remains is to separate it better into separate pages, to not mix Typed Data API and Entity API too much. I'll take a stab at that later today.

fago’s picture

thanks, looks good.

one thing you've got wrong in the docs (at least if related to the current code) is that $node->user_id->value is not a typed data object but already the plain value, i.e. the php int. That is as on the item level I've done the magic so that it directly returns/sets the value of the typed data object.

Generally, I think this is nice as usually we want to access the plain values on this level. Thus if you want to to get the typed data object for it you have to use get():

$entity->image[0]->alt instanceof String; is wrong, but
$entity->image[0]->get('alt') instanceof String; would work.

For entity references it is the same, the entity object is considered the plain value of the entity typed data object, which wraps the entity. Hence it's class name EntityWrapper. So

$entity->image[0]->entity would be the entity object while
$entity->image[0]->get('entity') would be the entity wrapper - which implements the complexdatainterface as well and delegates calls to the entity.

fago’s picture

I've also updatd the summary of #1696640: Implement API to unify entity properties and fields. Maybe we can reuse parts of the summary for the docs also? E.g. the initial overview to the typed data API. Then, I think the table of primitives should be included in the typed data API docs as well.

effulgentsia’s picture

$entity->image[0]->alt instanceof String; is wrong

Similarly, $string = $entity->image->alt->value; is also wrong. Should be $string = $entity->image->alt;

effulgentsia’s picture

Issue summary: View changes

Syntax error.