Interacting With Your Audience

Obtaining Visitors Statistics

~ToDo: Write explanation for display_count...
~Hook: Slice -> Fields -> display_count...

Allowing (Anonymous) Visitors to Add Content

Setting up an anonymous form

Origin: ~ToDo: id=1777 How to create a form allowing anonymous posting from public website? rel:1702,1671,

Abstract

Explains the basic idea, creation and settings of Anonymous forms. The name "anonymous" is in some cases not accurate, as the form is used for reader personal info and the readers must be authorized to edit their own info.

~ToDo: Link to the reader management section
~ToDo: Link to the alerts section 

1. General usage of Anonymous Forms

Anonymous forms are similar in function and design to the Add / Edit item page. The main difference is they are placed outside of the AA Control Panel and thus do not provide the AA authorization and have a design of their own.

The most common usage is to allow web readers to suggest new content. After filling the Anonymous form it is sent to the Holding Bin and a Thank you page appears. But you can also allow readers to edit items with the Anonymous form.

2. Filler and fillform

Two scripts handle the anonymous forms. The first, filler.php3, stores the info coming from the form into the database. It also validates the data and prooves permissions to edit or update the item. The second, fillform.php3, refills the data into the form shown to the reader. It retrieves the data from database or in some special cases directly from filler.

3. Creating Anonymous Forms with the Wizard

In the previous AA versions until version 2.4, the process of creating Anonymous forms was very simple: Copy the code of the "Add item" page with only a few necessary changes. But as the form now allows to edit items and to use several options for it, a new wizard was created. This wizard creates the HTML code for a complete form with the SSI include of fillform.php3 necessary to edit items. The resulting form differs depending on whether Anonymous editing is allowed or not.

You may change these settings in the wizard or later in hidden fields:

Table 1. Wizard settings

err_url	The URL to which the script filler.php3 jumps when some error occurs. It may be the same page on which the form is shown.
ok_url	Like err_url, for successful changes.
show_result	The URL of a PHP script which receives the results from filler.php3. This allows for a completely free design of how the errors are presented to the user. Usage of that script is inevitable if you want to tell users why their subscription failed. While ok_url can be static html page, err_url should include call of the filler.php3 script with show_result parameter as described bellow.

4. Editing with anonymous forms

If you are interested to know more about what the form contains, here are some remarks:

• The fields shown in AA but not shown in the anonymous form are mentioned

in the notshown[v7377697463682e2e2e2e2e2e2e2e2e2e] hidden variables. This allows to set these fields to default values on posting and to store old values on updating.

• The setting use_post2shtml allows to use the POST

method for the form even though it is on a shtml page. See more info in the script post2shtml.php3.

If you want to edit items with anonymous forms, first you must allow to choose which item to edit. You can create a view and add a link to the headlines, which links to the anonymous form and contains the parameter

my_item_id=11a7cc0908d77c22bf2c7ca43cdd8480

Another approach is used in Reader management slices, see below.

You must choose the correct setting in Slice Admin - Settings - Allow anonymous editing of items, which is used by the filler.php3 script on an item update request. The options are:

Table 2. Anonymous editing options

Not allowed	Never allow to update items
All items	Always allow
Only items posted anonymously	For items posted anonymously, filler always sets the ITEM_FLAG_ANONYMOUS_EDITABLE flag. By choosing this option you allow only items with this flag set to be edited.
Only items posted anonymously and not edited in AA	Similar to the previous one, but when you edit the item in the control panel, the flag is cleared and thus the item is no more allowed to be edited anonymously.
Authorized by a password field	filler looks for a field of type Password (with Id beginning with password....) and requests the password sent by the user to match. The password may be set on item creation. If the field is not flagged required, an empty password may be used. The new Field Input Type, Field Insert Function and Field Validate Functions “Password and Change Password” provide the usual edit boxes for changing, deleting and entering password, which is stored encrypted. The disadvantage is the password must be sent on every update.
Readers, authorized by HTTP auth	This is a special option, useful only for Reader management slices. The username given to the browser on HTTP authentification is looked for in the database. Each reader may edit only his or her personal info.

