Added documentation for the CmfResourceBundle #838
Conversation
wouterj
force-pushed
the
resource-bundle-docs
branch
from
5f8a97a to
07fb92e
Compare
| ============================== | ||
|
|
||
| The resources retrieved from the :doc:`resource repositories <repositories>` | ||
| can be enhanced with descriptions: Bits of information about the resource. This |
There was a problem hiding this comment.
For me that kind of naming "description" or "descriptors" was new on API or resources, So i would extend the explenation a little bit.
There was a problem hiding this comment.
I mean there is some more on index, but for a direct visitor this would not be enough.
| { | ||
| $homepageResource = $this->get('cmf_resource.repository.default')->get('/pages/homepage'); | ||
|
|
||
| $descriptionFactory = $this->get('cmf_resource.description.factory'); |
There was a problem hiding this comment.
why sould i retrieve description server side? Should i use them to change application output flow at the end?
There was a problem hiding this comment.
Well, using them on the front-end in the tree is only one use-case (and even in this use-case, the description is retrieved in the back-end by the ResourceRestBundle).
But resource is waaaaay more usefull than just TreeBrowser. E.g. symfony-cmf/routing-bundle#314 , on the long run all other bundles will just use resources. The resource component then provides an ORM repository and all bundles have ORM support \o/.
Another example is rendering, imagine a controller passing only the resource and resource description to a template. The template can then render it's title, body and metadata (e.g. SeoBundle has an enhancer as well) without knowing the backend. This means we can easily swap the PHPCR repository for Puli's FilesystemRepository and have static-CMS like functionality.
There was a problem hiding this comment.
You would render the attributes in your Twig template. There was also a twig helper somewhere... But you may also want to generate a JSON response.
|
|
||
| :doc:`introduction` | ||
| Ships a ``sylius_resource`` enhancer, adding CRUD links for the SyliusResourceBundle_. | ||
|
|
There was a problem hiding this comment.
i also added a position enhancer to servie the position property inside SonataDoctrinePhpcrAdminBundle. I helps to keep sorting alive after d&d.
| ============================== | ||
|
|
||
| The resources retrieved from the :doc:`resource repositories <repositories>` | ||
| can be enhanced with descriptions: Bits of information about the resource. This |
There was a problem hiding this comment.
Bits of information => Standardized bits of information (for example URLs, thumbnails, titles, etc.) which can be consumed by disparate components or applications or similar?
| enhancers*. The :doc:`TreeBrowserBundle <../tree_browser/introduction>` for | ||
| instance ships with an enhancer to add paths to document icons. Read more | ||
| about adding your own description enhancers in :doc:`description_enhancers`. | ||
|
|
There was a problem hiding this comment.
Maybe something on the idea behind this originally, here or in the relevant section
Description enhancers allow you (or a third-party) to provide descriptions, for example, you are developing a component which requires a title and thumbnail image to represent an entity (for example a browser). Your component may be used with either Sylius or Sonata Admin. Both of these applications are capable of providing the required metadata, but they do so in very ways.
Description enhancers enable you to abstract yourself away from these differences.
There was a problem hiding this comment.
thanks a lot for writing this up wouter. can you check the build error (some target not existing) and maybe add the suggestions from dan and max? but lets merge this asap - a useful documentation that is online is better than perfect documentation that is not merged ;-)
Written in one straight, so probably contains lots of mistakes & typos :)