JINC THE ADMINISTRATION GUIDE

Transcription

1 JINC THE ADMINISTRATION GUIDE Author Lhacky Date 06 September 2010 Version 1.0 Software Version JINC 0.7 1

2 SUMMARY About this document...3 Intended audience...3 JINC Capabilities...4 JINC Installation...6 JINC Main Page...8 JINC Global configuration...8 Newsletter Management...10 Newsletters List...10 Newsletter Editing...11 Newsletter Publishing in Frontend...12 Message Management...14 Messages list...14 Message Editing...14 Tags substitution...15 Message sending process...16 Subscriber Management...18 Subscribers Import from CSV file...18 Subscription to a Public Newsletter...19 Subscription to a Protected or Private Newsletter...20 Autosubscription after Joomla! User Registration...21 Statistics...22 Appendix A. Theme Management...23 Appendix B. Addictional Attribute Management

3 ABOUT THIS DOCUMENT The JINC (Joomla! Integrate Newsletter Compment) is a Joomla! component to manage newsletters that can help Joomla! administrator to communicate with users and guests. This document describes the activities to administer JINC in order to create newsletters, send messages and manage subscribers. This paper contains also the description of the main functionalities JINC provides to help the administrator to compose messages, to follow the subscription trend, to allow automatic subscription to a newsletter and so on This document refers to JINC version 0.7. INTENDED AUDIENCE The intended audience of this document are Joomla! administrators who wants to communicate with users and guests using one or more newsletters. 3

4 JINC CAPABILITIES This section lists the main functionalites JINC provides to the administrator during newsletters management. Basic Management Profiling Auto-subscription Default template Welcome Message Disclaimer Themes management Template management Content type management Massime or personalized mails Attachment TAG substitution Start/Stop functionalities confirmation Massive import Groups management Joomla! Contact Integration Addictional attributes Event based statistics Time based statitics Statistics charts Hints Forum Frontend translations Backend translations Newsletters Creation and editing of unlimited number of newsletters. Access restriction to a newsletter to guests, users or groups of users. Automatic newsletter subscription after Joomla! user registration. Automatic loading of default message template during message creation. Welcome message after newsletter subscription. Disclaimer automatically added to every newsletter message. Several frontend themes available to show a newsletter in Joomla! frontend Messages Definition of message templates to avoid copy and paste at every message creation. Possibility to choose between plain text and HTML messages. One mail per subscriber or mails with a lot subscribers in Blind Carbon Copy. Attachment capabilities. Subscribers and newsletters info TAGs substituted while sending process. Possibility to start the message sending process, pause it and re-start later Subscribers Mail confirmation during subscription and unsubscription by opt-in messages. Import subscriber lists from CSV files. Creation of groups of potential subscribers for private newsletters. Possibility to retrieve subscribers information from Joomla! contacts Administrator definible mandatory or optional attributes to subscribe a newsletter Statistical Functionalities Statistics registered based on events (subscription, unsubscription, message sent). Statistics showed by time line. Trend of events time based showed in a chart. Documentation Activable and disactivable hints during JINC administration. Forum on site Translations Frontend translated in english, italian, french, spanish, german and dutch Backend translated in english and italian 4

5 5

6 JINC INSTALLATION The JINC installation process is really easy. You have simply to download the latest JINC version from this link JINC Download Page and install it using standard component installation tool as in figure The installation process installs not only the component, but also two modules and a plugin, listed here The mod_jinc_news_access module is useful to create a list of newsletter accessible by the frontend user (or guest). The mod_jinc_subscription module is useful to let the user subscribe from Joomla! frontend inserting necessary information (i.e. his mail address or name depending on newsletter type). The JINCSubscription plug-in is useful to automatically subscribe a Joomla! user just after registration. During installation process JINC creates some tables in database with prefix #_jinc_ where #_ is your table prefix for Joomla! When you uninstall the JINC the uninstallation process will remove the component, the module and the plug-in, but no data nor table will be erased from database. 6

7 Before installing and uninstalling JINC is recommended you make a Joomla! complete backup. 7

