You are here

README.txt in Birthdays 5

Same filename and directory in other branches
  1. 6 README.txt
  2. 7 README.txt
CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Features
 * Requirements
 * Installation & Upgrading
 * Settings
 * Synchronizing
 * Customizing the module
 * Maintainers


INTRODUCTION
------------

The Birthdays module allows users to add their birthday to their profile. In
their profile the date of birth is show, as well as their age and their
star sign. This is all configurable. It also lists birthdays on a separate page
which can be filtered by month and year. Finally 2 blocks are defined to show
upcoming birthdays, either a fixed number or a specific number of days in
advance.

It is optional to send users an e-mail on their birthday congratulating them,
and the administrator can receive periodic reminders of who are having their
birthday next day, week or month.


FEATURES
--------

 * Integrates with Profile module.
 * Birthday input field on registration (or not)
 * A block displaying the next X birthdays.
 * A block listing birthdays for the next X days.
 * A page listing all the users and their birthdays/age/star sign, filtered by
   month and year.
 * Optionally displays user's star sign, with or without a link to Yahoo
   Horoscopes.
 * Displaying the user's birthday/current age/star sign on the user's profile.
 * User option not to be mailed on their birthday.
 * User & admin option to hide the year and age of the user(s).
 * User options can be turned off by administrator.
 * Optionally send e-mails to administrator with upcoming birthdays for the
   next day, week or month.
 * Optionally sends an e-mail to the user on their birthday.
 * Possibility to synchronize between the Birthdays module and the Profile
   module when necessary.
 * PGSQL support

Future features

 * Re-introduction optional postcard module support
 * Add optional Events module support
 * Use CCK field to enable use for Calendar, Node Profile and similar modules
 * Make visible for Views module
 * Add translations (files)


REQUIREMENTS
------------

The Birthdays module requires the Profile module which is a Core module that
comes with Drupal. It requires you to make a field of the type 'date'. To
receive administration e-mails or send out birthday wishes, cronjobs are
needed. See http://drupal.org/cron for more information about setting up
cronjobs.

This module no longer requires a version MySQL >= 4.1.1.


INSTALLATION & UPGRADING
------------------------

See INSTALL.txt for install/upgrade instructions.


SETTINGS
--------

Setting the module is done on a number of pages.

  Birthdays administration pages
  ------------------------------
  The Birthdays administration pages (?q=admin/settings/birthdays) is where the
  actual features of the birthdays module are set. Some of the options are
  described below.
  * 'Profile field': here you set which 'date' field of the Profile module you
    want the Birthdays module to use.
  * 'Show starsings': select whether you want to display the star sign icons on
    the profile and on the Birthdays page, and, if so, whether it should link
    to Yahoo Horoscopes.
  * 'Hide year and age': some sites might want to protect the user's privacy by
    hiding their age and year of birth. The options are 'No', 'Yes' and 'User
    optional, defaults to No', where the latter gives the user the option to
    select whether he or she wants this infomration to be hidden. If enabled it
    still requires them to put the full date of birth in, but only the day and
    month will be displayed.
  * 'Set Birthdays page settings': this influences how the listing of the
    Birthdays page is shown. Sorted by username of date of birth (year not
    included) and users without a birthday shown or not.
  * 'Show filter options': determine whether the buttons to filter by specific
    month and/or year should be displayed. When 'Hide year and age' is set to
    'Yes', filtering by year is not possible.
  * 'Send upcoming birthdays to admin': this one has 4 values 'Disabled',
    'Daily', 'Weekly, on the first day of the week' and 'Monthly'. This will
    send an e-mail to your site e-mail address at the given intervals, listing
    users that will have their birthday in that period. The first day of the
    week is controlled by the date and time settings of Drupal, which can be
    found at ?q=admin/settings/date-time.
  * 'Send user e-mail on day of birth': set whether users should receive an
    e-mail when they are having the birthday. Either 'No', 'Yes' or 'User
    optional, 'Yes' by default', where the latter leaves the decission up to
    the user.

  Permissions
  -----------
  To allow users to view birthdays of other people, the 'access birthdays'
  permission needs to be set for the appropiate role. This allows them to
  access the Birthdays page (?q=birthdays), see activated blocks with birthdays
  and view the birthday of the user in the profiles.

  Profile field settings
  ----------------------
  Several things can be adjusted to the assigned profile field. To do so please
  visit to ?q=admin/user/profile, and edit the field in question. The following
  options require special attention.
  * 'The user must enter a value': force the user to fill in their date of
    birth. A once set birthday can not be deleted.
  * 'Visibile in user registration form': give new users the option to add
    their date of birth when registering to your website. If combined with the
    option above, they can not register without putting their date of birth.
  * 'Visibility': this will influence the visibility of the field as described
    there, but the behavior might become erratic if not set to 'Public field,
    content shown on profile page but not used on member list pages'. So it is
    recommended to leave this as is.

  The other options on this page behave as described there.
  * 'Category': this controls with which other fields the birthdays field is
    shown.
  * 'Title': setting the visual name of the field.
  * 'Form name': changing this will not change anything visible to the user.
  * 'Explanation': add additional information about what the birthdays field
    does below the field.
  * 'Weight': will change the position of the field compared to other fields in
    the same category.

  Date format
  -----------
  The way the birthdays are formatted (e.g. 11 may 1934 or 05/11/1934) is
  controlled by the date and time settings of Drupal, which can be found at
  ?q=admin/settings/date-time. The Birthdays module uses the short date format
  as basis for displaying days and months in the blocks and the medium date
  format is used in the profile and on the Birthdays page.


