pierre@0: ---------
pierre@0: Overview:
pierre@0: ---------
pierre@0: This document is intended to help someone write a module for the ad api to
pierre@0: introduce a new ad type. The core ad module includes two ad type modules, one
pierre@0: for text ads and another for image ads. You can use the same api used by these
pierre@0: two ad type modules to create your own custom ad type module, for example you
pierre@0: may wish to write a module to ad support for flash ads. Some familiarity with
pierre@0: Drupal and PHP is required.
pierre@0: 
pierre@0: --------------------------
pierre@0: Naming your new ad module:
pierre@0: --------------------------
pierre@0: There are two ad types included with the core ad module, text ads and image
pierre@0: ads. Each ad type lives in its own module. Text ads are defined in the
pierre@0: ad_text module, and image ads are defined in the ad_image module. All
pierre@0: additional types of ads should be defined in modules following the same naming
pierre@0: scheme which is 'ad_' followed by the type of ad. For example, if you are
pierre@0: creating a module to add support for flash-based ads, you would call your
pierre@0: module ad_flash.
pierre@0: 
pierre@0: ------------------------------
pierre@0: Registering a new style of ad:
pierre@0: ------------------------------
pierre@0: Within the Drupal framework, ads are nodes. To create a new ad, a user
pierre@0: navigates to "create content >> ad", on which page they will be prompted
pierre@0: to select the type of the ad they wish to create. Your new ad type can
pierre@0: be added to this list by using the _adapi() hook and the 'type' operator. 
pierre@0: For example, if creating a module for flash ads, you might add the following 
pierre@0: function:
pierre@0: 
pierre@0: ad_flash_adapi($op, $ad = NULL) {
pierre@0:   switch ($op) {
pierre@0:     case 'type':
pierre@0:       return array(
pierre@0:         'flash' => array(
pierre@0:           'name' => t('Flash ad'),
pierre@0:           'module' => 'ad_flash',
pierre@0:           'description' => t('A flash advertisement.'),
pierre@0:           'help' => t('A flash advertisement.'),
pierre@0:         ),
pierre@0:       );
pierre@0:   }
pierre@0: }
pierre@0: 
pierre@0: ------------------
pierre@0: Displaying your ad
pierre@0: ------------------
pierre@0: To display an ad, your ad type module needs to define the _display_ad() hook.
pierre@0: Be aware that when this function is called, many standard Drupal functions
pierre@0: are not available to you as the adtype.php script will only bootstrap to
pierre@0: DRUPAL_BOOTSTRAP_DATABASE.
pierre@0: 
pierre@0: You are passed in an object which contains the ad ID (aid) and the redirect
pierre@0: URL (ie 'ad/redirect/13'). Utilize this information to return the complete
pierre@0: advertisement. For example:
pierre@0: 
pierre@0: function ad_static_display_ad($ad) {
pierre@0:   $return "<a href=\"$ad->redirect\">Static ad #$ad->aid</a>";
pierre@0: }
pierre@0: 
pierre@0: --------------------------------
pierre@0: Sharing your new ad_type module:
pierre@0: --------------------------------
pierre@0: The drupal.org CVS contributions repository requires that all included modules
pierre@0: be licesensed under the GPL. The ad module is dual licensed under both the
pierre@0: GPL and the BSD license, meeting this requirement. You can license your
pierre@0: new ad_style module under just the GPL, or under a dual license as long as
pierre@0: one of the licenses is the GPL.
pierre@0: 
pierre@0: If your module meets the above licensing requirements and you feel other Drupal
pierre@0: users could benefit from your work, contact the ad module maintainer to have
pierre@0: your module reviewed for inclusion.