5. Tips and tricks

• It is possible to send images and other files by the form (unlike the

anonymous posting in version prior 1.5)

• It is possible to set values to a non-displayed field by just adding a

hidden field for such a field:

<input type=hidden name="v696d675f6865696768742e2e2e2e2e2e" value="Anonymous author">

Note: This solution is easy and good working in many cases, but it is by no means secure. Any experienced user can change the values of the hidden fields so do not rely on such data. A better solution is to completely omit such fields from the input form and set the default values for the fields in

"Admin" -> "Main setting - Fields" -> "Edit" -> "Default"

The values are than set directly from the database. This solution is a little bit more secure.

• The inputs are validated as if they were typed in the standard itemedit.php3 form. When there are any invalid data, the

whole item is not updated. The javascript validation used in itemedit.php3 is also included in the form created by the wizard

• You can disable the standard AA validation by adding a hidden field

notvalidate in the form:

<input type=hidden name="notvalidate" value="1">

Be cautious when using two anonymous forms on one page. You must rename the form and the Javascript variables so that
they do not conflict with each other.

• If your form includes HTMLarea, you will need to include

<body onload="HTMLArea.init()"> 

in your form page.

6. Reader management specifics

Each reader has her or his own item in the Reader management slice. Thus the HTTP authentication described above may be used directly to determine which item (reader personal details) to show in the form.

In this case two forms are needed, one being the publicly accessible subscribe form and the second being the HTTP protected “Change personal details” form. Because the fields on both the forms may be the same, you can use one form and include it into two different .shtml pages.

For webs not using Auth we need a way to ensure nobody not only edits but even views the data. This is achieved by assigning a special “Access Code” (see the Reader management documentation) to each reader, which must be added to the URL in order that the data are prefilled. The password authorization described above is than used on item update.

7. Show results

Sending the data to AA results in adding the data into database or in an error. Some of the errors may be excluded in advance by Javascript validation (function proove_fields). But some of them, like a username being already used, can not.

By default, the fillform.php3 script shows standard error messages. They always appear at the place where fillform.php3 is SSI-included in your shtml page.

You may create your own PHP script (see an example in doc/script/show_result.php3) and send its URL as a value of a show_result variable. Add it as a parameter to the fillform.php3 SSI include created by the Wizard, e.g.

<!--#include virtual="/aaa/fillform.php3?show_result=http://ecn.cz/show_result.php3&form=..."-->

An array $result with the results will be sent to the PHP script and you may print appropriate messages, see the example.

You should probably use show_result parametr at the err_url page and at the page on which users can change their settings. Be aware that in the current version (as of July 2007) of APC-AA there is an option use PHP script in the wizard for anonymous forms. That option has probably no meaning. You have to change generated html code manually (add parameter show_result=...).

The $result array content is created at various places in filler.php3 array. Look there for accurate info. At this moment the messages are:

Table 3. Results from filler.php3

fatal	Fatal error. Several messages related to the slice, not to the particular item. These errors help on creating the web page.
validate	Array with not validated fields, field_id => message, e.g. headline........ => This username is already used created on field validation. You may create your own messages depending on the field_id.
permissions	Missing permissions. Depending on the setting for Anonymous editing (see above), this item did not fullfill the requirements.
store	Some error in StoreItem. Usually this points to an inner AA error.
success	No error. The operation was successfully done. The value is “insert” or “update” (i.e. $result["success"] == "insert" or $result["success"] == "update" in the show results script).
email_confirmed	Added by fillform.php3 on Reader management slices: When the reader successfully confirms his or her email by using the URL sent in an email, fillform adds a message “email_confirmed => OK”. This message is added only when the email has not yet been confirmed.
unsubscribed	Added by fillform.php3 on Reader management slices: When the reader unsubscribes from Alerts (which is achieved by setting How often to an empty value).

