API.txt

  1. cis7 sites/all/modules/ulmus/context/API.txt
  2. cis7 sites/all/modules/ulmus/ctools/API.txt
  3. cis7 sites/all/modules/ulmus/pathauto/API.txt
  4. cis7 sites/all/modules/ulmus/media/API.txt
  5. cis7 sites/all/modules/ulmus/features/API.txt
  6. cis7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  7. cis7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  8. cis7 sites/all/modules/ulmus/security_review/API.txt
  9. cis7 sites/all/modules/ulmus/aes/API.txt
  10. cle7 sites/all/modules/ulmus/pathauto/API.txt
  11. cle7 sites/all/modules/ulmus/context/API.txt
  12. cle7 sites/all/modules/ulmus/aes/API.txt
  13. cle7 sites/all/modules/ulmus/media/API.txt
  14. cle7 sites/all/modules/ulmus/security_review/API.txt
  15. cle7 sites/all/modules/ulmus/ctools/API.txt
  16. cle7 sites/all/modules/ulmus/features/API.txt
  17. cle7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  18. cle7 sites/all/modules/local_contrib/votingapi/API.txt
  19. cle7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  20. ecd7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  21. ecd7 sites/all/modules/ulmus/pathauto/API.txt
  22. ecd7 sites/all/modules/ulmus/aes/API.txt
  23. ecd7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  24. ecd7 sites/all/modules/ulmus/context/API.txt
  25. ecd7 sites/all/modules/ulmus/features/API.txt
  26. ecd7 sites/all/modules/ulmus/security_review/API.txt
  27. ecd7 sites/all/modules/ulmus/ctools/API.txt
  28. ecd7 sites/all/modules/ulmus/media/API.txt
  29. elmsmedia7 sites/all/modules/ulmus/aes/API.txt
  30. elmsmedia7 sites/all/modules/ulmus/security_review/API.txt
  31. elmsmedia7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  32. elmsmedia7 sites/all/modules/ulmus/ctools/API.txt
  33. elmsmedia7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  34. elmsmedia7 sites/all/modules/ulmus/pathauto/API.txt
  35. elmsmedia7 sites/all/modules/ulmus/context/API.txt
  36. elmsmedia7 sites/all/modules/ulmus/media/API.txt
  37. elmsmedia7 sites/all/modules/ulmus/features/API.txt
  38. harmony7 sites/all/modules/ulmus/aes/API.txt
  39. harmony7 sites/all/modules/ulmus/context/API.txt
  40. harmony7 sites/all/modules/ulmus/ctools/API.txt
  41. harmony7 sites/all/modules/ulmus/security_review/API.txt
  42. harmony7 sites/all/modules/ulmus/features/API.txt
  43. harmony7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  44. harmony7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  45. harmony7 sites/all/modules/ulmus/media/API.txt
  46. harmony7 sites/all/modules/ulmus/pathauto/API.txt
  47. icor7 sites/all/modules/ulmus/context/API.txt
  48. icor7 sites/all/modules/ulmus/media/API.txt
  49. icor7 sites/all/modules/ulmus/pathauto/API.txt
  50. icor7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  51. icor7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  52. icor7 sites/all/modules/ulmus/features/API.txt
  53. icor7 sites/all/modules/ulmus/ctools/API.txt
  54. icor7 sites/all/modules/ulmus/security_review/API.txt
  55. icor7 sites/all/modules/ulmus/aes/API.txt
  56. meedjum_blog7 sites/all/modules/ulmus/context/API.txt
  57. meedjum_blog7 sites/all/modules/ulmus/ctools/API.txt
  58. meedjum_blog7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  59. meedjum_blog7 sites/all/modules/ulmus/pathauto/API.txt
  60. meedjum_blog7 sites/all/modules/ulmus/features/API.txt
  61. meedjum_blog7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  62. meedjum_blog7 sites/all/modules/ulmus/aes/API.txt
  63. meedjum_blog7 sites/all/modules/ulmus/security_review/API.txt
  64. meedjum_blog7 sites/all/modules/ulmus/media/API.txt
  65. mooc7 sites/all/modules/elmsln_contrib/nodereference_highlight/API.txt
  66. mooc7 sites/all/modules/ulmus/context/API.txt
  67. mooc7 sites/all/modules/ulmus/ctools/API.txt
  68. mooc7 sites/all/modules/elmsln_contrib/outline_designer/API.txt
  69. mooc7 sites/all/modules/ulmus/pathauto/API.txt
  70. mooc7 sites/all/modules/ulmus/media/API.txt
  71. mooc7 sites/all/modules/ulmus/security_review/API.txt
  72. mooc7 sites/all/modules/ulmus/features/API.txt
  73. mooc7 sites/all/modules/ulmus/aes/API.txt
