Agree the structure of hook_embed_info()

Use this thread to track the development of the hook_embed_info() callback.

This hook is used by the embed module to determine what embedding handlers (or themes) are capable of. The data is used to construct the settings page, but it is also used during embedding to determine what should be done with multiple objects. For performance reasons this data array is cached in the cache table and is only regenerated when hook_menu() is called (usually when a new module is being enabled).

When called each module returns an array of arrays. The keys in the first array are the names of the handlers/themes. The sub-arrays describe the properties of that theme.

The current structure is

• title: brief human readable title of the handler/theme that is shown on the settings page.
• description: Longer description describing the theme, its benefits/key feature etc - shown on the settings page.
• types: Array of mimetypes to indicate what types of object the handler can process. When the settings page is generated a separate page is created for each registered mimetype. If no handler is reporting for a type then no settings page is presented.
• multiple values: A flag to indicate whether the handler/theme can accept an array of objects (e.g. it can construct an image gallery from an array of images), or whether it will output a separate object for each of the array elements. Directly analagous to CCK, and as such this can be set using the constants OBJECT_HANDLE_CORE and OBJECT_HANDLE_MODULE. If omitted then we assume OBJECT_HANDLE_CORE.
• resource: Name of a shared resource file that is used by the theme. Omitted if there aren't any. At present the proposal is to only check for one file, and use that as representative of the entire resource.
• download: A link to where the user can get any shared resource files that they need. Only allows one link.
• private: Optional flag that if set to TRUE will prevent the theme being shown on the settings page. This would be used, by, say the FlowPlayer 3 embedding script which is only designed to work with FlowPlayer and therefore should not be generally selectable.
• operations: Option menu path to a settings page for the theme/handler. If included then a 'configure' link will be put on the settings page. If omitted then no link appears.
• elements: Optional array of element properties to be merged with the element at render time. While it is possible to place any Form API property in here the logic is that a handler might want to do some pre- or post- rendering of its own, so this key allows the theme to register extra #pre_render and #post_render properties. Could be used to let a handler put, say, an image in case embedding fails.
• cacheable: Not sure about this - a theme could indicate if it can handle cached content or not. Not sure when this would be used - maybe an error could be flagged if a non-cacheable handler is asked to prepare cached content?

This list seems to have grown, but I think it's nearly finalised (there can't be much else we need to know about handlers!)