8 JINC MAIN PAGE JINC can be accessed by Joomla! administrator through the Component menù of Joomla! administration. The main page, as displayed in the following figure, allows to access every JINC functionalities and shows information about version, license and links to documentation and forum. Using the main page you can also check your JINC version and the latest version available. JINC GLOBAL CONFIGURATION Using the link 8 of the JINC Main Page you can access the JINC global configuration that is useful to set general behariours of the comeponent. As you can see in the next figure, there are only few parameters to configure for JINC: Mail per AJAX step. The sending newsletter can be a very long process depending on number of subscribers. JINC implements this process using several AJAX steps to avoid failure caused by network timeout (i.e.: HTTP timeout). With this parameter you can set how many mails will be sent every AJAX step during sending process. Default: 5. Time interval between mails. During newsletter sending JINC sends a lot of mails depending on number of subscribers and it waits for some times before to send successive mail. Sending mails without time interval should be avoided, because the SMTP server receiving the mail flow could consider it as a DoS attack or a SPAM attempt. Most of SMTP servers will block the sender causing newsletter sending process failure. This parameter allows JINC administrator to set a time interval to wait before send the following mail. Default: 1000 ms. Max number of recipients in BCC. When you use 'Massive mail' the sending process will create few mails with a lot of recipients in Blind Carbon Copy (see Message Managment 8

9 section for details). With this parameter you can set the max number of recipients in BCC for a single mail. Default: 50. Really send mail? If you are evaluating JINC probably you do not need to really send mails. If you choose to not really send mails, the mail body will be written in the log file in <JOOMLA_ROOT>/administrator/components/com_jinc/jinc.log. Default: yes. Log level. You can choose several log levels. The most significative are 'Debug', 'Finer' and 'Info'. 'Debug' log level will print in log file every SQL query executed against SQL Server by JINC. You can find log file in <JOOMLA_ROOT>/administrator/components/com_jinc/jinc.log. Default: Info. Hints activation. During JINC administration some hints will be displayed. When you will be confident in using JINC you can disable them. Default: yes. 9

10 NEWSLETTER MANAGEMENT The starting point to understand the JINC administration is the definition of a newsletter. In this section you can find how to create and edit a newsletter. NEWSLETTERS LIST The list of defined newsletters can be accessed using the link 1 from the JINC main page or using the Component JINC Newsletter menù item. The next figure shows three newsletters loaded using the JINC 'Load Sample Data' tool. With JINC you can define three types of newsletters 1. Protected Newsletter: only registered Joomla! users can subscribe to the newsletter. Attention: this does not mean that every registered user is subscribed to, but only that every registered user can subscribe to. 2. Public Newsletter: also a guest can subscribe to it providing a valid address. The access to the provided address will be verified by an opt-in message. 3. Private Newsletter: only registered Joomla! users belonging to groups defined by JINC administrator can subscribe the newsletter. It is very similar to a protected newsletter, but it is accessible only by selected user groups. In the above example the 'News for every Joomla! users' is a protected newsletter accessible by every users logged to Joomla! and used by JINC administrators to potentially communite with every users. The 'Private news for elected people' is reserverd to users belonging to the 'Test group' and can be used by JINC administrator to send messages to selected people. The 'News for everyone!!' is a public newsletter to which every one can subscribe to, also without a registered account. 10

11 NEWSLETTER EDITING The data you must provide to define a newsletter depends on the newsletter type, but some information are common to every newsletter as Name. Type. This value is not editable after newsletter creation. Description. Sender information. You must choose a sender name and a sender address. They will be used also for Reply-to information. Default template. This template will be loaded every time you want to associate a message to the newsletter. See section dedicated to message management for more details. Welcome message information. This is the message to send to an user after subscription to the newsletter. It can contain info about the newsletter, the unsubscription link and other. Disclaimer. This text will be attached at the end of every newsletter message. Other data depends on newsletter type. For public newsletters you must define the opt-in messages information. If a guest want to subscribe to a public newsletter, he must provide a valid mail address and to complete the registration process he must confirm that he can access the provided mailbox by clicking a link contained in a message (called opt-in message) sent immediatly after subscription request. In a similar way the guest must confirm the mail address at unsubscription time throught a removal opt-in message. Next figure displays opt-in info for the public newsletter in our example For private newsletters the JINC administrator must provide one or more groups of users that can access the newsletter (otherwise no users will never subscribe to it!!!). Here is an example in which 11