SYNCHRONIZING
-------------

A special page is located at ?q=admin/settings/birthdays/sync. The birthdays
are saved to two different database tables. This is because the profile module
saves the dates in a format which limit the ability to perform calculations on
the dates. These two tables need to be in sync with each other, which will be
most of the time.

Sometimes this is not the case. For example when you already collected
birthdays with the Profile module, but later decided to switch to the birthdays
module. Or when you accidentally (on intentionally) completely uninstalled the
profile module, but left birthdays module merely disabled.

In the first case you need to copy the Profile data to the (most likely empty)
Birthdays table, which is done with the top button. In the latter you need the
copy the birthdays in the Birthdays table back to the Profile module with the
bottom button.

Please note that with large amounts of users this might take some time.


CUSTOMIZING THE MODULE
----------------------

Sometimes you might want to customize the way some areas of the module look.
For instance, you might want to alter the Birthdays page, or change the listing
in the Birthdays blocks. This can be done by overriding the theme functions.
How to do so can be found here: http://drupal.org/node/173880.

If you want to display the date of birth or age on another location (e.g. near
the username, in the forums, on nodes), you best use the functions
$age = _birthdays_show_age($account);
$date = _birthdays_show_date($date_array, $account, 'medium');

These will adhere to the global or user determined visibility of the age and
year of date.

More specific information might follow later.


MAINTAINERS
-----------

 * David Gildeh (Drazzig) - http://drupal.org/user/26260
 * Maarten van Grootel (maartenvg) - http://drupal.org/user/109716

File

