modules/birthdays/README.txt

// $Id: README.txt,v 1.6 2008/10/01 10:37:26 maartenvg Exp $

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