Add documentation to describe Media + File Styles + Views + Presets = Lost in Media universe.

This has been quite confusing for me as well but I've looked at some of the code and maybe I can help with explaining. I'll explain it with term definitions from bottom to top, this is mainly regarding Styles as the documentation you linked covered Media very well.

• Field types - everyone knows field types. For example the File style modules field type is file and the Media entity contains a file field. Here modules can define themselves and hook in their containers, styles and presets. For example node reference can provide their styles for the nodereference field type.
• Container is the term used for Image, Audio and Video. These I won't go in to but I assume they can be extended with i.e. Youtube, Flickr etc.
• The styles listed on the File Styles page are currently given by modules, actually they are styles in Styles module given by File Styles. These you can add yourself through the UI or have modules hook into with styles_default_styles. Once you add a File Style they will be available to select in the view modes of Media Types. Once you select a style in the view mode it will use the preset that was assigned on the File Styles page.
• Presets are also added by module hooks styles_default_presets (File styles provide them currently). Currently there is no UI for adding or editing these but judging by the code it's on it's way.
• Effects is not really implemented yet but judging by the code this is where the image styles will be added together with other effects such as colorbox links into the preset. (This is based on some code currently not in use)
• Rest of the stuff is well explained in the Media documentation

So all the stuff listed in the dropdown at Media Types > Image media type settings > Manage Display > View mode are all the styles provided within the field type file. Therefore some of them are defined by File Styles and some by Media.

Hopefully this can help someone.

Updated with effects, and this makes the entire structure a lot clearer

Yes, you are absolutely right. This is the worst part of Media. Several people agree here. It's a tough problem to solve.

I'm in a rush right now, hopefully Aaron Winborn (styles author) can help elucidate more, but basically:

Media entities have a file field.
The file field has a formatter, by default that formatter is defined by the file_styles module.
The file_styles module routes that request to format it to different formatters depending on the type of file.
This allows you to use the same formatter for a youtube video and an mp4 on your server. They have totally different formatters, but they are both "video" type media entities.
Styles UI provides a UI for seeing what routing will happen.

Does that help at all? If so, *PLEASE* write some docs for this so until we fix the UX at least it can be explained.

@oxyc actually did a great job, I didn't see that comment before replying.

@oxyc: Can you add a doc page to the media docs and paste in what you've got there? Would be a huge help.

This Sage does not expect perfection. If he did, he'd be on his own case so much nothing would get done. Something is totally better than nothing. Even if it is just leaving what you know in an issue or a blog post and referencing it from the docs with:

Here's something I figured out, it may be wrong, but it works!: [link].

All the way up to full fledged docs with screenshots and video, etc... It's all good.

I just added it in the docs.

Should I remove the hook? I dont know how bad of practice it is to include such an ugly fix. Myself I wanted to be able to use my own image styles right away and I'm guessing many are in the same position.

If not I'll be sure to remove it as soon as a cleaner solutions becomes available.

Oh and no problem kannary, glad I could help.

@oxyc: Thanks a lot for writing up this page! Concerning the hook, perhaps we should move it to a separate page? That way, the docs page can be a clear Styles docs page, and the code snippet can live elsewhere?

It might also be useful to start a code snippet page in the (currently outdated) media dev docs for pieces of code like this. What do you think?

http://drupal.org/node/1091686
I'm also confused and had to spend about a day trying to diagram the entire process out.

I think visually better than text based, so I put together a few diagrams. They may not be 100% accurate, so your mileage may vary. If people find this helpful, I can do another round on them and upload the omni-graffle files so people can further edit (pdf/svg output also available).

Cheers, -Rick

AWESOME!

An effort is underway to re-define this architecture and make it easier to get w/o a diagram like this. However, that doesn't mean these don't belong in the docs.

Added them to the page oxy started: http://drupal.org/node/1092444. Please make changes if required. Also, if you can't make changes contact me - I used the documentation imput format which may not allow users without the documentation role from editing :( I did this so I could add the images inline.

I'm going to mark this as fixed and link to the doc page in the header.

Hey Jacob,
I'm glad you liked them :) As I stated, if people need to review/modify, I can provide the source files to extend/change further.

I know documentation by itself should be sufficient, but with so many levels of abstraction, I needed a visual!