12 only users belonging to 'Test Group' can subscribe to the newsletter. JINC 0.7 adds some newsletter property regarding the way the newsletter must be showed by frontend. It is possibile to choose the frontend theme, the number of messages to list and the way to show them. By default there are three available themes (ice, red, blue), but in order to develop and add a new theme you can see the Appendix A. Theme management. The administrator can choose to show a table listing the message subjects, with the possibility to have a link to the specific message, or the list of messages complete of bodies. If previously defined, you have also the possibility to assign to a newsletter addictional attribute the user must (or may) provide to subscribe the newsletter (i.e. surname, address, age ). For more details see the Appendix B. Addictional attributes management. NEWSLETTER PUBLISHING IN FRONTEND Once you defined a newsletter you must publish it in your Joomla! Frontend in order to allow user access and subscription. To do this you can create a menù item with a JINC Newsletter Layout to show newsletter information, older messages and the subscription form as in figure 12

13 In this way you will obtain a page similar to this one allowing the user to see information about the newsletter and to subscribe it. The newsletter information and the subscription form will be showed to anyone in case of public newsletter or only to authenticated and authorized users in case of protected or private newsletters. An alternative to allow guests or users to subscribe a newsletter is using the JINC Newsletter Subscription module (mod_jinc_subscription). This module show only the subscription form for a newsletter as in the next sample. Meanwhile if you need to list in frontend the newsletters available for a guest or a user, you can use the JINC Newsletter Access module which lists the newsletters a visitor can access depending on his access level. 13

14 14

15 MESSAGE MANAGEMENT Once you defined a newsletter you can associate messages to in order to send them to subscribers. MESSAGES LIST Using the link 2 from the JINC main page or the Component JINC Messages menù item you can access the list of defined messages, as showed in the next figure. The first message in our example (titled 'Hello everybody!!!') is related to the public newsletter and is a Bulk Message. With this kind of message the sending process will not send one mail for every subscribers, but few mails with a lot of recipients in Blind Carbon Copy (BCC.). The third message is related to the private newsletter and is a Personal Message. MESSAGE EDITING In our example the first message has been defined in such a way: 15

16 The previous figure displays the fields needed to define a message: Subject. Newsletter. This is the newsletter the message refer to. Body. Content type. The message can be send in plain text or HTML mode. Type. Personal or Bulk message. Attachment With the previous form you can load body and subject of the message from a predefined template, so you can avoid a noisy copy and paste process from a message to another every time you need to define a new message. This can be really useful when messages related to the same newsletter must have a common layout: in this case you can define a newsletter default template that will be automatically loaded when you associate a message to the newsletter. TAGS SUBSTITUTION JINC messages, included welcome messages and disclaimers, can contain special strings, called Tags, that will be substituted at message dispatch time. For an example the tag [NEWSLETTER] will be substituted with the name of the newsletter the message belongs. The tags availability depends on newsletter and message type: i.e. bulk messages and public newsletters can not contain tags as [USERNAME] and [USERID] because in those context users related info are not meaningful. During message definition near the body the message creator can find the list of available tags depending on the context he is working with. For example next figure shows available tags for a public and a private newsletter. 16

17 MESSAGE SENDING PROCESS Once you defined a message and associated it to a newsletter you are ready to mail it, but before sending the message to every subscribers you can produce a preview to be sure you obtained the expected result. To do this you can use the preview icon near the message subject in the message list context. Using this icon you will send the preview to the mail address of the user you are using for Joomla! administration. If you are satisfied with the result, you can send the message to the subscriber with the send icon (next to the preview icon) accessing the Newsletter sending process as in next figure The sending message task is splitted in subprocesses each executed in an AJAX step. Within each 17

