Add embedded support

[alanpoulain]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	yes (slightly and only if embeddeds are used)
Deprecations?	no
Tickets	fixes #279
License	MIT
Doc PR	api-platform/docs#1112

Alternative of #107.

Since @api-platform/api-doc-parser can now tell if a field is an embedded one, the admin can be slightly smarter and not using a reference for it.

If it's an array of embeddeds, the previous behavior stays the same: objects are replaced by their IRI and references are used in FieldGuesser and InputGuesser.

However, if it's an embedded field, the behavior changes depending of the value of useEmbedded in the Hydra data provider:

• if false, the IRI of the embedded will be displayed as a text (BC: it was a reference before, you can get back this behaviour by replacing the guessers by references) in FieldGuesser and InputGuesser.
• if true, the embedded object will be displayed as a text in FieldGuesser and InputGuesser.

The useEmbedded is false by default to not cause too much breaking changes, but it will not exist anymore in 3.0 (and the behavior will be like it was always true).

It means that, if you enable useEmbedded in the Hydra data provider, you can now use the dot notation of React Admin for complex structures!

However, the admin cannot determine the structure of the embedded and the fields in it. It's because the Hydra documentation doesn't give this information. In order to display them, you need to use directly the React Admin components.

[darkweak]

Suggested change

	document[key] = useEmbedded ? document[key] : document[key]['@id'];
	document[key.toString()] = useEmbedded ? document[key.toString()] : document[key.toString()]['@id'];

To avoid Object Injection Sink IMO

[alanpoulain]

It cannot be done like this because React Admin data providers need to give record objects: https://marmelab.com/react-admin/DataProviders.html#response-format

[darkweak]

It doesn't affect return, your key var should be a string right ?

[alanpoulain]

Oh yes, you're right sorry. But Object.keys returns only strings so I don't think it's necessary.

[loeyan]

Hey guys,

thanks for your work! Unfortunately, those changes doesn't seem to work for me (or I am doing something totally wrong). I am using "useEmbedded=true" and my embedded objects are not resolved :(

I also followed your docu in
https://api-platform.com/docs/admin/handling-relations/#display-a-field-of-an-embedded-relation

Further details you can finde here:
https://stackoverflow.com/questions/61704585/access-property-of-a-nested-record

I just debugged it in the browser a bit.... shouldn't the "useEmbedded" parameter be passed inside the recursive function calls of transformJsonLdDocumentToReactAdminDocument()?

i can see

• reactAdminDocumentsCache[document[key]['@id']] = transformJsonLdDocumentToReactAdminDocument(document[key], false, false);
• reactAdminDocumentsCache[obj['@id']] = transformJsonLdDocumentToReactAdminDocument(obj, false, false);

=> nested seem to be quite limited here!

[alanpoulain]

@loeyan the embedded support was not done for the array of embeddeds yet. The PR to add it is here: #302.