Problem

Current Media documentation is mostly for 1.x with the Media entity and Styles module. New users don't have good documentation for the current 2.x with File entity and Manage File Display workflow, and the legacy docs confuse them.

Solution

  1. Create new Media 2.x documentation.
  2. Revise old 1.x documentation that is still valid.
  3. Remove old 1.x documentation that is no longer valid (e.g., with backport of file entity to 1.x, Styles module integration is no longer recommended).
  4. Push Goal: create video tutorials to link to in documentation.

We have some good content to start with:

Walkthrough by pandaeskimo: http://drupal.org/node/1699054. Great stuff, a real-world example.
Media 2.x configuration overview by RobW: http://drupal.stackexchange.com/questions/40229/how-to-set-media-styles-.... Needs pictures.

Original Issue by pandaeskimo

http://drupal.org/node/1699054

I have tried to wrap my head around Media 2.0 and have created a tutorial as part of the Media documentation. There are tons of images outlining how to set things up. I'd appreciate any feedback or help building this out.

I will probably be cleaning up our own handling of media files and if I'm going about it the wrong way, feedback would be helpful.

We all know Drupal documentation is often week and the concepts behind using certain modules can be very awkward. Hopefully the workflow and descriptions in the tutorial can help people.

Thank you.

Comments

dddave’s picture

dddave CreditAttribution: dddave commented

Wow, awesome effort. I am going to try to dive into your work in the next days. Like the extra effort to get those pics.

Jean Gionet’s picture

Jean Gionet CreditAttribution: Jean Gionet commented

This is great for sure!

It would be nice to see added information about the "extra" configs you performed on your setup.
Like how "Entity View Mode" works and how and why you added the "Additional View Mode". The same on how to add your "Rights" option.

Having images attached and marked makes it very user friendly to follow.

Thanks for this!

damontgomery’s picture

damontgomery CreditAttribution: damontgomery commented

Thanks for the comments. Entity View Mode is pretty easy to configure and the extra fields are configured exactly as they are content types.

File Entity was recently updated to allow for replacement of files. Essentially, if you upload image.jpg again, it overwrites image.jpg instead of creating image_0.jpg. This means that (as I can tell) it is viable to use file entities instead of content type wrappers for all types of files like documents / images / videos.

I may create a supplemental tutorial on how to add fields to the file entity types and how management works through views.

RobW’s picture

RobW CreditAttribution: RobW commented

Great tutorial. The docs for Media are so spread out, outdated, and contradictory right now -- some culling of old pages and the addition of new docs and tutorials is really needed.

I wrote this last night: http://drupal.stackexchange.com/questions/40229/how-to-set-media-styles-.... Wish I had seen yours first, could have saved some time.

I'd like to see a combination of our documentation replace the current outdated Styles documentation, which should probably be removed completely. I think yours is a great step by step tutorial (my only suggestion would be to edit out the personal judgements, or make them universal recommendations), and mine is a more basic overview -- maybe we could refine both and present one after the other.

alanom’s picture

alanom CreditAttribution: alanom commented

As a keen consumer of Media documentation, it's very good. 90% covers different ground to RobW's drupal answers answer (it's actually one of the things listed in "related reading" in the background research in that question). They're definitely not duplicated effort and shouldn't be merged completely: it's normal, and very useful, for documentation to have a small number of different pages explaining the basics. In this case I see the ideal result as being something like:

  • A couple of reference pages, like RobW's DA answer, that state plainly what the concept is, what the moving parts are, what the tools are and what they do, and what gotchas need to be looked out for (such as deprecated elements). These ideally should be topic-specific: one on media styles can be almost exactly what RobW has written, following one on the core concept explaining the latest version of the whole file/stream management thing and introducing the media browser (this could incoporate content from pandaeskimo's "How Does Media Work?" and existing docs explaining phpstreamwrappers). A third (probably final?) page could go into detail on media fields and how these work in displays (maybe including views, panels/display suite, etc)
  • A tutorial or two that cover a range of topics in less depth but in a different more visual/practical way, like pandaeskimo's. These provide something different and work for a different audience looking for different information, although overlap is ineveitble and healthy. The "Fields and views" tutorial sounds like a very good addition
  • That might be enough, although it could be useful to also have as a final page an overview of related/extending modules, integration with other key parts of the Drupal ecosystem (views, panels/display suite, responsive themes, etc) and/or very brief examples of common uses of the Media family, again providing something different for a different audience