README.txt
View source
  1. CONTENTS OF THIS FILE
  2. ---------------------
  3. * Introduction
  4. * Features
  5. * Requirements
  6. * Installation & Upgrading
  7. * Settings
  8. * Synchronizing
  9. * Customizing the module
  10. * Maintainers
  11. INTRODUCTION
  12. ------------
  13. The Birthdays module allows users to add their birthday to their profile. In
  14. their profile the date of birth is show, as well as their age and their
  15. star sign. This is all configurable. It also lists birthdays on a separate page
  16. which can be filtered by month and year. Finally 2 blocks are defined to show
  17. upcoming birthdays, either a fixed number or a specific number of days in
  18. advance.
  19. It is optional to send users an e-mail on their birthday congratulating them,
  20. and the administrator can receive periodic reminders of who are having their
  21. birthday next day, week or month.
  22. FEATURES
  23. --------
  24. * Integrates with Profile module.
  25. * Birthday input field on registration (or not)
  26. * A block displaying the next X birthdays.
  27. * A block listing birthdays for the next X days.
  28. * A page listing all the users and their birthdays/age/star sign, filtered by
  29. month and year.
  30. * Optionally displays user's star sign, with or without a link to Yahoo
  31. Horoscopes.
  32. * Displaying the user's birthday/current age/star sign on the user's profile.
  33. * User option not to be mailed on their birthday.
  34. * User & admin option to hide the year and age of the user(s).
  35. * User options can be turned off by administrator.
  36. * Optionally send e-mails to administrator with upcoming birthdays for the
  37. next day, week or month.
  38. * Optionally sends an e-mail to the user on their birthday.
  39. * Possibility to synchronize between the Birthdays module and the Profile
  40. module when necessary.
  41. * PGSQL support
  42. Future features
  43. * Re-introduction optional postcard module support
  44. * Add optional Events module support
  45. * Use CCK field to enable use for Calendar, Node Profile and similar modules
  46. * Make visible for Views module
  47. * Add translations (files)
  48. REQUIREMENTS
  49. ------------
  50. The Birthdays module requires the Profile module which is a Core module that
  51. comes with Drupal. It requires you to make a field of the type 'date'. To
  52. receive administration e-mails or send out birthday wishes, cronjobs are
  53. needed. See http://drupal.org/cron for more information about setting up
  54. cronjobs.
  55. This module no longer requires a version MySQL >= 4.1.1.
  56. INSTALLATION & UPGRADING
  57. ------------------------
  58. See INSTALL.txt for install/upgrade instructions.
  59. SETTINGS
  60. --------
  61. Setting the module is done on a number of pages.
  62. Birthdays administration pages
  63. ------------------------------
  64. The Birthdays administration pages (?q=admin/settings/birthdays) is where the
  65. actual features of the birthdays module are set. Some of the options are
  66. described below.
  67. * 'Profile field': here you set which 'date' field of the Profile module you
  68. want the Birthdays module to use.
  69. * 'Show starsings': select whether you want to display the star sign icons on
  70. the profile and on the Birthdays page, and, if so, whether it should link
  71. to Yahoo Horoscopes.
  72. * 'Hide year and age': some sites might want to protect the user's privacy by
  73. hiding their age and year of birth. The options are 'No', 'Yes' and 'User
  74. optional, defaults to No', where the latter gives the user the option to
  75. select whether he or she wants this infomration to be hidden. If enabled it
  76. still requires them to put the full date of birth in, but only the day and
  77. month will be displayed.
  78. * 'Set Birthdays page settings': this influences how the listing of the
  79. Birthdays page is shown. Sorted by username of date of birth (year not
  80. included) and users without a birthday shown or not.
  81. * 'Show filter options': determine whether the buttons to filter by specific
  82. month and/or year should be displayed. When 'Hide year and age' is set to
  83. 'Yes', filtering by year is not possible.
  84. * 'Send upcoming birthdays to admin': this one has 4 values 'Disabled',
  85. 'Daily', 'Weekly, on the first day of the week' and 'Monthly'. This will
  86. send an e-mail to your site e-mail address at the given intervals, listing
  87. users that will have their birthday in that period. The first day of the
  88. week is controlled by the date and time settings of Drupal, which can be
  89. found at ?q=admin/settings/date-time.
  90. * 'Send user e-mail on day of birth': set whether users should receive an
  91. e-mail when they are having the birthday. Either 'No', 'Yes' or 'User
  92. optional, 'Yes' by default', where the latter leaves the decission up to
  93. the user.
  94. Permissions
  95. -----------
  96. To allow users to view birthdays of other people, the 'access birthdays'
  97. permission needs to be set for the appropiate role. This allows them to
  98. access the Birthdays page (?q=birthdays), see activated blocks with birthdays
  99. and view the birthday of the user in the profiles.
  100. Profile field settings
  101. ----------------------
  102. Several things can be adjusted to the assigned profile field. To do so please
  103. visit to ?q=admin/user/profile, and edit the field in question. The following
  104. options require special attention.
  105. * 'The user must enter a value': force the user to fill in their date of
  106. birth. A once set birthday can not be deleted.
  107. * 'Visibile in user registration form': give new users the option to add
  108. their date of birth when registering to your website. If combined with the
  109. option above, they can not register without putting their date of birth.
  110. * 'Visibility': this will influence the visibility of the field as described
  111. there, but the behavior might become erratic if not set to 'Public field,
  112. content shown on profile page but not used on member list pages'. So it is
  113. recommended to leave this as is.
  114. The other options on this page behave as described there.
  115. * 'Category': this controls with which other fields the birthdays field is
  116. shown.
  117. * 'Title': setting the visual name of the field.
  118. * 'Form name': changing this will not change anything visible to the user.
  119. * 'Explanation': add additional information about what the birthdays field
  120. does below the field.
  121. * 'Weight': will change the position of the field compared to other fields in
  122. the same category.
  123. Date format
  124. -----------
  125. The way the birthdays are formatted (e.g. 11 may 1934 or 05/11/1934) is
  126. controlled by the date and time settings of Drupal, which can be found at
  127. ?q=admin/settings/date-time. The Birthdays module uses the short date format
  128. as basis for displaying days and months in the blocks and the medium date
  129. format is used in the profile and on the Birthdays page.
  130. SYNCHRONIZING
  131. -------------
  132. A special page is located at ?q=admin/settings/birthdays/sync. The birthdays
  133. are saved to two different database tables. This is because the profile module
  134. saves the dates in a format which limit the ability to perform calculations on
  135. the dates. These two tables need to be in sync with each other, which will be
  136. most of the time.
  137. Sometimes this is not the case. For example when you already collected
  138. birthdays with the Profile module, but later decided to switch to the birthdays
  139. module. Or when you accidentally (on intentionally) completely uninstalled the
  140. profile module, but left birthdays module merely disabled.
  141. In the first case you need to copy the Profile data to the (most likely empty)
  142. Birthdays table, which is done with the top button. In the latter you need the
  143. copy the birthdays in the Birthdays table back to the Profile module with the
  144. bottom button.
  145. Please note that with large amounts of users this might take some time.
  146. CUSTOMIZING THE MODULE
  147. ----------------------
  148. Sometimes you might want to customize the way some areas of the module look.
  149. For instance, you might want to alter the Birthdays page, or change the listing
  150. in the Birthdays blocks. This can be done by overriding the theme functions.
  151. How to do so can be found here: http://drupal.org/node/173880.
  152. If you want to display the date of birth or age on another location (e.g. near
  153. the username, in the forums, on nodes), you best use the functions
  154. $age = _birthdays_show_age($account);
  155. $date = _birthdays_show_date($date_array, $account, 'medium');
  156. These will adhere to the global or user determined visibility of the age and
  157. year of date.
  158. More specific information might follow later.
  159. MAINTAINERS
  160. -----------
  161. * David Gildeh (Drazzig) - http://drupal.org/user/26260
  162. * Maarten van Grootel (maartenvg) - http://drupal.org/user/109716