/**
 *  API documentation for the Media module.
 */

The Media module provides a robust API for developers to extend functionality
in useful and novel ways.

CAUTION: This is pretty old!

Architecture
------------

To understand the API, it is first important to understand the underlying
architecture and the decisions behind its current implementation.

Stream Wrappers
---------------

First, the Media module makes heavy use of the core Stream Wrappers now
provided with Drupal 7. Streams are classes that encapsulate PHP file
functions, allowing an automatic override when calling the basic function.
For instance, a wrapper implementing an Amazon S3 Stream might override the
file_get_contents() using ->stream_open(), or a Flickr Stream Wrapper might
implement its own ->getExternalUrl to return the HTML URI for a specific
Flickr image.

See http://api.drupal.org/file/includes/stream_wrappers.inc/7 for more
information about Stream Wrappers in Drupal.

Schemes
-------

All Stream Wrappers will be registered to handle a specific scheme, which is
the part of a URI before ://, such as core Drupal's public:// and private://
schemes. (Technically, a scheme only requires :, but a bug in PHP 5.2
requires ://, so Drupal currently keeps the same requirement.)

The target after the scheme:// will be a unique identifier that the
implementing Stream Wrapper will use to determine the file resource being
accessed. For instance, public://my-document.txt might refer to a local file
stored in the server at /sites/example.com/files/my-document.txt, while a URI
of youtube://fe3fg8u34i might be the video stored at
http://youtube.com/v/fe3fg8u34i, and flickr://photoset/224 might use a lookup
table to determine this is a photoset accessed at
http://flickr.com/user/markam/photoset/325hsd89.

All files in Drupal are stored in the database with this unique URI, in
addition to its unique serial FID. In general, file objects are accessed
and loaded by the URI, which will automatically use the correct stream wrapper
implementation for its scheme.

File Field Widget
-----------------

The Media module extends the core File field to make use of its browser for
editors, which is in turn exposed for other modules to extend. It does this
by create a new widget definition, defining a File (media) 'generic' file
widget, and suppressing the original File widget definition to avoid
confusion. All existing file fields will be converted to this new widget on
installation of the module, and if uninstalled, any defined media_generic file
fields will be reverted to their original definition to avoid loss of data.

Media Formatters
----------------

By default, the File (media) widget will use the original display behavior,
which is to display a generic icon followed by a link to the file. However, in
many (if not most) cases, a site administrator will want to display media in
very specific ways. For instance, they might want an image uploaded to be
displayed as a cropped thumbnail, as with any Flickr images attached to that
field, while a YouTube video might be displayed as a thumbnail that pops up
in a Shadowbox, and finally a PDF might be displayed in an iFrame. And that's
only when it's displayed in a node teaser...

To manage the various display formatting needs of an editor, the Media module
offers a Media Style API for other modules to implement and extend. Media
Styles of various mimetypes are grouped together and made available as new
formatters for field display, whether for a node, a comment, in a view, or
elsewhere.

To implement a new Media Style, a module needs to register itself for a
specific mimetype, with the following hook. Note that Media styles will be
properly namespaced by the module, to avoid conflicts.

function hook_media_styles($mimetype = NULL) {
  switch ($mimetype) {
    case 'video/x-youtube':
      return array(
        'youtube_video' => t('YouTube Video'),
        'youtube_thumbnail' => t('YouTube Thumbnail'),
        'youtube_shadowbox' => t('YouTube Shadowbox'),
        'youtube_link' => t('Youtube (link to original)'),
    case 'image/x-flickr':
      $styles = array(
        'flickr__original' => t('Flickr (Original size)'),
      );
      foreach (image_styles() as $style_name => $style) {
        $styles[$style_name] = t('Flickr (@style)', array('@style' => $style->name));
      }
      return $styles;
  }
}

These styles will be available from the Media Styles configuration page, where
multiple formatters can be grouped together to create new formatter Style
bundles, available and intelligently applied to files of the appropriate
mimetypes.

For instance, a new Media Style might be created, named 'Small image', which
will bundle an Image style for the various image mimetypes, another for Flickr
images, a shadowbox for YouTube thumbnails, and a fallback to a size styled
File icon. Then this style would be made available as a display formatter, and
the Media module will apply the correct style for the mimetype of the
particular instance.

A module may also define default Media styles to be made available, by
implementing hook_media_default_style_bundles(). Unlike the individual Media Styles,
Media Style bundles are not namespaced by module. If two or more modules use
the same Style bundle names, the behavior is undefined. Also note that the
administrator may override a specific Style bundle, for instance by replacing
the Style for a specific mimetype.

function hook_media_default_style_bundles() {
  return array(
    'shadowbox_images' => array(
      'label' => t('Shadowbox images'),
      'mimetypes' => array(
        'image/*' => 'mymodule_image_shadowbox',
        'video/*' => 'mymodule_video_shadowbox',
        '*' => 'mymodule_default_shadowbox',
      ),
    ),
  );
}

@TODO
convert existing file fields to media_generic on hook_install
convert existing media_generic to file fields on hook_uninstall
allow theme_file_icon file directory override in widget display settings
  (Requires http://drupal.org/node/650732)
create new default file icons and set its folder as the new default
maybe instead/in addition have fallbacks if icon not present?
rename image style square_thumbnail to use the media_ namespace
review Media Styles for feasibility, usability, and architecture
create Media Styles UI .inc file
look at hook_field_info_alter to see if we can affect file widget that way
CLEAN CRUFT (lots of functions that no longer apply or need to be rethought)
why do we want to override the file field widget again?
should we also move 'media_styles' to its own module, perhaps file_styles?
in media_field_formatter_info(),
  should 'field types' => array('media_generic', 'file'), be only one or other?

File

sites/all/modules/ulmus/media/API.txt
View source
  1. /**
  2. * API documentation for the Media module.
  3. */
  4. The Media module provides a robust API for developers to extend functionality
  5. in useful and novel ways.
  6. CAUTION: This is pretty old!
  7. Architecture
  8. ------------
  9. To understand the API, it is first important to understand the underlying
  10. architecture and the decisions behind its current implementation.
  11. Stream Wrappers
  12. ---------------
  13. First, the Media module makes heavy use of the core Stream Wrappers now
  14. provided with Drupal 7. Streams are classes that encapsulate PHP file
  15. functions, allowing an automatic override when calling the basic function.
  16. For instance, a wrapper implementing an Amazon S3 Stream might override the
  17. file_get_contents() using ->stream_open(), or a Flickr Stream Wrapper might
  18. implement its own ->getExternalUrl to return the HTML URI for a specific
  19. Flickr image.
  20. See http://api.drupal.org/file/includes/stream_wrappers.inc/7 for more
  21. information about Stream Wrappers in Drupal.
  22. Schemes
  23. -------
  24. All Stream Wrappers will be registered to handle a specific scheme, which is
  25. the part of a URI before ://, such as core Drupal's public:// and private://
  26. schemes. (Technically, a scheme only requires :, but a bug in PHP 5.2
  27. requires ://, so Drupal currently keeps the same requirement.)
  28. The target after the scheme:// will be a unique identifier that the
  29. implementing Stream Wrapper will use to determine the file resource being
  30. accessed. For instance, public://my-document.txt might refer to a local file
  31. stored in the server at /sites/example.com/files/my-document.txt, while a URI
  32. of youtube://fe3fg8u34i might be the video stored at
  33. http://youtube.com/v/fe3fg8u34i, and flickr://photoset/224 might use a lookup
  34. table to determine this is a photoset accessed at
  35. http://flickr.com/user/markam/photoset/325hsd89.
  36. All files in Drupal are stored in the database with this unique URI, in
  37. addition to its unique serial FID. In general, file objects are accessed
  38. and loaded by the URI, which will automatically use the correct stream wrapper
  39. implementation for its scheme.
  40. File Field Widget
  41. -----------------
  42. The Media module extends the core File field to make use of its browser for
  43. editors, which is in turn exposed for other modules to extend. It does this
  44. by create a new widget definition, defining a File (media) 'generic' file
  45. widget, and suppressing the original File widget definition to avoid
  46. confusion. All existing file fields will be converted to this new widget on
  47. installation of the module, and if uninstalled, any defined media_generic file
  48. fields will be reverted to their original definition to avoid loss of data.
  49. Media Formatters
  50. ----------------
  51. By default, the File (media) widget will use the original display behavior,
  52. which is to display a generic icon followed by a link to the file. However, in
  53. many (if not most) cases, a site administrator will want to display media in
  54. very specific ways. For instance, they might want an image uploaded to be
  55. displayed as a cropped thumbnail, as with any Flickr images attached to that
  56. field, while a YouTube video might be displayed as a thumbnail that pops up
  57. in a Shadowbox, and finally a PDF might be displayed in an iFrame. And that's
  58. only when it's displayed in a node teaser...
  59. To manage the various display formatting needs of an editor, the Media module
  60. offers a Media Style API for other modules to implement and extend. Media
  61. Styles of various mimetypes are grouped together and made available as new
  62. formatters for field display, whether for a node, a comment, in a view, or
  63. elsewhere.
  64. To implement a new Media Style, a module needs to register itself for a
  65. specific mimetype, with the following hook. Note that Media styles will be
  66. properly namespaced by the module, to avoid conflicts.
  67. function hook_media_styles($mimetype = NULL) {
  68. switch ($mimetype) {
  69. case 'video/x-youtube':
  70. return array(
  71. 'youtube_video' => t('YouTube Video'),
  72. 'youtube_thumbnail' => t('YouTube Thumbnail'),
  73. 'youtube_shadowbox' => t('YouTube Shadowbox'),
  74. 'youtube_link' => t('Youtube (link to original)'),
  75. case 'image/x-flickr':
  76. $styles = array(
  77. 'flickr__original' => t('Flickr (Original size)'),
  78. );
  79. foreach (image_styles() as $style_name => $style) {
  80. $styles[$style_name] = t('Flickr (@style)', array('@style' => $style->name));
  81. }
  82. return $styles;
  83. }
  84. }
  85. These styles will be available from the Media Styles configuration page, where
  86. multiple formatters can be grouped together to create new formatter Style
  87. bundles, available and intelligently applied to files of the appropriate
  88. mimetypes.
  89. For instance, a new Media Style might be created, named 'Small image', which
  90. will bundle an Image style for the various image mimetypes, another for Flickr
  91. images, a shadowbox for YouTube thumbnails, and a fallback to a size styled
  92. File icon. Then this style would be made available as a display formatter, and
  93. the Media module will apply the correct style for the mimetype of the
  94. particular instance.
  95. A module may also define default Media styles to be made available, by
  96. implementing hook_media_default_style_bundles(). Unlike the individual Media Styles,
  97. Media Style bundles are not namespaced by module. If two or more modules use
  98. the same Style bundle names, the behavior is undefined. Also note that the
  99. administrator may override a specific Style bundle, for instance by replacing
  100. the Style for a specific mimetype.
  101. function hook_media_default_style_bundles() {
  102. return array(
  103. 'shadowbox_images' => array(
  104. 'label' => t('Shadowbox images'),
  105. 'mimetypes' => array(
  106. 'image/*' => 'mymodule_image_shadowbox',
  107. 'video/*' => 'mymodule_video_shadowbox',
  108. '*' => 'mymodule_default_shadowbox',
  109. ),
  110. ),
  111. );
  112. }
  113. @TODO
  114. convert existing file fields to media_generic on hook_install
  115. convert existing media_generic to file fields on hook_uninstall
  116. allow theme_file_icon file directory override in widget display settings
  117. (Requires http://drupal.org/node/650732)
  118. create new default file icons and set its folder as the new default
  119. maybe instead/in addition have fallbacks if icon not present?
  120. rename image style square_thumbnail to use the media_ namespace
  121. review Media Styles for feasibility, usability, and architecture
  122. create Media Styles UI .inc file
  123. look at hook_field_info_alter to see if we can affect file widget that way
  124. CLEAN CRUFT (lots of functions that no longer apply or need to be rethought)
  125. why do we want to override the file field widget again?
  126. should we also move 'media_styles' to its own module, perhaps file_styles?
  127. in media_field_formatter_info(),
  128. should 'field types' => array('media_generic', 'file'), be only one or other?