README.txt in Advertisement 6.3

Overview:
---------
The ad_actions module provides triggers for the following
advertisement events:
 - an advertisement has been clicked
 - an advertisement has been approved
 - an advertisement has been activated
 - an advertisement has been denied
 - an advertisement has been marked as pending
 - an advertisement has been taken offline
 - an advertisement has been created
 - an advertisement has been updated
 - an advertisement has been deleted
 - an advertisement has expired
 - an advertisement has an approaching scheduled activation
 - an advertisement has been activated through scheduling
 - an advertisement has an approaching scheduled expiration
 - an advertisement has expired through scheduling

The triggers can be configured to cause any of the following
actions:
 - generate an email
 - display a custom message to the user
 - override the ad's redirect

Two advanced actions are provided by this module.  The first is
named 'Send e-mail before automated ad trigger', and can be used
to send emails before an advertisement is scheduled to be
activated or expired.  The second is named 'Send e-mail on or
after ad trigger' and can be used with any of the triggers defined
by this module.

This module depends on the token module, allowing you to create
dynamic notifications.


Permissions:
------------
In order to configure ad triggers, users must be in a role that
has the 'administer ad triggers' permission.


Examples:
---------
This documentation offers two examples of how you can use the
triggers and advanced actions provided by this module. It also
explains how you can provide per-user configuration options
for disabling notification emails.


 Click notification:
 -------------------
 The following example shows you how to send an email to the
 owner of an advertisement whenever the advertisement is
 clicked.  In this example, we configure the action to send
 no more than one email in every 24-hour period.

  Part I)
  -------
  1) Go to Administer >> Site configuration >> Actions and
     in the "Make a new advanced action available" section
     toward the bottom of the screen select "Send e-mail on
     or after ad trigger" from the drop down menu and click
     Create.
  2) Enter something descriptive in the description field,
     for example you could enter "Send email after
     advertisement is clicked".
  3) Enter "[owner_email]" in the Recipient field.  This is
     a token that will automatically be replaced when the
     notification is sent.  For a complete list of
     available tokens click the "Placeholder tokens" link.
  4) Enter "Ad [title] has been clicked" in the Subject
     field.
  5) Enter the following into the Message field:
       Hello [owner_name],
       Your advertisement has been viewed [today_impressions]
       times and clicked [today_clicks] times today.
       - The [site-name] team.
  6) Set the 'When to send' field set to '1 day after'.
  7) Click the 'Save' button.
 
  Part II)
  --------
  1) Go to Administer >> Site building >> Triggers and
     in the "After an advertisement has been clicked"
     section click the "Choose an action" menu and select
     the action you created in Part I above.
  2) Click the 'Assign' button.
 
 With the above action defined and assigned to the click
 trigger, once an advertisement is clicked a notification
 to the ad's owner is added to a queue. If the
 advertisement is clicked again during the next 24 hours
 no additional notification is added to the queue.  24
 hours after the ad was first clicked, the notification
 email is sent out.  The token replacement happens when
 the email is sent, so all subsequent clicks are reflected
 in the notification email.


 Allowing users to disable notifications:
 ----------------------------------------
 It is possible to allow individual users to disable the
 notifications generated by the advanced actions defined
 by this module.

  Part I)
  -------
  1) Enable the profile module, which is part of the core
     Drupal installation.
  2) Go to Administer >> User management >> Profiles and
     click "checkbox" under the 'Add new field' heading.
  3) Enter 'Advertisements' for the Category.
  4) Enter 'Disable click notifications' for the Title.
  5) Enter 'profile_disable_click_notifications' for the
     Form name.
  6) Enter 'Check this box to disable click notification
     emails.  When this box is unchecked, you will 
     receive email notifications once every 24 hours when
     your advertisements are clicked.'
  7) Set the Visibility to 'Private field, content only
     available to privileged users.'
  8) Click 'Save field'.

  Part II)
  --------
  1) Go to Administer >> Site configuration >> Actions and
     click 'configure' next to the advanced action you
     created in the above example.
  2) Scroll down and select 'Disable click notifications'
     for the 'Profile field used to disable notifications'
     (This option will only be visible after you have
     enabled the profile module and created at least one
     user profile field.
  3) Click 'Save'.

  Part III)
  ---------
  1) Users with proper permissions can now click 'My
     account' in the navigation block, then click
     the 'Edit' tab, and finally click the
     'Advertisements' subtab.  On the subsequent
     screen they can disable notification emails for
     their account.

 The above is just one example of how you may allow
 users to disable notifications. You may wish to use
 something other than a checkbox for the user's profile
 field -- the field type is not important, though
 notifications will only be disabled when the user
 sets the field to a non-empty non-zero value.

 You can re-use the same profile field with multiple
 actions, thereby providing a single checkbox to
 disable all notifications.  Or, you can create a
 unique profile field for each advanced action
 providing your users with more granular control
 over the notification emails.

 It would be a good idea to explain to your users how
 they can disable notifications in each notification
 email that is sent.


 Notify that an ad is about to expire:
 -------------------------------------
 The following example shows you how to send an email to all
 owners of an advertisement 1 week before the advertisement
 is scheduled to be automatically expired.

  Part I)
  -------
  1) Go to Administer >> Site configuration >> Actions and
     in the "Make a new advanced action available" section
     toward the bottom of the screen select "Send e-mail
     before automated ad trigger" from the drop down menu
     and click Create.
  2) Enter something descriptive in the description field,
     for example you could enter "Send email 1 week before
     advertisement expires."
  3) Enter "[all_owner_emails]" in the Recipient field.  This
     is a token that will automatically be replaced with a list
     of all email addresses for all owners of a given
     advertisement when the email is generated.  For a complete
     list of available tokens click the "Placeholder tokens"
     link. (The [ad_owner_emails] token is only available if
     you have enabled the ad_owners module.)
  4) Enter "Ad [title] will expire in 1 week" in the Subject
     field.
  5) Enter the following into the Message field:
       Hello [owner_name],
       To date, your advertisement has been viewed
       [global_impressions] times and clicked [global_clicks]
       times.  Your advertisement will expire in about
       1 week, on [autoexpire_large].
       - The [site-name] team.
  6) Set the 'When to send' field set to '1 week before'.
  7) Click the 'Save' button.
 
  Part II)
  --------
  1) Go to Administer >> Site building >> Triggers and
     in the "Scheduled expiration" section click the
     "Choose an action" menu and select the action you
     created in Part I above.
  2) Click the 'Assign' button.
 
 With the above action defined and assigned to the scheduled
 expiration trigger, a notification email will be sent to
 all of the ad's owners 1 week before it will expire.