Discussion: A similar result may be achieved by adding several fields to the form, e.g. fields:

err_page[validate][username......]="err_username.shtml"
err_page[validate][*]="err_validate.shtml"
err_page[*]="err_unrecognized.shtml"

and by creating the .shtml pages with a static message concerning the particular error. The main advantage of this approach is the web administrator may not know PHP. The disadvantage is the necessity of creating many pages but using SSI includes the pages could look only like:

<!--#include file="err_top.shtml"-->
The username you entered has already been used. Please try another username.
<!--#include file="err_bottom.shtml"-->

Using anonymous form for editing existing content

Origin: ~ToDo: id=1724 How to edit items in public website? rel:1702,

You have prepared a public Anonymous_Form and want to use it to edit items as well. How to do it? There is a script fillform.php3 with associated JavaScript utilities in include/fillformutils.php3. This script takes the long item id from var my_item_id and calls JavaScript functions to look for the fields and fills them appropriately. You may use it this way:

file  anonymous.shtml:

<!--#include  virtual="/anonym_form.php3"-->
<!--#include  virtual="/anonym.html"-->
<!--#include  virtual="/apc-aa/fillform.php3"-->
<!--#include virtual="/bottom.html"-->
<!--#include  virtual="/anonym_bottom.php3"-->

Then you can call anonymous.shtml?my_item_id=... to show the edit form filled with old values.

There are two additional parameters which most users will not need: use "form = formname" when you changed the name of the form containing the fields (usually it is "f"). Use "notrun = 1" if you want to fill the controls e.g. only after clicking somewhere.

Only items posted by public website and not updated in the AA admin can be edited this way - a flag ITEM_FLAG_ANONYMOUS_EDITABLE cares about it. It is reset every time you send an item with itemedit.php3.

The same script may be used to refill conditions on a search page - see http://actionapps.org/faq/detail.shtml?x=1723

Notifications by email

Origin: ~ToDo: id=1716 Can apc-aa send email? What is the Email Notification control panel for? How do I notify someone of a new item, or an item in the holding bin? rel:2009

ActionApps can send email.

Go to the Admin -> Email Notification control Panel. There are four sections:

• New Item in Holding Bin
• Item Changed in Holding Bin
• New Item in Approved Bin
• Item Changed in Approved Bin

Each section has three fields

• Email addresses, one per line
• Subject of the Email message
• Body of the Email message

Each of these section configures how action apps will respond to an event. For example, if a new item arrives in the Holding Bin, apc-aa will send an email notification to everyone listed in the Email addresses field.

The Subject cannot use aliases (this should be fixed in a later version). The Body can use any aliases that you have defined for the slice, just as you use aliases in the Design control panels.

Allowing Visitors to Comment on Articles

Origin: ~ToDo: id=1746 How do I setup discussions? rel:821,278,218

FAQ: How do I setup discussions?

AA v2.0.0 supports discussions. The example, how the dicussions could look is on http://aa.ecn.cz/template/news.shtml?x=39124

Discussions are quite configurable (through views and aliases). Discussions can be easily managed in Item Manager - you can edit posted comments, Hide/Show them and Delete it.

Note, that each discussion is allways related to one item in slice.

There are some steps you have to do, if you want to add discussion to items, some of the steps depend on whether you are showing slices through slice.php3 or site.php3:

1. Switch to slice, where you want to have discussions
2. Go to 'Admin - Design Views'
3. Choose 'Discussion' in the listbox and click 'New'
4. The form for view editation should be filled with the default values (if not, you can use settings from the end of this e-mail)
5. Modify the 'HTML code of the form for posting comment' in order the form will be posted to right script:
   change the code:

   <form name=f method=post action="/apc-aa/filldisc.php3"...

   to point to directory, where your AA are installed (possibly: ...<form

   name=f method=post action="/aaa/filldisc.php3" ...)
