// $Id: API.txt,v 1.1.2.2 2008/08/16 17:58:32 jtsnow Exp $ *------------------------ * Embed Widgets API *------------------------ The Embed Widgets API allow module developers to do two things: 1. Create widget sources. 2. Create additional widget formats. Both are described below. *------------------------ * Creating Widget Sources *------------------------ This is done using hook_widgets(). Implementations of hook_widgets() must return an associative array. For an item to be listed as a source, it must be in $widgets['sources'] A basic example: 'example_widget', 'title' => 'Hello World', 'description' => t('This is just an example.'), 'settings' => array( 'content' => t('This is a very basic widget source.'), ), ); return $widgets; } ?> This code creates a widget source with the title "Hello World" and displays the string "This is a very basic widget source." as its content. The 'sid' and the array key must be the same for each source specified. A more advanced example: 'profile', 'title' => 'Profile', 'description' => t("Displays the current user's profile."), 'settings' => array( 'content' => 'profile_widget_display', 'function' => TRUE, 'file' => drupal_get_path('module', 'embed_widgets') . '/widgets.inc', 'arguments' => array( 'user_id' => array( '#type' => 'hidden', '#value' => '%uid', ), ), ), ); return $widgets; } /** * Display a user's profile. * * Content callback function for profile widget source. */ function profile_widget_display($args = array()) { $account = user_load(array('uid' => $args['user_id'])); require_once './' . drupal_get_path('module', 'user') . '/user.pages.inc'; $output .= '

' . $account->name . '