pandaeskimo - one piece of constructive feedback on the tutorial - it's very good, maybe it would showcase the power of the file display system better if it used a media type (e.g. Youtube videos) with multiple types of file (not just image), so people can see how things like thumbnails are styled alongside things like video players for the same media type? Also, you could get a tutorial will a lot of wow factor if, as a finale demonstrating an example of where to go from here, you showed integration with something like a popular content display overlay module like lightbox/colorbox, showing how easily it can be set up that image thumbnails of a set configurable style pop up an overlay with a video player, also of a set configurable style.

damontgomery’s picture

damontgomery CreditAttribution: damontgomery commented

Thanks for the feedback. I may be able to put together the youtube video guide similar to what I did here. I wanted to make a basic one that used as few modules as possible so it was as general as possible.

We personally do exactly what you've stated with YouTube videos and Fancybox lightboxes. This current implementation is on our dev servers which should be live at some point and I may even link to it.

The thing with Fancybox is that I've had to recently add code to the template.php file and edit the actual Fancybox code to load jQuery 1.7 alongside 1.4 (another nightmare :(). That's not a "plug and play" thing to put in a tutorial. (BTW, I hate ctools modal).

I've also done some work with making views for files and even incorporating views bulk operations, so that could be another tutorial.

For all of the "what is the best way to do it" questions, the answer is that I don't know. I stumbled around and tried to make sense of it all and came up with what seemed like the least convoluted strategy for us and it seems to work. file_entity and other modules have been developing a lot lately to support this new approach (for example allowing in place replacement of files keeping the same file path). If anyone knows any "official" answers, it would be great to edit these docs or point out the correct answers.

I also got a kick out of the SE answer since I don't have an account there but the questions were all tied together! :) We'll figure it out guys.

RobW’s picture

RobW CreditAttribution: RobW commented
Title: Please Help Review my Tutorial for Media 2.0 » Revise documentation for Media 2.0; remove deprecated information, include overview and walkthrough examples
RobW’s picture

RobW CreditAttribution: RobW commented
Issue summary: View changes

Revised to current stat.

RobW’s picture

RobW CreditAttribution: RobW commented
Status: Needs review » Needs work
Devin Carlson’s picture

Devin Carlson CreditAttribution: Devin Carlson commented
Status: Needs work » Fixed

I opened #1792802: Delete Media module's Styles page to remove the old Styles page and moved + renamed pandaeskimo's tutorial to function as a "quick start guide" for those who want an easy way to get into Media.

RobW’s picture

RobW CreditAttribution: RobW commented
Status: Fixed » Needs work

The Media documentation still needs a lot of work.

Made the following edits

Added:
Displaying Media page from the SE post.

Revised:
Media Usage renamed to Media Library
Marked Media: FAQ as outdated
Re-ordered the book pages

Archived duplicate content:
Media Configuration archived to ARCHIVE: Media Configuration

To do

There is more old, currently unhelpful information than new, helpful information.
The FAQ page is a mess. Should we archive it or does someone want to revise it?
The recipe page/ section may be outdated, and is probably available in other more appropriate areas. Ideas?
The developer documentation is outdated.

I think no information, or a note to check the respective code docs is better than old, no longer helpful info. Other opinions?

RobW’s picture

RobW CreditAttribution: RobW commented
Issue summary: View changes

Minor addition.

joseph.olstad’s picture

joseph.olstad
Primary language French
CreditAttribution: joseph.olstad commented
Status: Needs work » Fixed

this was done several years ago

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.