6. if you want comments to be approved before displaying then add the code:

   <input type=hidden name=d_state value=1>

   after the <FORM> tag.
7. click on Insert to create the view
8. The code below assumes the view created is number 55

1. Go to 'Admin - Design Fulltext'
2. Select the created view in 'Show discussion' listbox
3. Now the discussions will be shown just after fulltext of item.

Integrate discussions into Full text View (for site module or in view.php3)

Open the view that shows the full-text, add for example:

{view.php3?vid=55&set[55]=sh_itm-{unpacked_id.....}}

Check in your site file (e.g. apc-aa/modules/site/sites/site_xxxx.php3) to see that the lines dealing with sh_item are not commented out e.g.

# Handle paging, takes from variable like scrl=24&scr_24_Go=3/

if( isset($scrl) ) { # page scroller
  $pagevar = "scr_".$scrl."_Go";

  $apc_state['p'] = $$pagevar;

}
if( ($apc_state["p"] <= 0) OR ($apc_state["p"]=='-') )
$apc_state["p"] = 1;

• Go to 'Admin - Design Item Manager'
• Change the 'Item format' using _#EDITDISC alias. For example you can add new column just like:

<td class=tabtxt><a href="_#EDITDISC">Edit</a>(_#D_APPCNT/_#D_ALLCNT)</td&gt

• Possibly change 'Top HTML' for header of item manager and click OK.

typically you want the number of comments, and a link to either View or Add Commends depending on whether there are any, code if called from site.php3 mightlook like....

<a href="?{relargs}&i=_#SITEM_ID({switch({disc_app........})0:&add_disc=1}#disc">{switch({disc_app........})0:Add::_#D_APPCNT}

Comments.</a>

Discussion design is defined in special view - 'Discussion' view. Following table shows aliases, which you can use for the design. Many of the aliases have also its own "field_id", which is presented in the second table column. The "field ids" you can use, if provided aliases do not fill your needs. If you want (for example) to modify date format, you can use

{alias:d_date..........:f_d:j. n. Y}

expression, instead of the _#DATE###_ alias.

_#SUBJECT_	d_subject.......	subject of the discussion comment
_#BODY###_	d_body..........	text of the discussion comment
_#AUTHOR#_	d_author........	written by
_#EMAIL##_	d_e_mail........	author's e-mail
_#WWW_URL_	d_url_address...	url address of author's www site
_#WWW_DESC	d_url_descript..	description of author's www site
_#DATE###_	d_date..........	publish date
_#IP_ADDR_	d_remote_addr...	IP address of author's computer
_#CHECKBOX		checkbox used for choosing discussion comment
_#TREEIMGS		images
_#DITEM_ID	d_item_id.......	comment ID (the same as _#ITEM_ID_)
_#ITEM_ID_	d_item_id.......	comment ID
_#DISC_ID_	d_id............	item ID
_#URL_BODY		link to text of the discussion comment
_#URLREPLY		link to a form
_#DISC_URL		link to discussion
_#BUTTONS_		buttons Show all, Show selected, Add new
	d_parent........	id of parent discussion comment
	d_state.........	state of this discussion comment (0 - visible, 1 - hidden)

~ToDo: Convert the example that used to be in faq no. ????

Tip 1: How to place the discussions at a specified place

Instead of selection of discussions view in 'Show discussion' listbox in 'Admin - Design Fulltext' can be beneficial to place the discussions to the 'Admin - Design Fulltext' by a simple alias such as: {view.php3?vid=1831}

It means that you can place the discussions where you need and, e.g. to show them only when it is allowed: {switch({switch..........})yes|on|true|1:{view.php3?vid=1831}}

Tip 2: New comment notification

(How to notify authors of the article and of the comments to the article about a new comment)

Basicaly: You need to create E-mail Template for the email, assign the template to the discussion view you are using. Then the e-mails will be send to the e-mail specified in the 'e_posted_by.....' field of commented article plus (optionaly) to all the people, who specified its e-mail when they wrote the comment and 'send_reaction' was true.

Steps:

• go to the slice, where you want to add the notification by e-mail
• go to Slice Admin / E-mail templates / Add Item
• fill the form - the most important field is "Text", see the example:

Author: <b>{d_author........}</b><br>
 Title: <b>{d_subject.......}</b><br>
 Text of the comment:<br>
 {d_body..........}<br><br>
 <b><a href="http://biom.cz/diskuse.shtml{d_url_fulltext..}">View the comment</a></b><br>
<b><a href="http://biom.cz/diskuse.shtml{d_url_reply.....}">Answer the comment</a></b><br>
<b><a href="http://biom.cz/diskuse.shtml{d_disc_url......}">View all the comments</a></b><br>

• go to Slice Admin / Design / Views and edit the discussion View
• fill the number of Email Template to the "E-mail template" field of the discussion view (the number of e-mail template from previous step)
• add to the field "HTML code of the form for posting comment" a new field "send_reaction" - it can be hidden (all authors will recieve the discussions) <input type="hidden" name="send_reactions" value="1"> or shown as a checkbox: <input type="checkbox" name="send_reactions" value="1">
• the authors of articles will recieve the comments by e-mail if their e-mail address is in the field "e_posted_by....." (you can add the field at Slice Admin / Fields)

Tip: You can fill the "e_posted_by....." field through "Default value" setting of that field, if you want to send all reactions to one e-mail address

Filter out SPAM in your forms

There are several methods, how to protect your discussions,... before a SPAM implemented in AA

• http links are not allowed for some discussion fields (like subject, author, ...)
• we filter out also the comments/items with high desity os urls in the comment body. It is based on the fact, that spammers obviously submits many urls, so there is allowed only limited count of links for each field. Four or less urls are always OK. More are allowed just for longer comments (1 link for 250 characters).
• You should also insert fake field into the form as described below

Fake field solution is based on the presumption, that the robots fill all the fields in the form, even the hidden ones. filler.php3 (and filldisc.php3) script then never stores comment, which would have "answer" field filled. So if you add say:

 <style type="text/css">
     .donotshow { display:none };
 </style>
 <div class="donotshow">
   Do not fill, please: <input type="text" name="answer" value="">
 </div>

to the form, then the comments form is "protected". It works quite well, but of course it should be improved in future.

Managing Subscribers

Origin: ~ToDo: id=1666 Is it possible to add new users from public website?

You can use ordinary Slice to store user data. There is a special slice type called Reader Management, which you should use as it adds certain functionality you may find useful.

Here is a list of features you can expect from the Reader Management:

• Easy to create online subscription form (via Anonymous Form Wizard)
• Optionaly you can require users to confirm their subscribtion by visiting a link send to them automatically in an email generated from a template
• Subscriptions can become live immediately or be held for further revision by the administrator (Active/Hold Bin)
• Flexible set of fields, so you can freely decide which information you need to hold about your subscribers
• Administrator can receive notifications about new subscriptions
• Bulk import of user data (csv)
• Bulk export of user data (csv, xml)
• Password protected directories (via apache auth_mysql module)
• Unlimited membership types (categories mapped to user groups for authentication)
• Automatic expiration of the accounts that have passed the expiry date
• Mass mailing (all subscribers or selection)
• Subscribers can subscribe to receive news by email (Alerts)

Additional features (not included but via existing external scripts):

• Lost password retrival
• Automatic reminder when approaching expiration date
• Cookie/php authentication

Allowing Visitors to Subscribe to News By Mail Service

~ToDo: Convert Jakub's Alerts documentation here

The documentation of this feature is a part of the AA code tarball. See it for example on Econnect installation.