18 subprocess JINC send n mails waiting s milliseconds between mails. Default values are s = 1000 (1 second) and n = 5, so a subprocess lasts about 5 seconds. At the end of a subprocess the progress bar and the last server response time in previous figure will be updated. In such a way if a newsletter has 1000 subscribers the sending process spend 1000 seconds to finish executing 200 AJAX steps. These parameters are editable using JINC preferences (see section 'JINC Global Configuration') and are vey important for two aspects: they avoid HTTP and network timeout caused by too long requests and the delivery of too many mails in a time unit. For these reasons you should choose their values very carefully. The sending process can be paused and stopped, and when finished historical information are registered and can be reviewed using the history icon in messages list. In such a way the administrator can recover the date a message has been sent and how many mails has been successfully delivered. Here is an example of historical data about a message sending: In the example the message has been sent twice in the same day. The first time to no subscribers, and the second time to 29 subscribers after subscriber import from CSV file. Important:when a sending process is in execution for a process, no other administrators can start to run it. Other administrators can only pause or stop the process: this will cause the pausing or stopping also for the first administrator who launched the process. This functionality can be important in case an administrator starts a process, but his browser was closed for some reason (i.e. brower cash) before the process has been correctly terminated: in this case the process appear to be running, but no messages is being sent actually. In this case another administrator (or the same one after re-login) can pause the process and restart again from the same point. 18

19 SUBSCRIBER MANAGEMENT Using the link 4 of the JINC Main Page you can access the subscribers list displayed in figure From here you can check if someone is subscribed to a newsletter and delete a subscription (without subscriber approvation and without any communication with him). SUBSCRIBERS IMPORT FROM CSV FILE If you already have the list of users interested in a newsletter subscription, you can import it from a Comma Separated Value (CSV) file. The format of the CSV file depends on the type of newsletter you are working with. For instance with public newsletters the CSV file simply contains a list of valid addresses, whereas with a protected newsletter every CSV line must contains info related to the users you are being subscribing to it. To access the tool to import subscribers you must use the import icon in the row related to the newsletter in the newsletter list context as you can see in the next figure Then you must upload the CSV file in the format explaind by the hint as displayed in next figure 19

20 In this example we are importing subscribers in a protected newsletter, so the CSV file must contain for every user the username, the name and the mail address of the user you are subscribing. If the Joomla! user does not yet exist the importer tool will try to create it with a random password. At the end the import process result will be showed as in the next figure. SUBSCRIPTION TO A PUBLIC NEWSLETTER A public newsletter can be subscribed by anyone providing a mail address. JINC subscription process validates the subscription request by an opt-in message containing a link to click in order to confirm the ownership of the provided mail address. In this section we will follow the subscription process to a public newsletter. First of all is necessary to create e a public newsletter and publish it somewhere in the Joomla! Frontend. At this point the newsletter is available for subscription: the unique data the guest must provide is a valid mail address, as you can see in figure: The subscription request will registered and an opt-in message will send to the user with this personalizable text including a random generated link the user must click in order to confirm the newsletter registration 20

21 We received your subscription request to our newsletter News for everyone!!. To complete the registration process you must confirm you are able to access the mail address clicking this confirmation link: option=com_jinc&controller=newsletter&task=confirm&news_id=1002&pub_random= Best Regards, The Staff. The JINC administrator can see in the list of subscribers a row like this with the subscriber in state 'Waiting click from opt-in' until the guest won't confirm his subscription. The guest will not receive any newsletter message until he will not click the confirmation link. SUBSCRIPTION TO A PROTECTED OR PRIVATE NEWSLETTER The subscription to a protected newsletter is a very simple process. A Joomla! logged user can subscribe the newsletter without providing any data, because his mail address has been checked at website registration. Just after newsletter subscription the user will receive a personalizable welcome message at his mail address. By default the welcome message is similar to this one: Dear Administrator, Your userid admin has been subscribed successfully to our newsletter News for every Joomla! users. Bye, the staff The subscription to a private newsletter is really similar, but the user can subscribe to the newsletter only if he belongs to a group allowed to access the newsletter. 21

