Autonews
========

Infusion for phpFusion v 7, Autonews v 1.1


Purpose:
-------

To provide a tool to send automatically mails to subscribing users
containing information about changes on your site.

In the admin setup you decide how frequent the mail should be (ie daily or weekly),
and you specify which parts of your site to include. Nearly all parts of phpfusion
are covered (news, articles, photoalbums, photos, forum threads, forum posts,
downloads, weblinks, comments, new users, shoutbox).

Your users are subscribing to the mail by checking the autonews user field,
which is a part of the infusion. If they dont like your mails, the mail contains
an unsubscribe link.

Mails are send automatically, and you do not need to set up a cronjob or similar
service. Admins can monitor the status (number of subscribers, time for last mail
sending, etc.) in a side panel.

Admin settings are provided to avoid overloading of your site or your mailserver. 
You can specify a chunk size so that mail sending do not get too large and you can
specify a waiting time between two mail sendings.

You can give your mails a personal touch by adding graphics to it. Obviously the 
language of your mails obey the language of your site (provided that a locale
file for your language is available).


Installation:
-------------

1. Install the infusion

	a. Download autonews_infusion.zip
	b. Copy with your FTP-program the entire content of the files directory from 
	   autonews_infusion.zip to your phpfusion main folder
	c. Under Administration - Infusions: Install the infusion
	d. Under Administration - Users - Users Fields: Activate the autonews field
	e. Under Administration - System - Elements: Install autonews_panel.php as
	   an element and activate it

2. Use the infusion
	a. The infusion has an admin panel and a status site panel. Both are shown only
     to users having admin right in autonews
  b. The status panel provides information regarding sending mails. The admin
     panel is used to change settings
  c. If you receive an error when involing the admin panel, it is probably
     because you failed to complete items 1d and/or 1e
  d. After installation the infusion is disabled. Until you have changed this in
     the autonews admin panel, no mails will be send
  e. Mails are only send to subsribing users, ie users who has checked autonews
     in their profile (a user-defined field)
     
Update:
-------

1. Just copy with your FTP-program the entire content of the files directory from
   autonews_infusion.zip to your phpfusion main folder (no database changes)

Admin:
------

In the admin panel you can change the settings of autonews. The following comments
apply:

  Frequency: You can specify the time between mail sendings, but you cannot specify
  time
  At least xxx news: If there are too few news the mail is nots end. Next time
  mails are send, it will look at the entire period since last sending, meaning
  that news will accumulate, until you reach the lower limit
  Maximum xxx news: If there are too many news, a summary line is created regarding
  the lines that are left out. The soring goes by date, so its the oldest news that
  are summarized and left out in the details
  Send to max xxx persons at a time:
  Pause for at least xxx minutes between mails:
  These features have been incorporated to avoid overload and/or timeout if you
  have many subscribers or your mail server is slow or heavy loaded
  Banner files: To be located in your 'images' directory

In the admin panel you have the following options:

  Test present mail: Use this to see the effect of changed settings. It shows the
  mail that would have be send at the time of clicking, if sending was due. It also
  shows the receivers of the mail
  Show previous mail: Use this to see the most recent send mail. The list of 
  receivers reflects the present settings, therefore not necessarily the subscribers
  at the time of sending the mail
  Unsubscribe all: Deletes all subscribers 


Background:
-----------

It is the side element that handles generation and sending of the mail. To usual
users it is not visible, but every time a page with the element is generated, it
checks whether mails should be send, and does so if appropriate.

Therefore, if your page is seldomly used, autonews cannot guarantee, that mails
are send in due course.

Effort has been put into minimizing the load represented by the autonews panel.
Only one query is done to see if sending is due, and only if this is the case
the mail is generated. Mail sending can be divided into chunks. Even when mail 
sending is divided into chunks, the generation of the mail (which obviously takes
the most queries) is only done once. 


Modifications:
--------------

Those parameters of autonews, that cannot be adjusted in the admins panel,
but which have relevance, are placed in the autonews_params.php file:
  
  sendasbcc: TRUE: Mails will be send as 'bcc' with no one in the 'to' field.
             FALSE: Mails will be send one by one with the receiver in the 'to'
             field.
             The first is the most efficient, but sending 'bcc' with an empty 
             'to' field causes problems on some mail servers. If you experience
             that mails are not being sent, despite everything looking ok, try
             setting this parameter to FALSE
  fromemail: Override the value of settings['siteemail'] as the sender of emails
  copyemail: Specify an email adress to receive a visible copy of all mails send
             Be aware that if 'sendasbcc' is set to FALSE you will receive one
             additional mail per subscriber. Maybe not that fun!
  hsgallery: Set to TRUE to invoke support of hsgallery
  cronjob:   Set to true to use cronjob to send emails rather than the panel.
             Follow the instructions in infusions/autonews/autonews_cronjob.php

The date formats used are defined in locale.php (AN010 and AN011) for easy 
adjustment.

Autonews is intended for easy addition of new types of news, for example
regarding infusion you are using. Doing so requires that you are capable of
writing a query that retrieves the needed data, and that you have a decent
understanding of PHP. Please see the file adding_more_news.txt, which contains
an example of how to extend autonews to report future birthdays.

Tips and tricks:
----------------

You may want to make all users subscribing by. There may be legal issues 
regarding obtaining permission from users to do that and issues regarding spam. 
However there are also situations, where these are either dealt with or 
irrelevant.

Make all users subscribe:
You can subscribe all userby executing the following url:

http://www.mysite.com/infusions/autonews/autonews_subscribe.php?aid=xxx&uid=all&s=1

You need to be logged in as an admin with admin rights to autonews and you need 
to replace xxx in the above with your aid, which you can copy from any phpfusion 
admin url. It's a string of 16 letters and digits, that is unique to each user, 
and provides additional safety.

Make subscription the default for the user field:
That will however not solve it for new users - they will still be non-subscribers. 
To make subscription the default, you need to edit 
includes/user_fields/user_autonews_include_var.php and change this line

$user_field_dbinfo = "TINYINT(1) NOT NULL DEFAULT '0'";

to

$user_field_dbinfo = "TINYINT(1) NOT NULL DEFAULT '1'";

You need to do so before activating the user field. If the field is already
activated you need to deactivate, make the change, and activate it again. Be
aware that you'll use existing subscription information.

Thanks to:
----------
Hunden, afoster, kiko26 and others for providing valuable feedback and for testing.

Changelog:
----------

Ver Date    Changes
1.0	091129	First version
1.1	100315	Wrong English locale in user-field fixed
            Localisation of footer email text provided for
            French locale added (thanks to kiko26)
            Dutch locale added (thanks to Scheper)
            Use of date(...) in formatting dates changed to strftime(...) to 
            take into consideration users locale
            Timezone set in php-fusion is now accounted for
            Test added in admin panel to inform user if user field and autonews
            panel have beed correctly added (enhancement to facilitate correct
            use of infusion)
            Option added (in autonews_settings.php) to select between sending
            mails as "bcc" (as in v1.0) or one by one as "to". Introduced to
            accomodate for problems with "bcc" encountered on some mail servers
            Wrong link to "unsubscribe" in mail corrected (twice)
            Minor bug corrected in autonews_subscribe.php
            Error fixed in photos query that reported new picture when an empty 
            album was created
            Error fixed in photos query that used album_date rather than
            photo_date to determine age
            "Tips and tricks" added to "read-me"
            "adding_more_news.txt" added with description of how to extend 
            autonews
                      