'; $output .= user_view($account); return $output; } ?> This source accepts a user ID as an argument and displays that user's profile. This is accomplished by: 1. Supplying a function name as the 'content' property. 2. Setting the 'function' property to TRUE. 3. If necessary, specifying the path and filename where the function can be found. 4. Specifying an argument. The arguments property is an array of FAPI elements. In the example above, it is a hidden form element. This form will be displayed to the user when editing a widget. The function specified in the 'content' property will be called with an array of arguments as the only parameter. In the following example, the function 'my_widget_content' may be called with the following array as an argument: $args = array( 'name' => 'Joe', 'food' => 'Pizza', } 'example2', 'title' => 'Example 2', 'description' => t("This is an example"), 'settings' => array( 'content' => 'my_widget_content', 'function' => TRUE, 'arguments' => array( 'name' => array( '#title' => 'Your Name', '#type' => 'texfield', '#size' => 20, '#default_value' => 'Goober', ), 'food' => array( '#title' => 'Favorite Food', '#type' => 'texfield', '#size' => 25, '#default_value' => '', ), ), ), ); return $widgets; } /** * Content callback function for example2 widget source. * * Displays user's name and favorite food. */ function my_widget_content($args = array()) { $output = 'Name:' . $args['name'] . '
'; $output .= 'Favorite Food:' . $args['food'] . '
'; return $output; } ?> *------------------------ * Creating Widget Formats *------------------------ To create a widget format, you must use hook_embed_widget_types(). An example from the Google Gadgets module: array( 'title' => t('Google Gadget'), 'description' => t("Uses Google's Gadget API. Can be embedded on any website, your iGoogle home page, or any OpenSocial container."), 'code callback' => 'embed_widgets_google_gadgets_code', 'content callback' => 'embed_widgets_iframe_content', 'embed callback' => 'embed_widgets_google_gadgets_embed', 'embed filename' => 'gadget.xml', 'preview callback' => 'embed_widgets_google_gadgets_code', 'live preview callback' => 'embed_widgets_google_gadgets_live_preview', 'settings form callback' => 'embed_widgets_google_gadgets_settings', 'admin settings form' => 'embed_widgets_google_gadgets_admin_settings', 'custom theme callback' => 'embed_widgets_google_gadgets_customize', ), ); } ?> hook_embed_widget_types() must return an associative array. The first item in the array is the machine readable name of your format. Use only alphanumeric characters, hyphens (-), or underscores (_). This item is an array of information about your format. The array MUST contain the following keys: title ----------------- The user friendly name of your format. Will be displayed in user interface. description ----------------- This is used to describe to users how your format can be used and where widgets of this format can be embedded. code callback ----------------- The name of the function that is called to get the widget embed code. Must return a string. This function must accept the following argument: $embed_widget: The widget information as an array. As returned by embed_widgets_load(). content callback ----------------- The name of the function that is called to generate the content of your widgets. This function will likely call embed_widgets_build_content($embed_widget, $widget_type). You may then theme the returned content however you like. This function must accept the following arguments: $embed_widget: The widget information as an array. As returned by embed_widgets_load(). $widget_type: The machine readable name of your format. This function should not return anything. It should print the themed content. preview callback ----------------- The name of the function that is called when a widget is viewed in your format. This will likely be the same as 'code callback'. This function must accept the following argument: $embed_widget: The widget information as an array. As returned by embed_widgets_load(). This function must return a string of HTML. live preview callback ----------------- The name of the function that is called when a live preview is generated in your format. This function is necessary because not all code used to embed a widget is rendered when returned via AHAH. For example, JavaScript. If necessary, This function provides a more simplified version of the embed code in 'code callback'. This function must accept the following argument: $embed_widget: The widget information as an array. As returned by embed_widgets_load(). This function must return a string of HTML. settings form callback ----------------- The name of the function that is called when a widget is being created. This function returns a FAPI form array. This form is included in the widget creation form, allowing you to provide options specific to your widget format. If the machine readable name of your format were 'my-widget', your options would stored in the widget array as $embed_widget['settings']['my-widget']['option1'] $embed_widget['settings']['my-widget']['option2'] The names of the "options" are the names of the form elements. This function must be able to accept an array of default values. The keys of the array are the names of the form elements and the values are to be used as the default values for the form elements. custom theme callback ----------------- This function is called when the theme 'Custom' is chosen. This function prints a CSS file that is included on the widget content page. This function must accept the following argument: $embed_widget: The widget information as an array. As returned by embed_widgets_load(). Remember to set the HTTP header for CSS: drupal_set_header('Content-type: text/css; charset=utf-8'); The array may contain the following keys: embed callback ----------------- The name of a function that prints a file used by your format. This function is used if your format requires a file of some kind. For example, the iFrame format uses a JavaScript file; The Google Gadgets format uses an XML file. This function must set the content-type HTTP header for the type of file your are using. This function must accept the following argument: $embed_widget: The widget information as an array. As returned by embed_widgets_load(). This function does not return any value. This function prints the contents of your file. embed filename ------------------ The name of the file to be appended to the URL. For example, 'gadget.xml'. admin settings form ------------------ The name of a function that returns a FAPI settings form. This form will be displayed as a local menu item in Administer -> Site Configuration -> Embed Widgets.'. This is useful to provide any configuration options for your module. Please see the exising iFrame, Google Gadgets, and Facebook modules for examples of how to implement these functions. The Facebook module provides a very simple example. Helper functions: The following functions are used for common tasks when creating a widget format: embed_widgets_get_url(embed_widgets_get_url($embed_widget, $widget_type, $callback = 'embed'); This function generates a URL for the menu item that will use either 'embed callback' or 'content callback' as the callback. It accepts the following arguments; $embed_widget: The widget information as an array. As returned by embed_widgets_load(). $widget_type: The macine readable name of your format. $callback: Either 'embed' or 'content', depending on which function you need. embed_widgets_build_content($embed_widget, $widget_type); This function generates the content for a widget and all of its sources. It accepts the following arguments; $embed_widget: The widget information as an array. As returned by embed_widgets_load(). $widget_type: The macine readable name of your format. It returns the following array: - $content['title']: The widget title. - $content['head']: HTML to be placed in tag. - $content['scripts']: Necessary JavaScript includes. - $content['css']: Necessary CSS includes. - $content['tabs']: An array of tabs with the following format for each source: -$content['tabs'][$sid]['title']: The title of the source -$content['tabs'][$sid]['content']: The source content. -$content['tabs'][$sid]['breadcrumb']: If source is a path, breadcrumb trail of the source's menu item. -$content['tabs'][$sid]['submitted']: If source is a node, information on who modified the node and when. -$content['tabs'][$sid]['created']: If source is a node, information on who created the node and when. -$content['tabs'][$sid]['taxonomy']: If source has any taxonomy terms, contains a list of those terms. - $content['content']: The content for the active tab. - $content['footer']: The widget footer. - $content['button']: The embed button provides a link for other users to embed the widget.