22 AUTOSUBSCRIPTION AND JOOMLA! CONTACT INTEGRATION If you are working with private or protected newsletters you have two addictional functionality: the autosubscription and the Joomla! Contact integration. They are activable enabling the checkbox 'Newsletter subscription on user registration' and/or in newsletter editing as in figure With the first option a user will be subscribed to a protected newsletter just after his registration to Joomla! and he will receive the newsletter welcome message together the Joomla! address confirmation mail. In case of private newsletter the behaviour is a little bit different. The user won't be immediatly subscribed to the newsletter, but he will be inserted into the first group that can access the newsletter. In such a way he will have automatically access to the newsletter without any action by Joomla! Administrator. The Joomla! Contact integration allow the retrieving of user information from Joomla! Contacts while sending personal messages. In such a case the administrator have a list of addictional attribute editing a message such as [CON_NAME], [CON_ADDRESS], [CON_STATE] ecc that will be substituted during message sending with info retrived from Joomla! Contacts. 22

23 STATISTICS Every time someone subscribes or unsubscribes to a newsletter or an administrator sends a message JINC registers an event. Then JINC uses these events to generate statistics so the administrator can follow the trends of number of subscriptions and message sendings. To access the newsletter statistics you can use the related icon in newsletter list as in figure Using this icon you access the statistics page which can be used to show statistics about number of subscriptions, number of unsubscriptions and number of sent messages daily or hourly time based. Here is an example of statistics page regarding the sample newsletter News for every Joomla! Users. The performed chart shows the number of subscriptions within the last 8 days. Attention: to produce charts your PHP envirnment must have GD Support enabled and properly configured. 23

24 APPENDIX A. THEME MANAGEMENT JINC 0.7 adds the possibility to assign a frontend theme to a newsletter. A theme defines the graphical aspect of newsletter in Joomla! Frontend simply using a CSS file. JINC comes with three predefined and very simple themes: ice, red and blue. To define a new theme you must create a new css file in the directory <JOOMLA_PATH>/components/com_jinc/assets/themes/ following the example of one of the default theme and ridefining the CSS classes contained in it. The newsletter editing functionality will list as a theme every file in the target directory with.css extension. APPENDIX B. ADDICTIONAL ATTRIBUTE MANAGEMENT JINC 0.7 introduces the possibility to define addictional attributes for newsletter subscription. An attibute, in this context, is a value an user must provide to subscribe a newsletter. In case of public newsletter, for example, mail address and name are necessary attributes for subscription. The administrator can define addictional attributes and associate them to a newsletter as mandatory attribute (the subscriber must provide it) or optional attribute (the subscriber may provide). The addictional attibute definition functioanlity can be accessed from the newsletter listing page with the button 'Attributes' and accessing to the addictional attribute management tool as next figure. 24

25 An addictional attribute is defined by these parameters: 1. Attribute name: the name of the attribute used to refer to it around the JINC application. 2. Input name: the string used in the subscription form in Joomla! Frontend. For internationalizion purposes, this string can be translated in the JINC frontend language files (i.e.: <JOOMLA_PATH>/language/en-GB/en-GB.com_jinc.ini) 3. Tag name: the string describing the attribute during message editing for tag substitution purpose. This string must is not editable by administrator and must be translated in JINC backend language files (i.e.: <JOOMLA_PATH>/language/en-GB/en-GB.com_jinc.ini). 4. Input type: it can be Integer or String and is used to check input during user subscription request. 5. Description. The attribute description. Once defined, an attribute can be associated to one or more newsletter as a mandatory or optional attribute through the panel in the editing the newsletter page. The value of attribute associated to the newsletter will be request in the subscription form and the input value will be checked based on the attribute input type and his obligatoriness. For example, associating the attribute surname as mandatory and address as optional the subform request will appear like this and in message editor has the dispobility of the addictional tags [ATTR_ADDRESS] and [ATTR_SURNAME]. 25