APC Action Applications - Home Page

Frequently Asked Questions v2

 

Answers for: Slice Administrator

0. Password-protected public editing
1. How can I let users with the 'author' permission edit their own items?
2. How do I upload files into a slice
3. What is Reader Management?
4. Where is the HTML
5. 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?
6. How to use aliases
7. How do I control whether new items appear in the Approved or Holding bins
8. What are the 'Action Aplication Core' and 'News (EN) Template' slices?
9. How do I use add one of the fields in the drop-down at hte bottom of the Admin->Fields screen
10. Rich Text Editor
11. Jump module
12. Create new Wizard
13. How to show integers but not show 0?
14. What is the value of a check box input?
15. How to refill conditions on searchform?
16. Searchform extensions
17. How to setup searchform?
18. How to use images in a slice ?
19. How to display archive (expired items)?
20. How are mutual related links propogated?
21. AA Alerts
22. Alerts step by step walkthrough
23. Alerts Admin
24. two level menu view
25. Constants and Categories
26. What is the parent category?
27. How do I customise the Category breaks in an index view from another slice
28. Hierarchical constants
29. How to integrate APC-AA with email
30. How "No item found" message in view definition works?
31. Is there a way to allow different users to log in to the same slice but with their own language choice?
32. How can I include photos to the texts of articles?
33. MultiLingual eXtension for ActionApps / How to setup ActionApps for multilingual web sites
34. Which should I use, Item Listing View (View.php3) or Design-Index (slice.php3)?
35. What are Views good for?
36. How to display icon for Highlighted item on Item Manager (or public website)?
37. How do I create a Index of some items
38. How do I include this View in a HTML page?
39. How do I sort items within a View?
40. How do I include Previous and Next in the scroller of a View.
41. How do I select a sub-set of items from a view
42. How do I view just highlighted items on a page.
43. How do I make it view just a single item?
44. How do I link a Index view to show the items in a Full Text view
45. What is a Static View and how do I use it
46. How can I parameterize a view and fill in details from the URL
47. How can I change a piece of content on a page, for example a context-dependent Navigation menu
48. How can I use the related items feature to link items from one slice into another
49. How do I use a Javascript view to see pages on a site where AA is not installed
50. Which parameters can I use with view.php3
51. What are the wizards for parameter generation, and how do I use them
52. How to create a Calendar
53. Field Triggers
54. How do I automatically feed only select items to other slices?
55. How to set the off-line filling up?
56. How to edit items in public website?
57. How to create a form allowing anonymous posting from public website?
58. How to edit items non-anonymous from a website
59. How do I use jsview.php3 to view pages on a site where AA is not installed
60. How do feed items from one slice to another
61. How can I control which fields are fed, and whether they are editable
62. I want to feed highlighted items from several slices to the front page.
63. How to setup Cross server networking (CSN)
64. Feeding: How to access the id field in a parent
65. How can I set mapping on Manual feeding.
66. How to link parent item?
67. What are the different kinds of Views on the Admin->Views page?
68. Designing nice search results
69. Discussions as message boards
70. How do I setup discussions?
71. How to use Site Module
72. How to use Live checkbox (Auto Update Checkbox)?
73. How can I manipulate images (e.g. create thumbnails)
74. How do I create an RSS feed from a slice
75. What are the Parameters of the Alias Functions
76. Which parameters can I use with slice.php3
77. Cron - how to automatically run tasks on given time?
78. Where can I read about developing APC-AA applications
79. Which strings exactly are removed from Views?
80. How do I get rid of the "?" by each input field
81. Rich Text Editor icons
82. Field Types and Alias Functions
83. Protecting sensitive data against reading
84. Is it possible to add new users from public website?
85. How do I link to fulltext if, and only if, there is some fulltext
86. File Manager
87. How do I set mapping on RSS import
88. What paramater substitution is done in f_v

Items posted from a public website may be protected by a password. Suppose you have a field with ID "password.......x" (just like password.......1) in your slice and this field is visible on the public posting page. The user fills in the password when creating a new item. When using the script fillform to edit a public posted item on public pages, the password is not re-filled (all other fields are). But the script filler.php3 does not store the changes if the user does not refill the password correctly.

The scripts recognize the password field by ID "password.......x" - you can add such field in standard way on "Slice Admin" -> "Fields" page - derived from "Password" field template (the Reader Management slices already have such field in its default configuration). The 'posted_by......' field must be recorded for each submitted item.
So, it should be a required field in 'Admin->Fields' . It does not have to
be 'Shown', just 'Required'.

If this is done, only items that a user has permission to edit will be visible in the item manager for them.

First, your System Administrator has to setup the apc-aa, see below

Then edit one of the fields, e.g. SliceAdmin-Fields-ImageURL-Edit

Set the type to "File upload" and use the Wizard to set the file type to for example image/* or */*

Set the Validate/Insert field to "File"

The field will then show up with a pair of fields, one where a URL can be entered, and the other where a file can be chosen. You may wish to take care on picking the help text for these fields as it can be confusing to figure out whether to fill out both fields or just one.

Reader Management is a special kind of slice that is designed to contain data about subscribed "readers" (aka public web site users). A Reader Management slice can be used to send automated email alerts of new AA items, personalize page views, send bulk target emails, and generally act as a contact database. Anonymous forms can be set-up to allow users to change their subscriptions and contact data in the Reader slice.

The HTML for a typical APC-AA site can come from many places which can confuse people used to doing all their HTML in a single place.

Location What to put there
.shtml file static HTML that doesn't repeat, and is not changed often. Can be edited with any standard web editor by someone who has write permissions on the web server. The HTML has lines like <!--#include "/apc-aa/view.php3 --> (or apc-aa/slice.php3) to include a PHP file which will fetch information from the Slice's design.
Design section of the Slice This is used to list a range of items in a slice, or display a single item. Someone with Admin permission on the slice can go to apc-aa/admin -> Admin -> Views or apc-aa/admin -> Admin -> Display/Index or Display/Fulltext. HTML can be placed here associated with the top and bottom of a listing, with each item, and with groupings of items. The HTML includes alias such as _#HEADLINE
Aliases such as _#HEADLINE Each alias defines how to show a particular field, it does this by choosing a function (e.g. f_h) and parameters. For example _#HEADLINE is usually just output, while a Link might be output surrounded by <a href=" and ">. They can be edited by anyone with administrator priviliges on your slice by going to Admin->Fields->choose field ->Edit. A field can have several different ways of being output, for example a date could have aliases for both short (1/1/200) and long (1 January 2000) forms of output.
Functions such as f_h These define functions certain common ways fields are output. They are defined in the PHP code, and so have to be edited by developers, except that there is an extension function f_u that calls functions from apc-aa/include/usr_aliasfnc.php3, these can be written by anyone who understands PHP3.
Data Lastly of course, the HTML could be in specific fields in your data.

Exceptions:

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.

NOTE: a bug was fixed in the sourcecode on Jan 18, 2002, so
if you get errors, you might upgrade your apc-aa version to
the most recent version.

The output generated by AA is controlled by aliases. The aliases are 10 letters long words defined on 'Admin' -> 'Fields' -> 'Edit' page. Aliases are obviously expanded to the content of some database field or its modification (like How to use aliases alias). For modification of behavior of the alias we use alias functions, as described on
http://apc-aa.sourceforge.net/faq/#216.
http://apc-aa.sourceforge.net/faq/#291.

Since the AA version 2.1 there is possibility to use the aliases NESTED, which means that you can use another alias in the alias definition. For example this Parameters to f_c alias functions are possible:

!:<img src=":" _#PHOTO_WI _#PHOTO_HE alt="photo">::

which displays image (if it is defined). The aliases _#PHOTO_WI _#PHOTO_HE must be defined, of course.

You can use there not only the aliases, but it is possible to use any of database field directly there. Imagine, we store type of record in switch.........1 field (for example text/audio/video). If we create three images - icon_text.gif, icon_audio.gif, icon_video.gif, we can add an icon before each link by the following Parameters to f_m alias function:

<img src="img/icon_{switch.........1}.gif" width="14"> :text...........1::href:class="green10"

The AA version 2.2-pre (04/25/2002) give you new possibilities in alias definition - IN-LINE ALIAS DEFINITION. The parsing of format strings was rewritten, so now you can define aliases not only on 'Admin' -> 'Fields' -> 'Edit' page, but you can define it directly inside the format string (= 'Fulltext HTML code' on 'Design' -> 'Fulltext' page, for example). The new features are 100% backward compatible.

The alias definitions are surrounded by curly braces. There are the possibilities:

  1. direct display of some field

    ... there is displayed headline: {headline........} <br> Source: ...

  2. constant display

    Constants are stored in database as values, but it is possible to convert value back to name, description, ...
    The syntax is : {const_name:category.......1}, {const_description:category.......1}, which displays name (description) of constant stored in field category.......1.
    You can grab following information for the constants:
    const_short_idshort_id
    const_name name
    const_value value (the same as {category.......1} )
    const_pri priority number
    const_group name of constant group
    const_class class (APC parent category)
    const_id long constant id
    const_descriptiondescription (defined on hierarchy editor pages)


  3. display of multivalue fields

    ... fields in AA could contain multiple values (categories, ...). It is possible to diesplay it: The example is directly in Item Manager of 'Test News' slice. The syntax is:
    {@category.......1} displays list of 'values' - comma separated (comma is default)
    {@category.......1:-} displays list of 'values' - dash separated
    (it is usefull for example in display of related items: {view.php3?vid=11&cmd[11]=x-11-{@relation.......1:-}}
    {@category.......1:,:<b>_#1</b>} displays list of 'values' in bold - comma separated (_#1 is alias for the values)
    {@category.......1:,:<a href="/category.shtm?conds[0][category.......1]=_#1">_#1</a>} displays list of categories with link to the each category
    {@category.......1(const_name,const_value,const_short_id):,:<a href="/category.shtm?conds[0][category.......1]=_#2">_#3 _#1</a>} displays list of categories with link to the each category, but the text shows category name (and short_id) instead of value.
    You can use as many constant translations as you want in the parethes. See 'constant display' for list of possible values in previous paragraph.


  4. direct display of a variable defined with als or in $apc_state:

    ...view.php3?vid=123&als[heading]=My Page

    and then ... <h1>{heading}</h1>


    The same syntax will find variables defined in apc_state (by the site module).

  5. modification through alias functions:

    ... The previous example is good, but sometimes we need to modify the database field before it is displayed. For example the date field is displayed as number if seconds since begin of year 1970, which is probably not exactly what we want to show to user. The solution is to use alias function modification, which has the following syntax:

    alias:<the field>:<alias function>:<parameters>

    So, in text (format string) could be the publish date displayed by {alias:publish_date....:f_d:j.n.Y}. There you can use any alias function with any parameters.

    The parameters could be nested, so inside curly braces you can use any alias (How to use aliases), any other field ({headline........}) or any other in-line alias definition. There is no limit in level of nesting.

    For example, conditional display of date could look:

    {alias:switch.........1:f_c:text:{alias:publish_date....:f_d:j.n.Y}<!--:-->::}

    or if we have 06/19/2002 alias defined:

    {alias:switch.........1:f_c:text:06/19/2002<!--:-->::}

    Both this constructs displays date only if switch.........1 is equal to 'text'. ...

  6. comments

    ... as addition to in-line aliases you can {# make comments} which is not displayed in result html code. It could be nested again, so you can {# comment out _#ALIASES_ as well as fields {headline........} or alias definitions } - nothing will be in result HTML code ...

  7. switch

    ... the really new and very useful construct is switch. Many of us knows the troubles with conditional expressions, managed so far by f_c function. Now there is much better solution, which allows more options, regular expressions, ... The syntax is:

    {switch(<condition>)<option1>:<output1>:<option2>:<output2>:...[:<default_output>]}

    which we can explain on example:

    {switch({number.........1})1:one:2:two:[3-7]:more:too much}.

    This construct evaluates the condition, which is the content of the number.........1 field in our case. If content of the field is equal to 1, the 'one' is printed. Because 'options' are regular expression, we can specify the third option as [3-7] which means any number in range between 2 and 7. The default option is 'too much' in our case. The evaluation of options goes from left to right and the output is printed only for the first matching option.

    The 'switch' could be used instead of f_c alias function in many cases:

    {switch({switch.........1})text:06/19/2002}

    This expression could replace the expression in the paragraph 2)

    Another example displays text 'Continuos grant', if the field unspecified....2 is filled by 'yes', 'on', 'true' or '1'. Else it displays expiry date:

    {switch({unspecified....2})yes|on|true|1:Continuos grant::12/11/2007}

    Display of phone number, if specified (as obvious, '#:' stands for ':' if you do not want to use it as argument separator:

    {switch({con_phone......1}).+:Tel#:{con_phone......1}}

    Last example demonstrates the fact, that there is no limit in <condition>. There could be not only field (in curly braces), but there could be also any alias, alias definition or its combination. The level of nesting of 'curly braces expressions' is again unlimited.

    {switch({1})[1-9][0-9]*:There is discussion under this item}

  8. Inclusion of a view
    {view.php3?vid=123}

    Returns content of view 123. View uses the just like the view.php3 script, and can nest other {} structures. (e.g. {view.php3?vid=122&cmd[122]=c-1-{f}} ) Very useful for displaying related items e.g. {view.php3?vid=33&cmd[33]=x-33-{relation.......1}}

  9. includes (added 06/20/2002 - will be in AA v2.2.1)

    ... Sometimes we need to include some file or output of some script into the page. Now, there is {include(<file>)}, which will be replaced by the file. The file is called through HTTP request. No matter if included file is html, shtml, php, ...:

    the page was visited {include(cgi/counter.pl?id=222)}

    (the result of http://www.example.com/cgi/counter.pl?id=222 will be printed)

    APC news: {include(http://apc.org/apps/aa/view.php3?vid=112)}

    (the remote view (from APC site) will be printed)

    If you want to include other slices, it could be usefull to pass the URL parameters to the included file. In this case use the special URL_PARAMETERS constant:

    {include(fulltext.shtml?URL_PARAMETERS)}

    The limits:

    This can be used in an alternative syntax {include:<file>} or {include:<file>:http} which work exactly the same or {include:<file>:fileman} which will try and read the file directly from the Fileman directory for the slice being used. (this code is new 23 may 2003 and the definition of which slice is being used might change)

  10. mathematics operations (new in AA v2.4.0)

    ... If you want to compute some walue from datadase field, use the {math..} alias. The syntax is ...:

    {math(result_formatting) description1: expression 1: description2: expression2:...:description x : expression x }

    where:
    result_formatting has 3 parameters separated by '#' (number of decimals # decimals separator # thousands separator)
    descriptioncan be any text or html and is displayed before result of expression ("#:" mean ":")
    expressionin expression can be used numbers (decimal separator is ".". Aliases can be used of course) and characters: + - / * ^ . ( )

    example 1 - use in inquiry

    
    <img src="red.gif"   height=10 width="{math(0#,#) : {_#ANSVER1_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER1_ <br>
    <img src="blue.gif"  height=10 width="{math(0#,#) : {_#ANSVER2_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER2_ <br>
    <img src="green.gif" height=10 width="{math(0#,#) : {_#ANSVER3_} / ({_#ANSVER1_} + {_#ANSVER2_} + {_#ANSVER3_})* 100}%">  _#ANSVER3_ <br>
    
    
    if _#ANSVER1 = 25, _#ANSVER2 = 50, _#ANSVER3 = 250 result will be:
    
    
    <img src="red.gif" height=10 width="8%">  25   <br>
    <img src="blue.gif" height=10 width="15%">  50   <br>
    <img src="green.gif" height=10 width="77%">  250   <br>
    
    

    example 2 - cost of ordered services last year
    
    {math(2#,# ) <br>mails=:{_#NOOFEMAI}*{_#EMAPRICE}:
                 <br>web=:{_#WWWPRICE}:
                 <br>technical support=:{_#NOOFHOUR}*{_#HOURPRIC}:
    <br><hr>total={_#NOOFEMAI}*{_#EMAPRICE}+{_#WWWPRICE}+{_#NOOFHOUR}*{_#HOURPRIC}
    }
    
    
    result:
    
    mails=450,00
    web=1500,00
    technical support=2400,00
    ----------------------------
    total=4350,00
    

  11. user informations (new in AA v2.6 (CVS 05/19/2003))

    In AA v2.6 is new Reader Management, where you can control access to directory or file through AA admin interface (see Reader Management). You can then display informations about logged user by {user:} construct.
    The syntax is following:
    {user:} displays login of current user
    (this option do not search in database, so it is quick)
    You can use this parameter even if you do not use Reader Management slice and you are using standard Apache's password file auth ...
    {user:password} displays password of current user (in plain text)
    (this option also do not looks into database, but into internal server variable, so it is also quick)
    {user:headline........} displays headline........ field for current user, which is grabbed from Reader Management slice. There is no need to specify in which Reader Management slice user is, because all users are unique in all Reader Management slices.
    If the Reader Management slice is protected by password (see 'Slice Admin' -> 'Slice' -> 'Password for Reading'), you have to add slice_pwd parameter to view.php3 (or slice.php3), in which you want to display user's database info.
    You can of course display any field from Reader Management slice.
    {user:role} displays user's permission role (author/editor/administrator/super/undefined)
    (usefull in AA admin interface when you want to display another informations to authors and editors - use it in switch() - like {switch({user:role})editor:_#POSTED_BY} )

    Such construct you can use in any view or slice - just like any other aliases.

  12. page scroller (for site module only)

    ... If you want to use page scroller (Page 1 | 2 | 3 | ... ) in view , which is part of 'site'! (see site module), the {scroller} syntax construct is the right tool. You just add {scorller} to the view, there you want to usepage scroller - probably in the 'Bottom HTML' fileld of the view:

    {scroller:Page ::class="blue"}

    The syntax for {scroller} is:


    {scroller:begin:end:add:nopage}

    where:
    begin text to be shown before page numbers
    endtext to be shown after page numbers
    addoption to be added to page number
    <a href=".." class="blue10v">1</a>
    nopagetext to be shown wnen there are (yet) no pages (so the scroller is not displayed)

    Then you use quite normal view include using {p} state variable, which stores the page number in the site module's spot:

    {view.php3?vid=32&set[]=page-{p},listlen-10}

  13. Debugging

    Because it is sometimes unclear which substitutions are available at a certain point, {debug} will output some hopefully useful information

The state of the item is controlled by the field status_code....., which is quite normal AA field.

You can define default value for any field in slice now

Go to: Admin - Fields - Edit (status code) - Default.

The states are:

  1. approved
  2. holding bin
  3. trash bin

So, change the default value for the status_code..... field to 2 and the items will be posted directly into holding bin.

It is possible to display this field in inputform (possibly as selectbox), so the editors could be able to decide, where the item should go).

There are two (and should be more in the future) odd slices in slice listbox. Why?

Both - the 'Action Aplication Core' and 'News (EN) Template' are only visible to superadmins and both should not have any items.

News (EN) Template

The 'News (EN) Template' slice is just a template for creating new slices. This template is shown as an option in "Admin" -> "Add Slice" dialog in templates listbox. If you feel a setting for the new created slices is not optimal you have two possibilities:

Action Aplication Core

'Action Aplication Core' slice is something another. In this slice there are defined the default values for each field type. These values are used when you add some new field to a slice on the "Admin" -> "Main settins - Field" page. Fill the field name, priority and field type. After you have clicked on update, the new field is added to the database for the slice and the values (like validate function, alias, help text, ...) are copied from the same field in the 'Action Aplication Core' slice. It is a good idea to translate the help texts in the 'Action Aplication Core' slice too when you are translating the whole ActionApps to some other language.

(This is confusing, and hopefully will get changed in a later version)

To add a new field, give it a text in the left hand box. And select which field to use (don't use one that you are already using in the list above), this will setup default display and things like this.

Click update, then click Edit next to this new field (which should now appear somewhere in the list). You can change many of the details, and will almost certainly want to set "Help for this field" to something to appear in the Add_Item function, and the first field of Alias_1 to a string you will use when defining Index, Full-Text or Views. To use the Rich Text Editor choose the Field Type "Rich Edit Text Area". It is a powerful editor allowing to work WYSIWYG. Currently it is running on Windows only. For more details see the Wizard with help near the Field Type select box.

Jump is a simple module with simple behavior. It jumps inside the AA control panel onto a page to which you otherwise need to go over several links. For example if you often edit a particular constants group (e.g. "Country"), you must use "Slice Admin" / "Fields" / "Edit" / "Edit".

Better possibility: create a Jump module on the AA Admin page and give
admin/se_constant.php3?group_id=Country
as URL and a name you like. The module name will appear in the select box within slices names.

The wizard is available to AA Administrators only. It enables to

The wizard is closely related to the File Manager, which contains additional features.

The user is created immediately after clicking on "Add Slice". The next page with slice settings shows whether there was some error or the user was successfully added. If you don't fill any user information, she/he is not added. You can return to the wizard page by Back and try it again.

Only after successfully filling all the slice information (the same process as with the usual Create New Slice) the views and constants are copied and (optionally) the new user is assigned privileges to the slice.

The Email Welcome select box is filled from the wizard_welcome table. You can use these aliases in the "email", "subject", "from" fields:

A copy of the welcome mail message is sent to the administrator's address (_#ME_MAIL_), so that she/he may see the process went on successfully.

Edit the welcome messages on the "Wizard Welcomes" AA admin page. An example is:

description Generic Item Manager Welcome
email Welcome, you have been assigned an _#ROLE____ for the slice _#SLICNAME. Your username is _#LOGIN___. See http://apc-aa.sf.net/faq for help on AA.
subject Welcome, AA _#ROLE____
mail_from "_#ME_NAME_" <_#ME_MAIL_>

The new constant group names are found by trying to add "_1", "_2", "_3", ... at the end of the group name until a group with such name does not exist.

The code used by the Wizard is shared with the Add Slice, Add User and Pemissions/Assign scripts, so you can expect the same behavior and AA developers may easily maintain it..

In this example, we are trying to only show alias for page numbers (_#NM_PAGES) when it is greater than zero.

The field input has Validate: Number, so it generates a zero when left blank. To not show the alias and label when zero, use:

{switch({_#NM_PAGES})^0:: _#NM_PAGES pages }

This switch will show nothing when the number starts with 0, otherwise it will show e.g. "15 pages". Since number validation removes preceeding zeros e.g. 0020, this should always work.

It depends on Fields - Edit -> Insert' setting. If you set it to 'Text', then the value is stored exactly, how it is send by form checkbox (which means 'on' or nothing). However, default and suggested setting is 'Boolean', which means '0' or '1' is inserted.

The script fillform.php3 allows to easily refill condition variables as well.

If you have some search form using the conds[] array, you may call fillform.php3?fillConds= 1 to create JavaScript, which will automaticallyrefill the condition input fields. You may use it by SSI, e.g.

<!--#include virtual="/aaa/fillform.php3?form=formname&fillConds=1"-->

Place it after the HTML code for the search form, otherwise it will only make a JavaScript error. Replace "formname " with the name of the form containing input fields.

The script can refill multiple select boxes like
<select name="conds[0][value][]" multiple>
as well. Don't forget the [] after [value].

Don't use quotes around field IDs, otherwise some values will not refill (e.g. checkbox <INPUT TYPE="checkbox" NAME="conds[1][highlighted.....]"> must not be 'highlighted.....').

There are special dateConds[] parameters which I use to refill AA-like dates (three selectboxes for day, month and year), but this is a bit difficult. If you are interested, write me and I will explain.

How to search in multiple slices

The searchform may be extended to seach for items in several slices at once. This is done by adding the slices[] parameter, e.g.

<input type=hidden name="slices[0]" value="517d65d9936c98a1537a5fecbddc7d42"> <!-- news -->
<input type=hidden name="slices[1]" value="849d65d9936c98a1537a5fecbddc7d52"> <!-- events -->

The comments <!-- news --> are useful because you perhaps don't remember, which slice has which id (value="slice_id").

All other settings remain the same as in the usual searchform. The only difficulty is that sometimes the field ids do exist in some slice and do not exist in another one. Than you must rename the fields (menu Slice Admin --- Change field IDs).

To view the items found, you must set the same aliases (Searchform extensions etc.) in all the slices searched through. Each item will be shown using the aliases of the slice to which it belongs.

Tip: If you want to show checkboxes to choose in which slices to search, use something like

<input type=checkbox name="slices[0]" value="517d65d9936c98a1537a5fecbddc7d42" checked> News
<input type=checkbox name="slices[1]" value="849d65d9936c98a1537a5fecbddc7d52" checked> Events

How to search in discussion items

The discussions are not stored in the same database tables as other item content. You may use the conds[discussion][] parameters, e.g.

<input type=hidden name="conds[0][discussion][subject]" value="1">
<input type=hidden name="conds[0][discussion][body]" value="1">

Specify the discussion fields in which to search: you may use this fields --- date, subject, author, e_mail, body, state, flag, url_address,
url_description, remote_addr, free1
or free2. The other fields (conds[0][operator], conds[0][value] etc.) remain the same as usual.

To view the discussion items found include aa/discussion.php3 by SSI. You must pass a view ID of some discussion view to the script, e.g. when the view ID is 22:

<!--#include virtual="/aa/discussion.php3?vid=22"-->

The top HTML code, index view code and bottom HTML code are used to create a listing of the items found, nothing other.

How to use hierarchical constants in searchform

To show hierarchical constants like in the AA control panel Edit item, use the aa/hiercons.php3 script. You must send the following to the script:

The SSI include for a hierarchical constant group "Keywords" may look like

<!--#include virtual="/aa/hiercons.php3?varname=conds[1][value]&param=Keywords:3:60:5:0:1&lang_file=cz_news_lang.php3"-->

Warning: constants in the multiple select box must be selected, otherwise they are not send to the server. Do this by JavaScript.

One benefit: fillform.php3 knows how to refill multiple select boxes as well.

The keywords selected by the user will be joined by OR or AND, that means any keyword or all keywords must be present in an item. You must specify the operator by conds[1][valuejoin], e.g.

<input type=hidden name="conds[1][valuejoin]" value="OR">

Tip: If you want to show a select box to choose whether the keywords should be joined by OR or AND, use something like

<select name="conds[1][valuejoin]">
<option value="OR">Find items with ANY keyword
<option value="AND">Find items with ALL keywords
</select>

How to use a multiple select box

If you want the user chooses keywords from a multiple select box, use the similar settings as in hierarchical constants: set the name of the select box to [value][], e.g.

<select name="conds[1][value][]" multiple>

and add the [valuejoin] field (see above).

It is possible to create searchform manually in HTML. There is no possibility to create it automaticaly as it is known from AA v1.2., yet. Special possibilities for searching in multiple slice at once, searching in discussions, choosing keywords from hierarchical constants and using a multiple select box are described at other places in this FAQ.

Form example:

 
<form action="index.shtml" method="get" name="sf" id="sf">
  Search Author:   <input type="text" name="conds[0][created_by......]"><br>
  Search in Headline and Fulltext:  <input type="text" name="conds[1][value]">
                                    <input type="hidden" name="conds[1][operator]" value="LIKE">
                                    <input type="hidden" name="conds[1][headline........]" value="1">
                                    <input type="hidden" name="conds[1][full_text.......]" value="1">
  <br>
  <input type="hidden" name="sort[0][headline........]" value="a">
  <input type="submit" value="Search" >
</form> 
Let's notice:

conds --- simplified syntax

The simplified syntax is <input type="text" name="conds[i][field_id]"> (see conds[0][created_by......] in the example). It is easy and good, if you want to

conds --- extended syntax

The extended syntax sets an [operator], [value] and one or more [field_id] for each condition. See conds[1] in the example.

[value]

Contains the search phrase (like conds[1][value]="Prague"). Usually this is the only visible text box (<input type="text" name="conds[1][value]">). The search phrase may be a boolean expression, but you don"t need to think about it if you are using the standard LIKE [operator].

The phrase may contain ANDs, ORs, parenthesis ({[]}) and NOT. When the user gives apple OR cherry, she will get all items containing any or both of the two in any of the fields specified by [field_id] (see further).

Spaces are considered as AND:

Prague Spring becomes Prague AND Spring

With the standard LIKE operator this works fine: it finds all items containing both Prague and Spring at any place (not necessarily Prague space Spring).

Hyphen is considered as AND NOT if not between two letters:

North-West remains as it is, but
North -West
becomes North AND NOT West because of the space on the left of the hyphen

To avoid this behavior, use quotes or single quotes:

"Prague Spring" or "North -West"

[operator]

If you don't specify it, the default operator is LIKE. You can change the default by using the defaultCondsOperator parameter (e.g. defaultCondsOperator=RLIKE). Other posibilities are:

Operator Description
= equals (or "e:=" with modifiers)
<> not equals
< less than
> more than
<= less or equals
>= more or equals
BETWEEN in interval: the [value] must contain two numerical values, comma separated
LIKE substring search (SQL: LIKE "%phrase%")
RLIKE substring which begins with phrase (SQL: LIKE "phrase%")
LLIKE substring which ends with phrase (SQL: LIKE "%phrase")
XLIKE string (SQL: LIKE "phrase")
ISNULL not set (good for boolean values - like values from checkbox)
NOTNULL is set (the field must be filled - no match for NULL or epmty string '')

date modifiers

Date values are stored in the database as UNIX timestamps (no. of seconds since 1.1.1970). You can use modifiers to convert it from human format. The modificators are written before a comparison operator separated by colon (like "d:>="). The possibilities are:

Operator modificator Example Description
d d:>= Used for english style datum transformation. If used, the "value" can be in format like "06/24/2001" or "10 September 2000" see strtotime PHP function definition
e e:>= Used for european style datum transformation. If used, the "value" can be in format like "24.12.2001"
m m:>= Used for comparison with current time. If used, the "value" is substracted from current time (time()) and result value is used in comparison. The value should be in seconds. This modifier is good for displaying items newer than two days, for example.

[field_id]

Specify the fields to be searched through by their IDs.

sort

Specify the sort order by the sort[] form fields. For example:

<input type="hidden" name="sort[0][headline........]" value="a">
<input type="hidden" name="sort[1][full_text.......]" value="d">

The value is "a" for ascending and "d" for descending order. The items are sorted first by sort[0], second by sort[1] etc.
If no sort[] variable is defined, items are sorted by Publish date - descending.

It is possible to sort items not only by the value, but there is possibility to sort by 'priority' for the fields which uses 'constants' (Slice Admin -> Fields -Edit -> Constants) - like category field:

<input type="hidden" name="sort[0][category........]" value="1">
<input type="hidden" name="sort[1][unspecified.....]" value="9">

The value is "1" for ascending sorting by priority and "9" for descending order.

See another example on the APC Demo Site, where publish date field is used.

Using this method, you can, in the "add item" form, use an image from an existing URL or upload an image to use it.

1) in the ActionApps main menu, choose "Slice Admin" option
2) In the list of fields, there will be a field called "Image URL"
3) Edit the properties of the field...
a. Change input type to "File Upload"
b. Edit the parameter to "image/*"
c. Set Validate to "URL"
d. Set Insert to "File"

4) Now, you can use the alias _#IMAGESRC like :
<IMG SRC="_#IMAGESRC">

Expired items are normaly not visible on the public website. However is it usefull to sometimes show expired items such as for archives.

There are two easy steps to show expired items in a view:

  1. Make sure display of expired items is permitted by setting ALLOW_DISPLAY_EXPIRED_ITEMS constant to true in config.php3
  2. Define a condition where 'expiry_date.....' is specified. You can use a condition fields in a view design or a search condition or a condition in an URL or SSi using cmd[]-c or cmd[]-d see parameters to view.php3

Example of condition fields in a view design:

set Condition 1 'expirary date' < 9999999999999
(this is a unix date in far far far future - you'll be dead :^)

Example of view.php3 parameter:
.../view.php3?vid=23&cmd[23]=d-expiry_date.....-e:>-1.1.1998



When you update an item that includes a mutual related link it will update the matching relation field ID in the related slice. Make sure both slices are using the exact same ID and that the input Insert is set to "Item IDs". THIS ITEM IS COMPLETELY DEPRECATED. A COMPLETELY NEW ALERTS DESIGN IS DESCRIBED IN THE NEW DOCUMENTATION. ALSO SEE READER MANAGEMENT DOCUMENTION AND DEMOS FOR USEFUL ALERTS DEMOS AND TUTORIALS

Related FAQ items:

AA Alerts are designed to deliver new AA items to users by e-mail. Slice Administrators choose the design and which kind of items from which slices to include, creating Collections. Users subscribe for Collections and receive them optionally once a day, week or month.

A user interface allows users to change their subscriptions. Users are identified by e-mail and they must confirm their e-mail address by a confirmation code received by e-mail to make sure the address is working.

The admin interface allows AA admins to define new Collections, list users subscribed to Collections and list Collections subscribed by users.

Collections

Collections are created by Slice Administrators on the page Slice Admin / Alerts / Collections. They are based on Filters, which are defined in the Digest type of Views.

A Collection is an ordered list of Filters. Each Filter is associated with one Digest and filters items to be sent by using the search form conds[] and sort[]. Digests are views suiting Alerts needs (see below).

You may define Editorial for each Collection, which will be printed before Digests' texts. In the Editorial you can use these aliases:

Digests and Filters

Note: You create filters by typing their DESCRIPTION. You must type at least one description before you can create Collections.

Each view of type Alerts Digest has a set of Filters definitions. Create filters by typing their description. If you want to include all items in the filter, don't fill anything into the "conds[]" field. Otherwise you may fill any conds[] and sort[] definition in the URL shape, e.g.

conds[0][headline........]="human rights"&conds[1][fulltext........]=Bosna

is a filter sorting out items with "human rights" in headline and "Bosna" in fulltext. If you want to order the filtered items, use sort[] (see How to setup searchform in FAQ for details on conds[] and sort[]).

If you want to add more than 2 filters, use Update and than open the view definition again. Two new empty filter boxes will appear.

Sending e-mails

To send the alerts, you must have AA cron set on. Three entries are added to table cron by sql_update.php3, for daily, weekly and monthly sending. You can change the entries if you like. They define the time and date at which all mails are sent. You can't set individual sending times for collections.

E-mails are created so that in e-mail clients supporting HTML users see the HTML form and in clients supporting text only, users see text. The text form is created by deleting all HTML tags. Technically speaking, it is a MIME multi-part/alternative message with a text part and a HTML part.

E-mail headers From:, Reply-To:, Errors-To: and Sender: are configurable for each Collection. Also, you may set these fields for a fictive collection __default__, which is used whenever any of them is not filled for the active Collection. Another fictive collection __subscription__ sets e-mail headers which appear in e-mails sent on user subscription.

User interface

The login screen is shown by misc/alerts/index.php3, the main interface is in misc/alerts/user_filter.php3. It allows to input name and change password. In the other part there is a list of all subscribed collections. A user may change contents of any of the collections. Until she does so, the collection ID remains the same as in the Admin interface. This allows to propagate changes to users: If you do any change in the Admin interface, it will change to all users which didn't modify the collection. But when a user changes a collection, its contents is copied not to modify the common Collection storage. From the user point of view, she doesn't recognize it.

Creating subscription forms

Two scripts are here to simplify subscription forms creation. The first one is add_user_collection.php3, which uses the following required parameters:

and the following optional parameters

The standard error page shows an error description. The standard OK page shows information about where to change subscriptions or that the user should confirm her email address if she didn't yet.

The second script print_collections_select.php3 prints a select box to choose a collection by description. It is not necessary to use it, the script only simplifies the maintainance because it gets the collection descriptions from database. It has these optional parameters:

A simple subscription form may be:

<form name='f' method='post' action='http://www.ecn.cz/apc-aa/misc/alerts/add_user_collection.php3'>
<table>
<tr><td>E-mail:</td><td><input type=text name=email size=50></td></tr>
<tr><td>How often:</td><td><select name=howoften>

<option value=daily>Daily
<option value=weekly>Weekly
<option value=monthly>Monthly

</select></td></tr>
<tr><td>Choose a collection:</td>
<td><!--#include virtual="/apc-aa/misc/alerts/print_collections_select.php3?c[]=7&c[]=11"--></td></tr>
</table>
<input type=submit value="Subscribe">
</form>

But mind the example address www.ecn.cz/aaa is not working, it is only an example.

User Subscription Flow

  1. Usually users subscribe on subscription forms in your pages
  2. They receive an email message telling them to click on the confirmation URL or copy it to a browser
  3. The confirmation URL contains a 4-letter confirmation code which identifies the user
  4. After clicking on the URL the login screen appears with the user email filled in and the confirmation code is deleted from the database
  5. When the user clicks once more on the URL, the code is not more valid: a subscription page appears
  6. If the user doesn't remember her password, she clicks on "Send confirmation", receives another confirmation email and her password is deleted
  7. You can use AA Admin E-mails to warn users and / or delete them when they didn't confirm their subscription for a number of days

Sending e-mails manually

You do not need to send e-mails manually, this part is useful for developers. AA cron runs alerts.php3 with two parameters:

For example

alerts.php3?howoften=weekly

It will work on all items which appeared in Active bin from the last time this script was run. That includes items which were Pending and became Active (even if they are Expired at the moment of sending e-mail), items which were moved from Holding bin and new items added directly to Active bin. Look in the source alerts.php3 for the exact algorithm of selecting items (it's not as easy as described here).

The script itself does not check how often you run it, hence a user can receive a monthly digest every day if you are not careful.

You can use cron.php3 to run the script regularly.

Permissions in Control Panel

Superadmins may as usually access everything.

Slice Admins may access:

Tables structure

All tables concerned with Alerts have a name starting with alerts_.

User information is stored in alerts_user, collections description in alerts_collection. Filters belonging to collections are in alerts_collection_filter.

Filters are in alerts_digest_filter which is linked 1:n to table view (1 view has n filters). The fields last_xx in alerts_digest_filter include last time when the digest of items filtered by the particular filter was created and text_xx temporarily store the digest text.

Users subscriptions are in alerts_user_filter, each line of which has either a filterid or a collecetionid filled. It allows the users to choose simple filters instead of whole collections but this is not implemented.

THIS ITEM IS COMPLETELY DEPRECATED. A COMPLETELY NEW ALERTS DESIGN IS DESCRIBED IN THE NEW DOCUMENTATION. ALSO SEE READER MANAGEMENT DOCUMENTION AND DEMOS FOR USEFUL ALERTS DEMOS AND TUTORIALS

This walkthrough does not describe all details, you must look into the FAQ item AA Alerts for them.

To set up Alerts on your computer, first ask some Superadmin to set up default Collections and cron:

  1. Jump to Alerts / Collections
  2. There should be the special collections with Description __default__ and __subscription__. If you don't have them, something was wrong with sql_update.php3. You should create them in Admin panel, but you must change the "showme" field value to 0 in the database.
  3. Set the email headers for the special collections
  4. Set up cron on your server
  5. Change the values in the table "cron" in the database if you don't like the defaults. There should be 3 rows working with misc/alerts/alerts.php3, sending the daily, weekly and monthly digest. These are created by sql_update.php3.

Now any Slice Admin may work with Alerts:

  1. Switch to the slice the items of which you want to send
  2. Create a view of type Alerts Digest, fill in a plausible design
  3. At the top of the view design page fill some Filter Description and if you want to sent only some of the new slice items, fill the conds[] field with search form-like conds[] and sort[]
  4. Jump to Alerts / Collections
  5. Create a new Collection, fill at least the Description
  6. After clicking on Insert, a list of Filters and Users will appear
  7. Add Filters to the Collection

Hurrah, we have a new collection!

Now how to offer it to users? On any of your web pages, create a subscription form. See AA Alerts for details. If you want to see a list of users subscribed to your collection, click on Edit in Alerts / Collections.

THIS ITEM IS COMPLETELY DEPRECATED. A COMPLETELY NEW ALERTS DESIGN IS DESCRIBED IN THE NEW DOCUMENTATION ALSO SEE READER MANAGEMENT DOCUMENTION AND DEMOS FOR USEFUL ALERTS DEMOS AND TUTORIALS.

To learn about AA Alerts, click here.

To handle problems with users who did not confirm their subscription, AA superadmins may use Alerts Admin (in Control Panel menu Slice Admin / Alerts / Admin).

You can delete not confirmed users after a number of days and / or send them an email demanding them to do confirmation after a smaller number of days.

To switch either of the actions off, set number of days to 0. The two last fields are for your information only, they inform you about the subscription time boundary for the action.

To run the actions, you must have cron set up with a row running
misc/alerts/admin_mails.php3. This row is added automatically by the sql_update.php3 script.

This example uses 1 view, 3 categories, and 2 levels of constants. The catgories are not important but maybe you like to use them so I left them in there.

The view below manages a two level side bar menu. It highlights the branch you are in and the (sub)item you have selected. Example can be seen here http://pi.gn.apc.org

The constants are used as the menu entries. You have to use hierarchical constants and define the constants like this:

Level 0: Name      Value 
         Terrorism Terrorism 
         Policy    Policy ... 

Level 1: Name                        Value
         Politics of Terrorism       Terrorism::Politics of Terrorism Defining 
         Terrorism and Emergencies   Terrorism::Terrorism and Emergencies 
         IGOs and Laundering Policy  Policy::IGOs and Laundering Policy
         ... 

Now create a new constants view Paste the text below into Odd Rows.  Set the Group by to "Value Select" the hierarchical constant group created above View 342 is the listing view I use to display items from my slice.

The slice has 3 categories. This menu only manages the selection of the first category (category........) which is set to use the constant group created above. Further it's first confition is set to LIKE (name of category........). You will have to replace 342 in the text below with your listing view. You can leave away most of the {country}-stuff. To work this just needs {theme} and {_parent_}.

TODO: use better names for the aliases. 'theme' and 'country' might be substrings in the constants. That would cause havoc! All left to do now is to create your style sheet. Have fun!

----------SNIP SNIP----------

{switch({_#LEVEL##_})0:<br>
  {switch({theme}).*theme.*:
    <div class="constView_ContentThemes_ListEntry">
  :{_#NAME###_}.*:
    <div class="constView_ContentThemes_ListEntry_Hl">
    :<div class="constView_ContentThemes_ListEntry{switch({_parent_}){_#NAME###_}.*:_Hl}">
  }
  <a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}{switch({_#VALUE##_}){theme}.*:&als[_parent_]={theme}}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_ListEntry_link">_#NAME###_</a>
  </div>
:1:<!--{theme}--_#VALUE##_--_#NAME###_-->
  {switch({_parent_}).*_parent_.*:
    {switch({theme}).*theme.*::
      {switch({_#VALUE##_}){theme}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={theme}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
    }
  :{switch({theme}).*theme.*::
    {switch({_#VALUE##_}){_parent_}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={_parent_}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
    }
  }
}

----------SNIP SNIP----------

 

Some fields have a predefined set of possible values --- a constant group. These are usually shown in a select box, multiple check / radio boxes etc. Edit them in Slice Admin -- Fields -- Constants -- Edit / New.

Categories are constants with some special properties. The constant table structure is:


CREATE TABLE constant (
   id char(16) NOT NULL,
   group_id char(16) NOT NULL,
   name char(150) NOT NULL,
   value char(150) NOT NULL,
   class char(16),
   pri smallint(5) DEFAULT '100' NOT NULL,
   PRIMARY KEY (id),
   KEY group_id (group_id)
);

When to use different name and value

How the 'Display' and the 'Store in Database' parts are supposed to be used?

For example the "State" select box (if you want to see it on input form) has the names and values of:

NameValue
Approved bin1
Holding bin2
Trash bin3

Another example, more real-life - colors select box. There can be names of "Red", "blue", "very bright green", ... and values will be "#FF0000", "#0000FF", "#EEFFEE". In input form you see Red... and on page is then #FF0000

The third example is kind of hint. Suppose you want to have different kinds of item - for example "public", "private", "other" and you want to see this words on compact view. No problem, but you want to see each in different color. So you can define:

name: Private
value: <font color="#FF0000">Private</font>

Order Categories on Input Form as You Wish

You can set the priority order in the constant editing page, and then if you want the output in this order as well, then in the View set the sorting to be "Ascending (or Descending) by Priority"

Propagate changes into current items

Usually if you change a constant value, the current items in the database remain the same. By checking this box you force the changes to be made on the items too. If you change "red" to "cyan", all items with color "red" will be changed to "cyan".

Remember that the constants may be shared by several slices --- if you change a value, the changes may be propagated to some places which you didn't count with. Another danger is that if there were some items with "cyan" before, you can never ever find which item are converted from "red" and which are not.

Changing the constant name doesn't have any effect in the database but changes the look in all Edit / New item pages using the constant group.

Displaying list of constants on a page

For displaying list of constants on the page you can use specila type of view - Constant view Constant view is quite normal view, just like item listing view. You can use aliases, conditions or sorting (conds[], sort[], als[]) (from AA v2.6). 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 or if you want to use conds[] or sort[].
_#NAME###_const_nameConstant name
_#VALUE##_const_valueConstant value
_#PRIORITYconst_priConstant priority
_#GROUP##_const_groupConstant group id
_#CLASS##_const_classCategory class (for categories only)
_#COUNTER_ Constant number
_#CONST_IDconst_idConstant unique id (32-haxadecimal characters)
_#SHORT_IDconst_short_idConstant unique short id (autoincremented from '1' for each constant in the system)
_#DESCRIPTconst_descriptionConstant description
_#LEVEL##_const_levelConstant level (used for hierachical constants). If you want to display hierarchical constants in its hierarchy (so constant on second level have two spaces before the name), you can use following AA expression:
{switch({_#LEVEL##_})1: :2:  :3:   }

The APC AA has a Two Layer category system:

1) One set of broad categories set at the network level
These are useful so that people can 'browse' and find the information they are looking for without a specialized understanding of the content area.

2) Totally flexible page-specific categories

Individual page owners can setup any specialized categories that work for them. They 'map' their specialized categories to the APC-wide parent categories.

We also want to be able to map between different languages, so categories can be displayed in the local language, but stored as a universal constant.

This requires relating items in the first slice to the second, and using a related view.

  1. Create a slice, called for example Yyyy where your categories will be stored.
  2. Create the slice where the data will be stored

What are hierarchical constants? Imagine some keywords allowing to quickly find items of interest --- you have a top-level keyword Country, a first-level keyword United Kingdom and a second-level keyword Leeds. The support has three parts: Editing of the constants and choosing them in the Add / Edit item in AA control panel is described here, using them in a search form is described elsewhere.

Hierarchical editor

The new hierarchical editor is accessible from the standard constant editor by the button "Edit in Hierarchical editor".

The standard and the hierarchical editor are in some sense interchangeable --- you can edit constants in both and it will not damage the structure.

The hierachical editor shows several level boxes. When you choose an item in some level, the next level box will be updated. Because usually the constant Name and Value are the same, there is a check box "Copy value from name" which allows you to only edit the Name box. You can change the editor view by the options at the bottom of the page:

Changes to the view setting will take effect only after using "Save all changes to database".

Input type "Hierarchical constants"

To take advantage of the constants ordered into a hierarchy, use the "Hierachical constants" input type for a field containing the constants. This view allows the user to go through the constants by level boxes in the same way as in the hierarchical constant editor. The values chosen are filled into a multiple-select-box field.

Check the "wizard with help" about parameters.

There are several places where APC-AA sends mail, and it can be confusing, especially since it is really easy to configure them wrongly so they don't work, and little help for figuring out why. Lets consider 4 cases. The Bugs and Weaknesses of each method are shown because they may help pick which method to use, and also help guide as to places for further development.

Slice Admin or Editor wants notification of new items added to Hold bin, or edited or whatever.

Use the Email Notification functionality, here you can specify different messages to be sent when messages are added / edited to Active / Hold bins, and different recipient lists, so for example you can create a message to an Editor whenever a new message arrives in a Hold bin, and maybe a different message to the sysadmin when an item is moved into the Active bin (usually by the Editor). The message could be just something like "An item has been posted in Xyz slice" or by using aliases can include any fields of the item posted.

Bug/Weakness: You can't use aliases in Subject line, this might be fixed in some version (but is unlikely to be a priority!)
Limitation: The members of the list can only be changed by a slice admin, so don't use this for Alerts ...

A number of people want to receive items posted to a slice

Use a reader management slice (see doc/reader.html) in conjunction with Alerts (doc/alerts.html).

Bug/Weakness: its complex to setup, and frequently people don't succeed, if you don't follow the Tutorial Step by Step (in doc/alerts.html) you probably won't get it to work.

Bug/Weakness: In particular it requires creating an anonymous form, which depends very much on the way its being used (e.g. called from something.shtml or site.php3). One possible development fix would be creating a PHP3 script that took the slice-id of an Alerts module as a parameter and did this much more simply.

Bug/Weakness: documentation says 5.3a: View with type "Alerts Digest", when it means "Alerts Selection Set".

A number of people want to be in an email discussion, i.e. all posting to each other.

Use a Reader Management Slice (see doc/reader.html) in conjunction with Mailman, APC-AA is used to manage the mailman list

Bug/Weakness: you can no longer manage the lists (subscribe/unsubscribe) by email to the Mailman account once you've done this, mailman will almost certainly be sending out email telling the users they can!

Bug/Weakness: You have to understand both apc-aa AND mailman to get this to work since doc/reader.html refers to tasks that require knowing where to find and how to configure mailman.

Bug/Weakness: There is no link between information in a slice, or discussions, and the email discussion, i.e. this is not - like yahoo groups - a web OR mail interface to the same set of data.

Reports of failure (Jason Diceman) partly due to server setup

People wish to receive copies of new comments in Discussions by Email

See "FAQ/Discussions as Mail List", this allows a field in each item to specify a mailing list.

Bug/Weakness: This field has to be added to every item, it can't be specified at the slice level (make the field Required but not Shown and set a default). This is particularly difficult if you want to retrofit discussions to an existing slice, or something coming in over RSS.

Bug/Weakness: This can only go to a single email address, so you have to manage the list somewhere else outside APC-AA (there is no way to for example link it to Alerts).

Bug/Weakness: It doesn't appear to work, sends blank emails.

Summary


Template for Email Who gets the email How sent Bugs, Limitation and further development
Notification Admin -> Slice -> Email Notification Directly from script updating

Can't use aliases in Subject line
Can't self-manage recipients

Alerts Admin -> Slice -> Views -> Alerts View Readers from Reader slice, who can choose which to recieve By Cron Complex to setup (anon forms)
Email Discussion Not applicable - its email to email Members managed by Reader Management slice Mailman handles all sending

Requires understanding mailman to setup, reports of failure partly due to server setup
Cant subscribe/unsubscribe by email
No slice -> email or email -> slice

Discussion -> Email Admin -> Slice -> Views -> Discussion to Email One hard-coded email address Not sure, probably cron. Doesn't integrate with Alerts so no recipient management at all
Doesn't seem to work (Mitra).
Has to be added to each item in slice.

Note:

There is no integration for receiving email, although there has been discussion (where?) about posting articles by mail

In view you can specify "No item found" message, which is displayed if view (due to its current conditions) do not find an item to display.You can enter there:

One recomendation is to write something that relates to the slice content, e.g. "No news found" or "No events found", with in visible HTML or a comment tag. This helps with both usability and view development problem solving.

No, it is not possible - at least yet.

 There is a problem with characters encoding and different languages. Each language uses its own character encoding (like iso-8859-1 for English and Spanish, iso-8859-2 or windows-1250 for Czech, ...). If you select language for the slice, you also select (implicitly) the character encoding. If we allow users to use different language in the same slice, each item will be in different encoding, ... which means problems.

This can be done thanks to function f_y - expanded string.

  1. In the slice "Photogallery" make a view or views, which will show a single photograph.
  2. It is usefull to define the aliases in the Slice Admin / Design / Item Manager, so in the Item Manager you will see below any photograph the alias or aliases for showing it, e.g.: "{view.php3?vid=1047&cmd[1047]=i-1047-6341bce1bd2d5072f75cc440d6e1edf4}"
  3. In the slice "Articles", for the field "full_text......." create an alias e.g. _#FULLTEXT with fuction "f_y" and with no defined parameters.
  4. During the editing of items you can just copy the aliases from the slice "photograph" to the places in the text, where you would like to have the photographs

See an example.

see http://mimo.gn.apc.org/mlx for instructions

The Item Listing View (View.php3) and Design-Index (slice.php3) provide overlapping features. Which to use will depend on which features you need. Here are some of the differences.

Available featuresViewIndex
Search conditions from URLYesYes
Search FormNo<#215>Yes
?x=1699No (workaround)Yes
ScrollerNoYes
Slice idImplicit, can be overridden by parameterParameter in include or URL
Copy with TemplateYes with new wizard, but may need to edit HTML because numbers changeYes
SortingFrom Admin onlyFrom URL parameters only

Views are useful when you want functionality a little bit different from the standard Index, or Full-Text views. You can use them to customize sorting, or pick certain items or only a subset of the items.

Highlight is normal field, so You are able to display the icon or a text for highlighted items (on Item Manager or on website).

You can add the column for showing Highlighted item flag on admin interface:

1) Go to Admin - Design Item Manager

2) Add new column in Item Format (and Top HTML). For Item Format use the _#HIGHLGHT alias (not deffined, yet) just as in following example:

<tr class=tabtxt><td align=center><input type=checkbox name="chb[x_#ITEM_ID#]" value=""></td><td><a href="_#EDITITEM">_#HEADLINE</a></td><td align=right>_#PUB_DATE</td><td align=center>_#CATEGORY</td><td align=center>_#HIGHLGHT</td></tr>

3) Go to Admin - Fields - Highlight - Edit

4) Define the _#HIGHLGHT alias:

Alias 1: _#HIGHLGHT
Function: f_c - condition
Parameter: 1:<img src="/aaa/images/highlt.gif"><!--:-->:&nbsp
Help Text: Highlighted item shown as bulb icon

This will show bulb for Highlighted items. If you want to Display just Yes/No text use:

Parameter: 1:Yes<!--:-->:No

You have to be the slice administrator, then from the standard admin page select Admin -> Views, then you select "Item Listing" and click New.

The first few items are the same as for creating Index views (see the manual). You can then specify how to sort items, and specify a condition (that can take a parameter in the URL).

<!--#include virtual="/aa/view.php3?vid=5"-->

Will embed view number 5 into your page. The view knows which slice it applies to, so this can be embedded in an Index or Full Text View.

View.php3 will take parameters either in the "include" line, or in the URL of the page to which it refers.

You can sort items by specifying in the definition of the view (Admin->Views then select an existing View or click New) which fields to sort by, and wether to sort ascending or descending. The primary sort is the main ordering, and the secondary sorts within this. So for example you might specify Category as the primary sort, and sub-category as the secondary. Note that if you sort on a field then there is a bug (or feature) where items without that field defined will not show up in the index view.

Because views do not currently use sessions. There is no way, how to add 'Previous 1 2 .. Next' scroller to the 'view'.

This is the biggest limitation of 'Views' and we have to count with it.

To select just a sub-set of the items, specify a Condition, or set of conditions, you can then parameterise that in the include statement or URL. So for example, if you set Condition 1 to "Category" and "LIKE" then you can specify a parameter of "cmd[5]=c-1-News" to set the first condition on View 5 to "News" so that it would list any item with a category containing the string "News". This condition could be set in either the Include statement or the URL e.g.

<!--#include virtual="/aa/view.php3?vid=5&cmd[5]=c-1-News"-->

or in the URL.

?cmd[5]=c-1-News&.....

If there are special characters in the search term, i.e. dashes (as in E-mail) or spaces then quote it, and escape the quotes, for example to select a category=Social Ecology would require a URL of the form:

conds[0][category........]=%22Social%20Ecology%22

(%22 is a double quote (") and %20 is space). If you are constructing this URL from somewhere else and do not know what could be in the field then make sure to quote and urlencode the string.

If you want to put highlighted items on a page, you should create a view. In the view, one of the conditions is that highlight is not '' (note there is a bug so that once you've set the condition to '' if you try and edit this view, you will need to reset the condition to '' before you hit update or you will get a SQL syntax error

Create a Full-Text view by going to Admin->Views and selecting "Full Text" and clicking "New". Then you can specify cmd[5]=i-5-1a2b3c4d in the URL or include statement. You can also use cmd[5]=x-5-934 where 934 is short _id

The right alias is _#ITEM_ID#.

For example, to show an item in a full text view, the view.php3 script should get the parameters like:

vid=110&cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf

( the 'i' command to view.php3 script takes as argument unpacked (long) item id)

So if we pass the vid parameter directly in fulltext.shtml page:
fulltext.shtml:

<!--#include virtual="/aaa/view.php3?vid=110"-->

Which then needs us to pass the cmd parameter through url:

<a href="fulltext.shtml?cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf"> fulltext </a>

So we can generate this by placing in the Odd rows field of an index view

<a href="fulltext.shtml?cmd[110]=i-110-_#ITEM_ID#"> fulltext </a>

If you want to link to a view appearing in the same place on the same page (as for the main index going to a full text), then if your Index view has vid=109 then the URL should be:

"?cmd[109]=i-110-_#ITEM_ID#"

which will redraw the same screen, replacing view 109 with view110, for the item specified.

Static Views are a bit like macros, they are not related to a specific item or slice, but can be used where the same content, or parameterised content is needed on many pages.

It is a view that only has one format - the 'Odd Row' format. It does not lookup the values for any items or fields, but just prints the 'Odd Row format'.

However they can take parameters from the URL

You can use aliases defined in the URL parameter 'als'. For a detailed description of the als parameter, see "What parameters can I use with slice.php3"

For example,

There are 13 navigation pages. For example, there is a page on 'Communication Rights' which has a report on Internet Rights in general and links to the pages
'Communication Rights in South Africa'
'Communication Rights in Morocco'
'Communication Rights in Senegal'
etc...

I did not want to write 13 pages, so I used 2 static views -- one for country pages, and one for topic pages.

The topic page is /topic.shtml. It has this include

<!--#include virtual="/apc-aa/view.php3?vid=2-->

topic.shtml will be called with parameters. To create the 'Communication Rights' topic page, it will be called as

/topic.shtml?als[MY_TOPIC]=Communication+Rights&als[URLE_TOP]=Communication%2BRights

URLE_TOP is an alias similar to MY_TOPIC, but it double URL encodes the value. It will be used to generate links. %2B represents the +. A + in url encoding is a space.

In this topic.shtml I want to create links to these pages. To create these links, view #2 has this 'odd row' format:

<a href="/resource.shtml?cmd[1]=c-1-South%2BAfrica-c-2-_#URLE_TOP">South Africa - _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Morocco-c-2-_#URLE_TOP">Morocco - _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Senegal-c-2-_#URLE_TOP">Senegal - _#MY_TOPIC </a>

and the MY_TOPIC and URLE_TOP are substituted from the als parameters in the URL.

Views can be swapped in and out from the URL, using syntax like "cmd[5]=v-8" to display view 8 at the place where View 5 was expected (for example by <!--#include="/aa/view.php3?vid=5"-->

For example, if you want a navigation menu that redraws itself depending on what is clicked on, you should create each of the different views you want to appear and then include one view in the shtml page. Then you can switch between displayed views using the url parameter.

For Example:
----------- index.shtml ----------
[...]
<h3>content</h3>
<!--#include virtual="/apc-aa/view.php3?vid=9"-->
<p> page footer... </p>
[...]


--------- code for this menu in the Odd row field of view #9-----
[...]
<a href="index.shtml?cmd[9]=v-13">News</a><br>
<a href="index.shtml?cmd[9]=v-14">Calendar</a><br>
<a href="index.shtml?cmd[9]=v-15">About us</a><br>
[...]

When the index.shtml page is redrawn the initial view #9 will be replaced by the appropriate view, for example view #13 will appear in the News slice and view #14 in the Calendar slice.

Because the PHP is interpreted via an include on the server, you cannot easily change the view at run-time, for example changing it based on a mouse-over event, it requires a page to be redrawn.

** Input (setting the admin interface)
  1. go to Admin - Fields
  2. add new field to the slice, where you want to store related item
  3. go to Edit page for the new field (Admin - Fields - Edit)
  4. choose one of the following options in 'Input type' selectbox:
    - Related Item Window
    - Multiple SelectBox
    - Select box
    - Check box
    - Multiple Checkboxes
    - RadioButton
    (this is sorted in order of usability - most useful is 'Related Item Window' or Selectbox)
  5. If you choose 'Related Item Window' then in the Constant field you can select not only the constants groups, but you can select there also the slice! If you select there the slice, there will be item headlines as options in the inputform. It allows you to select related items for the one you are writing. As you see it is possible to select any slice in here, so it is possible to create related items not only from the current slice, but to another slice too. It is possible to have the slice of items and another slice of authors and then set the relation through such field. For related item just select there the same slice you are in.
  6. Select the 'Item IDs' option in Insert field to be the related items ids correctly written to database.
  7. click on 'Update' - Input is set

One Note on 'Related Item Window' - in fact it is the only one option to use if you want to use the field as 'Related Item' because other options shows all slice items on one page, which is usually too much. Another feature of 'Related Item Window' is, that it is possible to add items not only to the written item, but you can add '2 way relation' between items - written item (say 2) is not only related to assigned item 1, but the item 1 is then related to item 2 then.

The next problem is, how to display the related items on webpage.

** Output (1) - Standard use of views

  1. go to Admin - Design Views page
  2. create new view (you can create the 'Fulltext view' if you want to show only one item or you can create 'Item listing' view for displaying more than one item in view)
  3. Fill the name of view, Top, Bottom and Odd row HTML code (the condition fields you can leave blank)
    For example:
    Item listing: Item List - related test
    Odd Rows: <br>Related: How can I use the related items feature to link items from one slice into another
  4. Click on 'Update'
  5. Create page which includes the view. Say the view number is 110:
    related.shtml
    APC - ActionApps Test Site
  6. go to Admin - Fields - Related field Edit page
  7. create an alias for the Related field:
    Alias 1: _#RELATED_ (the name is up to you)
    Function: f_h
    Parameters: -
    (the parameter is DASH - used as separator for multiple item ids)
  8. go to 'Admin - Design Index' page
  9. Add next code to 'Odd rows' field:
    <a href="related.shtml?cmd[110]=i-110-_#RELATED_">Related</a>
  10. click Update - link to related stories Done

This is the way, how to create link to related item view and also this is the way, how to create link to fulltext view

For related item however we expected another behavior. We want to display related items under the fulltext of the item (or directly under each item on index page). That's why we introduced 'view as alias feature':

** Output (2) - view as alias

steps 1) - 4) is exactly the same as in Output (1)

  1. go to Admin - Fields - Related field Edit page
  2. create an alias for the Related field:
    Alias 2: _#SHOWVIEW (the name is up to you)
    Function: f_v
    Parameters: vid=110&cmd[110]=i-110-_#this
    As the parameter we write the same parameters we would write for view.php3 as url parameters. The only difference is, that we use the keyword _#this, which is substituted by item ids from the field.
    Note: _#this is not alias - is is not defined as other aliases, it is much more the keyword - see Paramater substitution in f_v
  3. go to 'Admin - Design Fulltext' page (for example)
  4. Add next code to 'Fulltext HTML code' field:
    <br>Related: _#SHOWVIEW
  5. click Update - related items displayed

Output (2) describes how to create view alias. With such alias you can work as with any other aliases.

Tip:
In step 6) of Output (2) we used field content as list of displayed items:

vid=110&cmd[110]=i-110-_#this

In some cases we may want to switch between the views depending on field content. Then you can use parameter like:

vid=110&cmd[110]=v-_#this

or more complicated:

vid=110&cmd[110]=i-_#unspecified.....-_#this

Then the fields <this> in example a) or unspecified..... in example b) should contain the ids of view to show (112, 113...).

How do I create a View which indexes all items that relate to that item.

An example might help..

I have two slices 'authors' and 'articles'.

In articles I have a field 'author' which relates to the slice 'authors' (in it is stored ID or IDs of author/authors of the article).

So in articles on the web is displayed information from the 'authors' slice.

But now I would like to show references to articles on the pages of their authors. And I don't want to make it by a new relation field in the slice 'articles', because I would have to after addition of a new article go to the slice 'authors' and edit the author's profile - make a relation to the new article.

Do you have some idea, how to display the information from the slice 'articles' in the slice 'authors' if the relation field is in the slice 'articles'?

Yes, it should be possible to display author's articles, because there is the "relation" field for Author (the created_by.....1 in your case) in the Article slice. There are the ids of 'Author' records (items) stored in this field. So, it is possible to create view (say number 123) in 'Article' slice where the first condition will be

Author =

Then, you just create the page which includes the view:

---author.shtml ---
<!--#include virtual="/aaa/view.php3?vid=123"-->

The link to this page then should look like:

author.shtml?cmd[123]=c-1-5254422456eab4763bea34

where 5254422456eab4763bea34is item (=author) id in Author slice. Such link can be generated automaticaly Index - Odd row (for example):

<a href="author.shtml?cmd[123]=c-1-4f35cd6ab328690caffbe7d646eded78">_#NAME####</a>

Javascript item exchange View is a type of View. It works exactly the same as a standard view, but the primary usage for this type is to show items on any page around the Internet. For a simpler way of doing this, see "How do I use jsview.php3 to view pages on a site where AA is not installed."

The destination page should contain a HTML tag like:

<SCRIPT LANGUAGE= "JavaScript"SRC="http://aa.ecn.cz/apc-aa/view.php3?vid=1"></SCRIPT>

This tag includes the output of view to any page on Internet (there is no restriction to one server).

Because such tag requires javascript as output of view.php3, the format strings for the view (Admin -> View) should look like:

Top HTML document.write("<TABLE WIDTH='100%' BORDER='0' CELLPADDING='2' BGCOLOR='#FFFFFF'>")
Odd Rows: document.write("<TR><TD VALIGN='TOP'>12/05/2001</TD><TD><a href='?x=1735'>How do I use a Javascript view to see pages on a site where AA is not installed</a></TD></TR>")

Bottom HTML:

document.write("</TABLE>")

Note that there is (or was) a bug where if the item would generate no items then you'll get an error rather than empty Javascript.

The only required parameter to view.php3 script is number of view to show. This parameter is given by vid url variable. All remaining parameters are optional.

Each optional view parameter begins with cmd[x], where x is view number in which the parameter should be used. This is needed because of possibility to include more than view to one shtml page. That's why we need to specify, for which view the command should work.

It is impossible to specify more than one cmd for one view. If you want to use cmd[]=d for the view, you can't use it with combination with cmd[]=c, for example.

Above is still true, even after CVS snapshot 20031109, since when you can also use this syntax: vid=x&cmd[x][]=c-1-<something>&cmd[x][]=c-2-<something>. Note the extra [].

However, you can use more settings (set[x]) per view. Just seperate settings with a comma, like: set[23]=from-10,to-20.

After the cmd[x]= is always character, which specify which command is used - how modify the view. The c command modifies conditions, for example. The values after command character are user parameters and its meaning is different for each command. The parameters are separated by '-' character. If you need to use a hyphen '-' in a parameter, use 2 hyphens '--' instead. Description of parameters is in following table of examples.

Parameter example Description
vid=4 id of displayed view
cmd[23]=v-25 show view id 25 in place of view id 23
cmd[23]=i-24-7464647 view number 23 has to display item 7464647 in format defined in view 24
cmd[23]=x-24-1589 The same as i, but there you can use both - short_id or long item id (as the last parameter)
cmd[23]=x-24-1589-1545-1612 Display all three specified items. You can use as many ids as you want (the same works also for 'i' and 'o' cmd). This behavior is used for related fields, where related fields are displayed by{view.php3?vid=33&cmd[33]=x-33-{@relation.......1:-}}.
cmd[23]=x-24-url keyword url means, that item id is taken from url parameter 'x=...'
cmd[23]=o-24-1589 The same as x, but the number of item display (countHit) is not increased (as opposite to 'x' or 'i')
cmd[23]=c-1-ICT display view no 23 in place of view no 23 (that's normal), but change value for condition 1 to "ICT"
cmd[23]=c-1-ICT-2-%22Jane%20Smith%22

the same as above, but there are redefined two conditions. All three conditions could be redefined, notice how "Jane Smith" requires urlencoded double quotes %22 or the search won't work, and the space turned urlencoded to %20 otherwise it would be interepreted as Jane OR Smith

Since CVS snapshot 20031109 you can also use this syntax:
cmd[23][]=c-1-ICT&cmd[23][]=c-2-%22Jane%20Smith%22
You do need to use this e.g. when you want to specify the first condition in your .shtml file, while second one comes from the URL
cmd[23]=d-headline........-LIKE-Profit-source.........1-=-Ecn-publish_date....-m:>-86400 displays view no 23 and redefines the conditions. The conditions are in format field-operator-value. For list of possible operators see search caption. The operators could be with its modifiers, too. The unlimited number of conditions should be there specified. The speciefied conditions allways replaces all conditions specified in view definition (through admin interface). There are three diferences from cmd[]-c command - 1)operators and fields are specified, 2) default view conditions are ingnored, 3) there can be unlimitted number of conditions. The example would show items in which the headline contains 'Profit' and source field is 'Ecn' and the item is newer that one day.
cmd[23]=d-headline.......1,category........-RLIKE-Enviro You can use more than one field in one condition. Example displays items where headline.......1 OR category........ begins with Enviro
set[23]=listlen-20 setings to modify view behavior (can be combined with cmd)
- sets maximal number of viewed items in view 23 to 20
- there can be more settings - comma separated
set[23]=sort-headline.......1 set item order (use 'sort-headline.......1-' for descending sort order
set[23]=from-10 - displays items from 10-th (in view 23) - it can be combined with listlen, to, ... parameters (set[23]=listlen-20,from-5)
set[23]=to-15 - displays items to 15-th (in view 23) - usefull if combined with from parameter (set[23]=from-2,to-9)
set[23]=page-2-3 - displays second page from 3 (in view 23) - it didvides all matching items into 3 pages and displays the second one. If you do not specify the second parameter (3 in our example), the page will be listlen items long.
set[23]=random-1
set[23]=random-number.........1
selects item(s) to show randomly. If you use the 'random-1' parameter, any item in Active bin is displayed. If You use field_id instead of '1', then the content of field specified by field_id is used as probability to show the item. Let's have two items. The parameter looks like 'random-number.........1'. The first item has the number.........1 filled with number 10, the second with 50. Then the second item will be displayed 5x more offten than the first one. The 'weight numbers' and 'number of displayed items' are unlimited. This feature is very good for banners.
set[23]=banner-2-38
set[23]=banner-2-38-number.........1
set[23]=banner-2-38-norandom
by this parameter you are able to display any view (38 in or case) inserted just after the second (2) item in view (number 23). The item shown in inserted view (38) is selected randomly, possibly with weight specified in weight field (number.........1) - just like in random parameter described above. If you do not want use random item (banner), use 'norandom' keyword in place of 'weight field' (good for displaying nested newsbox). See also banner parameter for slice.php3. The example of included banner is on http://ecn.cz.
set[23]=noitem-Not%20found - redefines the 'Not item found' message in view.
set[23]=slice_id-79a69a0ad73c81ac332b0e8c4c3cea93 - redefines the slice from which the items will be displayed.
set[23]=slices-79a69a0ad73c81ac332b0e8c4c3cea93-45639a0ad73c81ac332b0e8c4c3cea44 - display items from specified two or more slices.
als[alias] user alias definition - you can define your own aliases in url (for both - slice.php3 and view.php3). Aliases names MUST!!! be 8 characters long. Don't forgot, that the alias value have to be urlencoded.
Example: als[MY_ALIAS]=Summary%20Page (or maybe better: als%5BMY_ALIAS%5D=Summary%20Page)
defines alias _#MY_ALIAS. If used in formatstring ('Admin - Design Index' for example), it prints 'Summary Page'
nocache=1 URL parameter for pagerefresh - the view is not taken from cache (- no matter if the view is allready cached or not). Cache is updated.


The parameter wizard helps you to design parametres when setting input type of function aliases.

It describes the input type / function and all parametres. Under each input box is a description, left of the box is the type of the parameter value. It allows you to set each parameter individually, not concerning about the ":" syntax. You run it by clicking on a link in the admin pages. You can reread the old parametres, write the new ones or watch example parametres. Some of the input types / functions
have more examples showing different groups of parametres.

This wizards now replaces the previous 'What is the Prameters in Alias Function definition' section in the FAQ.

The script is a universal mechanism based on a help array (see constants_param_wizard.php3 and xx_param_wizard_lang.php3). It only takes a few parametres (names of the fields on the web page) and is prepared to be perhaps used for another tasks as well.
The AA now enable to create a Calendar. Events lasting for several days are supported, repeating events are not supported.

Usually three parts of a calendar view are needed. First, a table showing the days and perhaps some caption of events which happen. This is prepared by the calendar view type. Second, some select boxes to choose the year and the month. Prepare these in a .php3 page. Third, a list of events to be shown after clicking on a date. This may be done by a list view with the conditions set as explained further.

To put the view and the caption together, use a .shtml page --- an example of a very simple one is in doc/script/calendar.php3.

Calendar view

Create it by Admin - Views - Calendar - New. Two calendar types are available: Month List shows a month with days in one list under each other, Month Table shows a table with one row for each week. Some new aliases are defined: New parameters to the view command are introduced: month and year. E.g.
set[301]=month-3&year-2002

The view setting are as follows:

Year and month selectboxes

These may be created by a .php3 script. An example of one is in doc/script/calendar.php3. The script is commented

List of events

An ordinary view of the type "Item listing" will do. You must set two conditions. The first condition must be "Start date <" where Start date is the name of the field containing event start date, the second must be "End date >=" where End date is the name of the field containing event end date.

The conditions are controlled by the command cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1 described above.

If you want to add functionality to the Add / Edit item page, you can use JavaScript code. This may be useful in many cases. JavaScript is executed on the client computer and works in most web browsers, e.g. Internet Explorer and Netscape on PC / Mac. There are many enhancements which work in IE only or in Netscape only but enough features are available for both. I assume you know about JavaScript or will look for some more info on web.

Some examples of what may be done:

Events lasting one or more days. You need two fields -- event start and event end. But most events are one-day events and the users hate to fill the same date twice. You can add a link "Copy date from Start date" which will copy the value. Or you can add an "aa_onSubmit" trigger, which will copy the value before submitting the form when End date is not changed.

Combining two fields. You want to join values from several fields into another field. You can do it just after leaving any of the fields by the "aa_onChange" trigger or just before form submit by the "aa_onSubmit" trigger.

Predefined functions

Some useful functions are ready to work with fields. These are defined in indclude/fillform.js. Have a look at the file to see other more general and more powerful functions. The file is included with the Add / Edit item page if anything is defined on the Field Javascript page. The two basic functions are:

setField (fieldid, newValue) -- sets a value to various control types, to a text box, text area, select box, check box etc. Works even with AA dates (shown by three select boxes for day, month and year) -- use a UNIX timestamp (number of seconds since 1.1.1970) to set a date.

getField (fieldid) -- gets the value from various control types. Works with AA dates, returns the UNIX timestamp.

Field Triggers

If anything is written in this page, the file include/fillform.js is included with the Add / Edit item page. You can write any JavaScript code in the page. AA will look for triggers and add them to all controls if it founds them. Each trigger must be defined with

function aa_onTrigger (fieldid) { trigger body }

where Trigger is a name of any allowed trigger -- these are listed at the bottom of the Field Javascript page. You can add whitespace (spaces, tabs, line ends) but you must use the parameter fieldid. The ID of the field to which a control belongs or the name of the form ("inputform") is sent in it.

Solution to the examples

Combining two fields. You want to copy headline and expiry date to abstract after editing any of them:

function aa_onChange (fieldid) {
    switch (fieldid) {
        case 'headline........':
        case 'expiry_date.....':
            var myDate = new Date (getField('expiry_date.....')*1000);
            textdate = myDate.getDate()+'.'+(myDate.getMonth()+1)+'.'+myDate.getYear();
            setField ('abstract.......2',getField('headline........')+' '+textdate);
            break;
    }
}

Events lasting one or more days. Suppose you are using the Expiry date and Publish date as event end / start date. You can add this code to the Before HTML code in Admin -- configure Fields:

<tr><td></td><td class=tabtxt>
<a href="javascript:setField('expiry_date.....',getField ('publish_date....'));">Copy from post date</a>
</td></tr>

Remember to add something to the Triggers page (e.g. "//" which is a commentary in JavaScript), otherwise fillform.js with the functions getField and setField won't be loaded.

If you want to use the trigger, add this code to the Field Triggers:

function aa_onSubmit (fieldid) {
    
var myDate = new Date (2001,0,1); // the default date is 1.1.2001
    if (getField('expiry_date.....') == myDate.getTime() / 1000)
        setField('expiry_date.....',getField ('publish_date....'));
}

This will change the end date before submitting but only if it is set to 1.1.2001, which is default.

Through Value field on the Mapping page you can specify not only a new value, but also any AA expression, which is unaliased - example:

<a href="{source_href.....}">{source..........}</a>

In the Value field you can specify, which items should be fed and which not. It is done by modifying the value of the ‘Status Code’ of the receiving slice, according to field in the feeding slice.
Status codes are: 1=active, 2=Holding, 3=Trash, 4=Do not fed)

An example set-up:

1) Set Feeding, as usual ('Slice Admin' -> 'Inner Node Feeds') (see feeding FAQ)

2) Go to 'Slice Admin' -> 'Mapping' and select the your source slice

3) fill something like: {switch({category.......1})Enviro:1:4} for 'Status Code' and set FROM to '-- Value --'

After this all items from the source slice with category 'Enviro' will be fed into Active ('Status Code' value=1). Other will not be fed ('Status Code' value=4).

The offline filling currently works only in IE with Java support (there are some problems with Netscape and file manipulation permissions).

All files used for off-line filling are stored in /mics/offline2slice directory. All of them should be copied to local computer, where you want to use offline filling. There are a few steps to do for sucessfull installation.

  1. Create directory on your local computer (default is c:java).
  2. Copy files from /mics/offline2slice directory of apc-aa installation to created directory.
  3. Add row "set classpath=c:java" to your autoexec.bat file, in order java finds the class definitions.
  4. Restart computer in order the changes in autoexec.bat tekes efect.
  5. Open the delete_file.html file and change the location of main filling form
    row 11: document.location='c:\java\fillform.html';
  6. Change the location of the file, where form data are stored
    row 19: <PARAM NAME="filename" VALUE="C:\offlinedata.txt">
  7. Open the file fillform.html and modify it in order to have the same fields as your slice have. The fields are identified by its ids (like 'headline........'), known from AA.
  8. Change the parameter to OffLine2Slice applet to point to the file, where the content of filled forms will be locally stored
    row 240 <PARAM NAME="filename" VALUE="C:\offlinedata.txt">
  9. Change the URL in ACTION atribut of second form at fillform.html page to point to your server with ActionApps
    row 356: <FORM NAME="hidden_form" ACTION="http://aa.ecn.cz/aaa/offline.php3" METHOD="post">
  10. Change slice_id in hidden form input to match your slice, where you want to store item
    row 358: <INPUT NAME="slice_id" TYPE="hidden" value="45636f6d6f6e69746f72427942455a4c">
  11. Change the path to delete_file.html to point to your install directory, where the file is stored
    row 361: <INPUT NAME="del_url" TYPE="hidden" VALUE="C:/java/delete_file.html">

The offline filling is now installed on your computer and you can try it (open your local fillform.html file in your browser). There you can fill as many items as you want and after all send it to the server.

Before sending the filled forms to server make you sure, that the slice you want import to, permit this operation (see 'Admin' - 'Slice' - 'Allow off-line item filling').

After the sucesfull sneding the items to server, your browser should be redirected to the page, where you can delete the file (offlinedata.txt). In this file the filled data are locally stored. The deletion is not necessary - the offline filling script offline.php3 will recignize, if the data for each item is already stored in database or not (the CRC for each item is computed). However, the better practice is to delete the file. This saves the capacity of line, because the data will not be transfered to server for second time.







Other documentation

You have prepared a public anonymous posting 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.html"-->
<!--#include virtual="/aaa/fillform.php3"-->
<!--#include virtual="/bottom.html"-->

Than 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 this.

1. General usage of Anonymous Forms
2. Filler and fillform
3. Creating Anonymous Forms with the Wizard
4. Editing with anonymous forms
5. Tips and tricks
6. Reader management specifics
7. Show results

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.

See also: doc/reader.html, doc/alerts.html, doc/script/show_result.php3

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. See below.

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

4. Editing with anonymous forms

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

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.

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"-->
If you want to be able to go into the admin interface to edit an item, you can now put the alias
_#EDITITEM, into a view, the user will be asked to login, there are other ways to edit items anonymously.

After editing the item, the user will be returned to the page they were viewing.

The user will only be prompted to login the first time they try and edit an item, after that the AA_CP_Session parameter is added to the URL. In some cases this might not get through to the _#EDITITEM, (hints on how to make this work could go here). In which case a return URL can be
specifically written into the URL using {alias:headline........:f_e:edit:full url}

If you want to display some view on page, which is stored on site where is not installed AAs, you have three possibilities.

  1. use remote, remotec or remotec.php
  2. create javascript view - this is good if you want to do something complex with the Javascript.
  3. use the jsview.php3 to display existing view.

This answer covers point 3) - jsview.php3

The usage is easy. Just replace SSI include in original shtml age with the javascript one. The jsview.php3 takes exactly the same parameters as view.php3.

For example, if the old SSI code in page.shtml was:

<!--#include virtual="/apps/aa/view.php3?&vid=2&cmd[2]=c-1-APC" -->

the new javascript code in page.shtml would be:

<script type="text/javascript" src="http://www.apc.org/apps/aa/jsview.php3?vid=2&cmd[2]=c-1-APC"></script>

There are two feeding methods - authomatical and manual. Automatical feeding works only for new/updated item. By manual feeding it is possible to feed any selected item to another slice (if you have permission to do so).

Manual feeding
In Item Manager select the items you want to send to another slice. Select "Export" on the toolbar just below the itemlist. After clicking on "GO" a new window is shown where you can select destination slices. (You must have a permission in the destination slice - at least Author. If you are Editor or more in the destination slice, you can set the "Active" checkbox, which means to copy the items in the destination slice into the Active Bin. If the checkbox stays unchecked, the item is copied to the Holding bin).

The feeding is error-safe, it is impossible to feed one item to the same destination slice more than once.

Automatical feeding

Each Feed needs to be configured in both the slice where the items are entered and which will export items, and for the slice where the items are imported.

Select the slice where the items are entered. Select Admin->Content Pooling -> Inner Node Feeding. If you are willing for items to go to any other slice on the same host then check "Enable export to any slice". Otherwise uncheck this box, and move slices that you want to receive items to the Export Enable box.

Select the slice where items will be received. Make sure the slice you want to recieve from is in the Import box. As a courtesy send an email to the administrator of the slices you want to receive from.

The import process can be fine tuned in two ways.

In Admin->Content Pooling->Filters you can select which of the exporting slice's categories items come from, and to which categories of the importing slice they are delivered. Select the Active box if you want items in this category to be made Active, otherwise they will go in the Holding Bin for manual approval. There is currently no way to control which items are fed, only which category they go to.

In Admin->Content Pooling->Mapping you can control which fields of the source slice end up in which fields of the destination slice.

If you want to export items already in the slice, then go to the Item Manager, check the items to export, and choose "Export" and Go. This will give a choice of destination slices, which you can check along with whether they should be Active, or go to the Holding Bin for manual approval.

When you write an item which goes into the Active bin or when you approve an item, the feeding function is invoked. This function finds all slices where the item should be fed (depending on current feeding permissions ("Admin" -> "Content pooling - Import & Export") and feeding setings ("Admin" -> "Content pooling - Filters")). The feeding goes deeper and deeper between the slices until a cycle is detected or feeding into Holding bin is set.

Feeding one item from one slice to another means:

Let's look in the constants.php3 file:

# content table flags
define( "FLAG_HTML", 1 );
define( "FLAG_FEED", 2 );
define( "FLAG_FREEZE", 4 );
define( "FLAG_OFFLINE", 8 );
define( "FLAG_UPDATE", 16 );

# states of feed field of field table
define( "STATE_FEEDABLE", 0 );
define( "STATE_UNFEEDABLE", 1 );
define( "STATE_FEEDNOCHANGE", 2 );
define( "STATE_FEEDABLE_UPDATE",3);
define( "STATE_FEEDABLE_UPDATE_LOCKED",4);

# relation table flags
define( "REL_FLAG_FEED", 2 ); # 2 - just to be compatible with content table


There you see how the various flags can be set. The most important are the flags for the field table. For each field you can set whether this field is

These settings can be done on the "Admin" -> "Main settings - Fields" -> "Edit" -> "Feeding mode" page, where you can set for each field:

Depending on field table flags, the flags for content table are set:

After copying the contents, the relation table is updated. This table holds information about the feeding tree (from which item is the content fed to another). The relation table will be used for another purposes in future too (for holding discussion threads, ...), so each record for feeding if flagged as REL_FLAG_FEED.



There is solution for 'Internal feeding':

It could be done using field 'Mapping' ('Slice Admin -> Mapping').
One of the possibilities there is to select '-- Value --' for a field. The 'Value' is not ony static text, but you can use any AA alias construct there (just like: <a href="{source_href.....}">{source..........}</a>).

The solution is to specify such expression for 'status_code' field (which controls, in which bin resulting items appear:
1 - Approved
2 - Holding bin
3 - Trash
4 - Item is not fed

So, if you specify something like:

{switch({highlight.......})1:1:4}

for status_code field, only highlighted fields are fed (into Approved).


There is no way to do it for external (Inter Node or RSS) feeds. The only solution there is to feed all the items into one slice
and then show only highlighted items in destination slice (the
highlighted flag will be copied too, so there is no need for manual setting "highlighted" in destination slice) CSN is a feature which allows item exchange between two servers.

Developers note: The implementation is based on Moritz Both's specification:
http://plus.aldebaran.de/apc-aa/csn.html
http://plus.aldebaran.de/apc-aa/csnspec.html

--------------------------------------------------
A. Installation

Node = one installation of ActionApps.

Assume there are two nodes, which want to exchange items

Step 1 Set up the node details,
- must be done by sysdadmins, with shell access on both nodes, but they only have to be done once, no matter how many slices and how many nodes are configured, normally it will have be done when ActionApps was installed.

Set the ORG_NAME in config.php3 file to the name of your organization, e.g.:
define ("ORG_NAME","Econnect");

Step 2 Set the information about the collaborating nodes.
- must be done by a Superadmin on both nodes, once for each node that it imports or exports to.

Step 3 Setting import and export
- this can be done by the Slice Admin

3.1 On the exporting node,

There you can set the permissions for remote users, who will have the rights to get items from the current slice.

3.2 On the importing node,

There you can set, from which remote nodes and slices will items be fed.

3.3. Set the filters and mapping on the importing node

Filters and mapping you can set exactly the same way as for local feeding. See 'Slice Admin -> Filters' and 'Admin -> Mapping'

Step 4. Set the cron
ActionApps adds the task for CSN to the AA Cron on its setup. If you are superadmin, you can check it on AA -> Misc - Cron page. There should be task defined as:

 * 8,23,38,53 * * *   admin/xmlclient.php3 

In order the task from cron are started regulary, the cron must be well configured by the system administrator. If the cron is configured, the column 'last_run' on 'AA -> Misc - Cron' page is not empty and the value is time to time changed. Please read section:

or such link to your index (or fulltext) design (Admin -> Design -> Index -> Odd Rows). This will point to fulltext of parent item or to the fulltext of the same item, if the item is not fed.


Normally you will want either a Item listing, Full text or Static Page view.

On you index view...

Include _#ID_COUNT (number of found items) in the Top HTML and _#ITEMINDX (index of item within view) in front of each result item.

Also make sure the HTML code for "No item found" message says something that makes sense for the search type. Use the notshowall=1 [exact code] so blank searches show all items. Include multiple useful sorting options.

If you have one slice item with many discussion items, it may be used as a message board.

You can make AA send all new discussion items posted to this particular item to an email address. If the address is a mailinglist, you can use the discussion as a message board.

You need to:

The program is implemented in discussion.php3, function send2mailList. It is called from filldisc.php3.

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:

Design the Discussion

  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
    tag.
  7. click on Insert to create the view
  8. The code below assumes the view created is number 55

Integrate into Full text View (if you are using slice.php3)

  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 into Full text View (if you are using site.php3, or possibly if you are just using 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;

Integrate into Item Manager so the discussions can be edited.

  1. Go to 'Admin - Design Item Manager'
  2. 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>
  3. Possibly change 'Top HTML' for header of item manager and click OK.

Add to Listing views

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 might look like....

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

Done. Discussions works.

Aliases usable for discussions

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} expresssion, 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_DESCd_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_IDd_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)

Default values for discussion view

If the default values for the view design are missing, here are some values that work:

Top HTML
<table bgcolor=#000000 cellspacing=0 cellpadding=1 border=0 align="center"><tr><td
class="discuss"><table width=100% bgcolor=#f5f0e7 cellspacing=0 cellpadding=0 border=0>
HTML code for index view of the comment
<tr><td width="10">&nbsp;</td><td class="discuss">_#CHECKBOX</td><td width="10"
class="discuss">&nbsp;</td><td align=center nowrap class="discuss">_#DATE####</td><td width="20"
class="discuss">&nbsp;</td><td nowrap class="discuss">_#AUTHOR## </td><td class="discuss"><table
cellspacing=0 cellpadding=0 border=0><tr><td>_#TREEIMGS</td><td><img src=http://work.ecn.cz/apc-
aa/images/blank.gif width=2 height=21></td><td nowrap class="discuss"><a
href=_#URL_BODY>_#SUBJECT#</a></td></tr></table></td><td width="20"
class="discuss">&nbsp;</td></tr>
Bottom HTML
<tr><td align="center" class="discuss" colspan=8><br>_#BUTTONS#<br><br></td></tr>
</table></td></tr></table>
Show images
on
Order by
thread
View image 1
<img src=http://work.ecn.cz/apc-aa/images/i.gif width=9 height=21>
View image 2
<img src=http://work.ecn.cz/apc-aa/images/l.gif width=9 height=21>
View image 3
<img src=http://work.ecn.cz/apc-aa/images/t.gif width=9 height=21>
View image 4
<img src=http://work.ecn.cz/apc-aa/images/blank.gif width=12 height=21>
*HTML code for fulltext view of the comment*
<table bgcolor=#000000 cellspacing=0 cellpadding=1 border=0 align="center"><tr><td class="discuss">
<table width=100% bgcolor=#f5f0e7 cellspacing=5 cellpadding=0 border=0>
<tr><td class="discuss"><b>_#SUBJECT#</b></td></tr>
<tr><td class="discuss"><A href="mailto:_#EMAIL###">_#AUTHOR##</a>, _#DATE####</td></tr>
<tr><td class="discuss"><br>_#BODY####<br><br></td></tr><tr><td align="right"><a
href=_#URLREPLY>Reply</a></td></tr></table></td></tr></table><br>
HTML code of the form for posting comment
<SCRIPT Language="JavaScript"><!--
function checkData() {
var text="";
if(!document.f.d_subject.value) {
text+="subject "
}
if (text!="") {
alert("Please, fill the field: " + text);
return false;
} return true;
} // -->
</SCRIPT>
<form name=f method=post action="/aaa/filldisc.php3" onSubmit=" return checkData()">
<table bgcolor=#000000 cellspacing=0 cellpadding=1 border=0 align="center"><tr><td
class="discuss"><table width=100% bgcolor=#f5f0e7 cellspacing=0 cellpadding=5 border=0>
<tr><td class="discuss"><b>Author</b></td><td class="discuss"><input type=text
name=d_author></td></tr>
<tr><td class="discuss"><b>Subject</b></td><td class="discuss"><input type=text name=d_subject
value="_#SUBJECT#"></td></tr>
<tr><td class="discuss"><b>E-mail</b></td><td class="discuss"><input type=text
name=d_e_mail></td></tr>
<tr><td class="discuss"><b>Comment</b></td><td class="discuss"><textarea rows="5" cols="40"
name=d_body ></textarea></td></tr>
<tr><td class="discuss" colspan=2 align="center"><input type=submit value="Send"><input type=hidden
name=d_parent value="_#DISC_ID#"><input type=hidden name=d_item_id value="_#ITEM_ID#"><input
type=hidden name=url value="_#DISC_URL"></td></tr></table></td></tr></table></form>

Site Module

Current APC ActionApps are very good for creation of small or not so complex database driven sites. It was not so easy to create complex websites with many cooperating slices and views, so far. The “site module” is the answer for those, who wants to build complex websites using APC AA.

At the time I wrote the text, the only sites driven by “site module” is the Econnect site http://ecn.cz. ChangeNet site http://changenet.sk and example site on Sourceforge http://action.org/slices/. I describe the site module on Econnect's site. You will see, that the principles are similar to all “site module” based websites.

The site module is part of AA admin interface, just like other modules are. You can access it from 'Switch to' selectbox, if you have permission to. Site module allows you to describe structure of the site – you modify there so called sitetree. Sites based on the module do not need any special files (like shtml, ...) - whole site could be managed using AA admin interface (there is no need for FTP access (with one exception – 'main control script' file described later)). How to describe the structure we will see latter in this text.

Idea - State and sessions

The first estimation in creation of site module was the need to write it as fast as possible. The complex sites used to be sites with many visitors a day. For better performance is good to be able cache the generated pages. However, in “pre-site module” approach each user gets its own session id, which is unique for the user and help us to store the state, where the user user is within the site (which page on page-scroller she is on, ...). It is good, but it is extremely hard to cache such informations. That's why we develop the site module without sessions variables given to each user. We use “state string” instead. There we store the state, where the user is within the website.
State string is variable which we call “apc” (stands for “Application Pointer Cache” :-) the name of this variable is given – it have special behavior inside APC AA (it is automatically added to all links generated by APC AA, for example).
The “apc” variable is added to all links in AA so you every time know, where the user was in step before.
For example: if you get the link http://ecn.cz/index.stm?apc=zzvx1--&..., you know, that user was in “news-alerts-all_categories-all_regions-page1” page on the site. How it is coded into “apc” state string is another thing (and it is in most cases up to you) – will be described in next caption.

“apc” state string

As you can see, the Econnect's apc state string consist of seven state variables – each character in the string is one variable in our case, but it is not a rule (in fact the fifth state variable - “p” - page could be more than one character long). All the state variables are defined in main control file for the site - /module/site/sites/site_xxx.php3 (or its alternative called (for security reasons) through http:// call). In this file you define not only the number of state variables, the regular expression for extraction the variables from apc state string, but you specify there also the ways, how we have to change the state. For example, if the site_xxx.php3 file gets the following url parameter:

http://ecn.cz/index.stm?apc=zzvx1--&p=3

the state variable is changed to apc=zzvx3--, which means that you are on the same webpage, but on the page 3.

Now we describe the variables used on Econnect's site, but keep in mind, that the variables used in your site could be different (if you will).

Position in apc state string

Name of state variable

Possible states of the variable

description

1

w (web)

z,e,n

Main classification of pages – Econnect's pages are divided into three webs:
z – zpravodajstvi (news)
e – econnect
n – nno (NGO related news)

2

s (subweb)

z,m,k,t,a,s (for w=z)
1,2,3,4,5,6,7,8,9 (for w=e)
N,F,P,I,J,V (for w=n)

Each web (w) is divided into subwebs, so for example web z – zpravodajstvi contains:
|z – news
k – comments
t – press releases
...

3

f (filter)

Any letter

Primary use of this variable is to select category of shown items (environment, human rights, culture,...), but each page could utilize this variable for its own purpose (category of grant, job, ...)

4

r (region)

Any letter

The same as f – primary use for region selection

5

p (page)

Any number

Stores the page number, where user is (switched by page-scroller). Could be more than one character long in our case.

6

t (type)

Any letter

Special type of output – like 'text only', 'printer friendly', ...

7

x (item)

Any number

Id of item to show (like 24365) – as you see it could be again more than one character long

You can use any number of any state variables in your site and combine it together into apc state string. The only thing you have to keep in mind is that apc state string must be splittable into state variables. In Econnect's example we are using following regular expression to get state variables from 'apc state string'.

 
{w} {s} {f} {r} {p} {t} {x} ereg( "^([a-zA-Z0-9_])([a-zA-Z0-9_])([a-zA-Z0-9_-])([a-zA-Z_]+)([-]|[0-9]+)([a-zA-Z_-])([0-9]*)", $apc, $vars ))

Main control file

Main control file is the only file you will need to edit in the process of site creation. The file contains script (probably in PHP) and its purpose is just parse 'apc state string' into state variables and possibly change the state of the variables based on the parameters it gets through url.

The script is called before any page of the site is displayed. There is easy, but functional example of such script. All comments are inside.

If $apc is not defined, we probably access the main page (like http://ecn.cz).

if( !$apc )  $apc = 'zzvx--';      # initialize 'state string', if not set, yet

Split $apc state string into state variables (for now prefixed by 'o');

if( ereg( "^([a-zA-Z0-9_])([a-zA-Z0-9_])([a-zA-Z0-9_-])([a-zA-Z_]+)([-]|[0-9]+)([a-zA-Z_-])([0-9]*)", $apc, $vars ))
list($ostate,$ow,$os,$of,$or,$op,$ot,$ox) = $vars;
else # if the $apc is in wrong format, initialize it
list($ow,$os,$of,$or,$op,$ot) = array( 'z', 'z', 'v', 'x', '-', '-');

Now we have to program the reactions on special url requests. Wherever we are in the site and we click on the link containing w=z (like http://ecn.cz/index.stm?apc=zzvx1--&w=z), we change the state to 'news' section

if( isset($w) ) { # w stands for WEB
switch($w) {
case 'z':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('z','z','v','x','-','-',''); break;
case 'n':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('n','N','1','-','-','-',''); break;
case 'e':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('e','1','1','-','-','-','73161');
break;
}
}

The same with state variable s, but we are switching within the same WEB (variable {w} remains unchanged)

if( isset($s) ) { # s stands for SUBWEB
$os=$s;
$ox=''; # $ow stays the same – we change subweb, not web
$op='1';
if( $old_w != 'z' ) # the format in zpravodajstvi stays the same
$old_f='';
}

Write rule for each possible url request.

if( isset($f) ) {$of=$f; $ox=''; $op='1';} # f stands for FILTER
if( isset($r) ) {$or=$r; $ox=''; $op='1';} # r stands for REGION
if( isset($p) ) {$op=$p; $ox='';} # page
if( isset($t) ) {$ot=$t; $ox='';} # switch to special mode
if( isset($x) ) {$ox=$x;} # item id to display
if( isset($scrl) ) { # page scroller
$pagevar = "scr_".$scrl."_Go";
$op = $$pagevar;
$ox='';
}

Finaly, save the final state of variables into $apc_state array. The key 'state' is used for storing new 'apc state string', other keys of the array are variables, which we can use in site module administration (in next chapter). There should be not only state variables, but any other variables which you want to use in site module, as well.

$apc_state = array ('state' => "$ow$os$of$or$op$ot$ox",
'w' => $ow,
's' => $os,
'f' => $of,
'r' => $or,
't' => $ot,
'p' => $op,
'x' => $ox,
# helper variables used in site module – you can define as many such
# variables as you want
'archive' => (($op>10)? 'archive' : ''),
);


You can find example of such file in /modules/site/sites/ directory of ActionApps installation

Site administration

The HTML code for the pages is managed from site administration page. The code is divided into pieces, which is structured into tree structure – called sitetree. The sitetree you can see on the left side of the administration interface. During the displaying of the page, AA starts with the first HTML piece and then goes down and prints the right branch of the tree, based on the state of state variables. The piece of HTML code could contain not only HTML code, but there could be incorporated results of some slice view, as we see later.

We recognize two kind of HTML pieces – 'spots' and 'choices'.

a) spot

spot is HTML code which is simply displayed. AA prints the contents of the spot and then the evaluation continue with the spot just below. On the other hand 'spot' (as well as choice) could be also the root of some branches of code. You can make spot as root of branch by assigning any (decision) variable to the spot. For example, if you assign variable 'w' to the 'start' spot, you create the root of branches (choices). The evaluation will continue in the branch (choice), where w satisfy the conditions.

b) choice

As you see, each choice belongs to a spot, where a 'decision variable' is defined. Each choice has defined a condition for the decision variable. AA prints only FIRST choice, which satisfy the conditions. After evaluation of the chioce (printing the output), AA continues with the spot on higher level of the sitetree.

You can use regular expressions in the conditions. You can also combine the condition for more than one 'decision' variable. The conditions are joined by the logical AND operator.

Incorporating database views into output.

You can use not only HTML cote in the spots, but you can incorporate here the outputs from any slice. The slice output is always controlled by view in site module (we do not use Fulltext or Index in site module). To include slice output use the following construct:

{view.php3?vid=353}

This includes in the output the result of view number 353. Although the {view.php3...} is just language construct (it have only a little to do with view.php3 file), we can use all the well known parameters we know from view.php3. So, the following example is the one, we surely use in our site for displaying the fulltext of the item x:

{view.php3?vid=217&cmd[217]=x-217-{x}}

As you see from the example, we can use another language construct {x}, which is substituted by the content of variable x (x is the state variable defined in 'main control file' in $apc_state array).

Language construct to be used with site module

Syntax

description

{<variable>}

Returns content of variable (like {w})

{view.php3?vid=<vid>&<view parameters>}

Returns content of view <vid>. View uses the <view parameters> just like the view.php3 script. (like {view.php3?vid=122&cmd[122]=c-1-{f}} )

{switch(var1,var2,..)val1,val2,..:<printed text1>:val1,val2,..:<printed text2>}

Returns <printed text1> or <printed text2> or ... based on conditions val1,val2 for variables var1, var2, ... The only first matching text is printed. You can use regular expressions in conditions. (like {switch(w)z:News:e:Econnect:.*:NGO} )

{# any text}

Comments – no output is printed

The construct could be nested – the level of nesting is unlimited.

If you are using highlight field for displaying items on homepage and you want to allow people to be able to switch the highlight on and of quickly, then Live checkbox is the solution for you. It allows you to display checkbox directly in Item Manager, so users just check or uncheck in there. They do not need to go in item editing page and edit each item.

How to set it up
  1. Go to 'Slice Admin' -> 'Fields' and choose 'Edit' for field you want to use live checkbox (probably highlight....... or other Boolen field)
  2. Set alias (for example _#LIVECHBX) using f_k - Auto Update Checkbox
  3. Go to 'Slice Admin' -> 'Design - Item manager'
  4. Incorporate new alias (_#LIVECHBX) into Item Manager design
  5. Done

In Slice admin interface form for configuring fields there is an input box for parameters of insert function. For field with insert function "File = uploaded file", you can set these parameters:

        type of file : maximum image width : maximum image height : secondary image fields delimited with ## separator

Example:

if you insert parameters:
        image/*:450:600:image.....1##image......2
function will do these actions after submitting the item/article:

Limits of the function:

Setup your slice as normal, got to Slice Admin -> Views -> type:RSS News.

You can edit the feed to more precisely pick what you want for each item. Use the _#RSS_* aliases to refine it.

The URL of the RSS feed should be at /apc-aa/view.php3?vid=xx

When we setting up aliases for database field on se_fields.php3 page, we sometimes need to change the behavior of alias in som way or we need to pass some parameter for alias handling function such as f_f. The Parameters field is the right place, how to do it. The list of parameters for each alias function follows.
In some cases we need to pass more than one parameter to alias function. In such case the aliases are separated by colon character. If we need to use colon inside parameter, we just use #: string instead of : character.

FunctionParameterDescription
f_xtransformation
content value (pairs) pairsthe content of the field and the value to return, the content can be a regular expression as in http://www.php.net/manual/en/ref.regex.php
default value returned if no match
f_0null function (nothing shown)
none
f_hprint field content due to html flag set (escape html special characters or just print)
delimeterif delimeter parameter is specified, the field with multiple values are displayed as list, delited by delimeter
f_dprints date in user defined format
formatformat string just like in PHP (like "m-d-Y") - see PHP manual
f_iprints image scr (<img src=...) - NO_PICTURE for none (the functionality of this alias function can be created as conditional f_c function as well)
none
f_nunpacked id
none
f_gprints image height atribut (img height=...) or clears it (the functionality of this alias function can be created as conditional f_c function as well)
none
f_wprints image width atribut (<img width=...) or clears it
none
f_aprints abstract or grabed fulltext text field
lengthlength - number of characters taken from field_id (like "80:full_text.......")
field_idid of fulltex field
f_fprints link to fulltext (hedline url)
link_onlyfield id (like "link_only.......") where switch between external and internal item is stored
redirecturl of another page which shows the content of item (like "link_only.......:http#://www.ecn.cz/articles/solar.shtml") (note the #: in previous example!)
this page should contain SSI include ../slice.php3 of course
f_bprints text with link to fulltext - more general version of f_f function
param: link_only:url_field:redirect:txt:condition_fld (hedline url)
link_onlyfield id (like "link_only.......") where switch between external and internal item is stored
url_fieldfield id of external url for link_only
(like hl_href.........)
redirecturl of another page which shows the content of item (like "link_only.......:http#://www.ecn.cz/articles/solar.shtml") (note the #: in previous example!)
this page should contain SSI include ../slice.php3 of course
txtif txt is field_id content is shown as link, else txt
condition_fldfield id - if no content of this field, no link
additionadditional parameter to <a tag (like "target=_blank")
f_tconverts text to html or escape html (due to html flag)
none
f_sprint database field or default value if empty (the functionality of this alias function can be created as conditional f_c function as well)
defaultdefault value (like "javascript: window.alert('No source url specified')")
f_lprints field as link, if field_id in $param is defined, else prints just field
field_idfield_id of possible link (like "source_href.....")
f_ehttp://actionapps.org/aa/admin/itemedit.php3?AA_CP_Session=f48237b26098d261a71de80ded1c49c4&edit=1&encap=false&id=6525acb6a0ceb34e3db375618efe19f0 used on admin page index.php3 for itemedit url
none
f_cprints "begin".field."end" if field="condition", else prints "none"
if no cond_col specified - this $col is used
condition can be reversed (negated) by "!" character at the begin of condition
param: condition:begin:end:none:cond_col
condition
begin
end
none
cond_col
Example: 1:Yes<!--:-->:No
This example is usable for example for Highlight field - it shows Yes or No depending on highlight field
Example: !:Email#:::
If e-mail field is filled, it shows "Email: email@apc.org" (for example), but if it is not filled, it shows nothing
f_ucalls user defined function (see How to create new aliases)
functionname of called function in include/usr_aliasfnc.php3 file
parameterparameters passed to function
f_mmailto link - prints: "begin<a href="(mailto:)$col">field/text</a>"
if no $col is filled, prints "else_field/text"
begintext before link (for example "e-mail")
field/textif field id specified, the field is used as link text else the text is used insteed.
else_field/textif no e-mail addres specified in $col, the field content (or text) is displayed
linktypemailto / href (default is mailto) - it is possible to use this function for links, too - just type "href" as last parameter
i_simage size and other properties - as default prints: 'height="xxx" width="yyy"', where xxx and yyy are the height and width of the image in pixels. Other properties can be printed as well.
Returns empty string if it cannot determine the width or height.
information
  • html (default) - returns image size as HTML atributes (height='xxx' width='yyy')
  • width - returns width of image in pixels
  • height - returns width of image in pixels
  • imgtype - returns flag indicating the type of the image: 1 = GIF, 2 = JPG, 3 = PNG, 4 = SWF, 5 = PSD, 6 = BMP, 7 = TIFF(intel byte order), 8 = TIFF(motorola byte order), 9 = JPC, 10 = JP2, 11 = JPX, 12 = JB2, 13 = SWC, 14 = IFF, 15 = WBMP, 16 = XBM
  • mime - returns mimetype of the image (like 'image/gif', 'application/x-shockwave-flash', ...)
f_yExpanded string: expands the string in the parameter.
If you need use aliases in a database field. It can be used e.g. for including photographs from the slice "Photogallery" to the field "full_text......." in the slice "Articles". See an Example.
string to expand If specified then this string is expanded, if not specified then expands the contents of the field.


The slice.php3 is the main script used to display items from database. The alternative for this script is view.php3. The main ussage of slice.php3 script is to include it into some .shtml file by the SSI include command - like:

 <!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6"-->

The following parameters you can add just like url parameters. It is possible to combine more than one parameter. Example:
<!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6&listlen=10&no_scr=1"-->

The slice.php3 is there from the beginning of ActionApps, so some of the parameters are quite old. Such parameters are still implemented, but in many cases it is better to use newer - more powerfull substitution for the parametr. That's why the list is prioritized from the most common parameters (which should be used) to the old parameters (which use is deprecated).

The only way, how to display data from slices, where 'Reading Password' is set. See: http://apc-aa.sourceforge.net/faq/#slice_pwd
ParameterRequiredDescription
slice_idYesid of displayed slice
conds[]Novery usefull for complex conditions - see How to setup the searchform? for conds parameter setting (it can be used as url parameter too - not only form Forms, as described in search section)
Example:conds[0][category........]=Environment&conds[1][category.......1]=Waste
defaultCondsOperatorNoreplaces LIKE for conds with not specified operator - simplified syntax of conds[] uses LIKE operator as default - you can change it by this operator to RLIKE for example (RLIKE is better in many cases - at least it is much faster from database point of view)
Example: defaultCondsOperator=RLIKE&conds[0][category........]=Environment
neverAllItemsNoif set, don't show anything when everything would be shown (if no conds[] are set) - good for search pages, where on the top (or bottom) is searchform - normaly, for the first time (when you did not send the searchform), all items are shown - if you want to have there only blank page intead, use this parameter
sort[]Nosee conds[] - very usefull for complex sorting
Example:sort[0][pub_date........]=d&sort[1][headline........]=a
(a ...ascending order; d ... descending order)
xNothe same as sh_itm, but short_id is used instead (implemented for shorter item url (see 1767 alias))
iviewNochanges the design of index item listing to the design defined in specified view. The view should be of 'Item listing' type.
Example: iview=49
- listing of items generated by slice.php3 will use format-strings as defined in view No. 49
fviewNochanges the design of fulltext to the design defined in specified view. The view should be of 'Fulltext view' type.
Example: fview=48
- the item displayed by the slice.php3 script will use format-strings as defined in view No. 48
dviewNouses specified view for discussions instead of the one specified on 'Slice Admin' -> 'Design - Fulltext' page. (good for testing new discussion view, ...)
Example: dview=18
- view 18 is used as tepmlate for discussion design in this slice
listlenNochange number of listed items in compact view
Example: listlen=10
slice_pwdNo
Example: slice_pwd=VerySecret
no_scrNoif true, no page scroller is displayed
Example: no_scr=1
group_nNodisplayes only the n-th group (in listings where items are grouped by some field (category, for example)) - good for display all the items of last magazine issue
Example: ( group_n=1 )
slicetextNodisplays just the text instead of any output - can be used for hiding the output of slice.php3
Example: slicetext=%20
highlightNowhen true, shows only highlighted items in compact view
Example: highlight=1
als[alias]Nouser alias definition - you can define your own aliases in url (for both - slice.php3 and view.php3). Aliases names MUST!!! be 8 characters long. Don't forgot, that the alias value have to be urlencoded.
Example: als[MY_ALIAS]=Summary%20Page (or maybe better: als%5BMY_ALIAS%5D=Summary%20Page)
defines alias _#MY_ALIAS. If used in formatstring ('Admin - Design Index' for example), it prints 'Summary Page'
incNofor dispalying another file instead of slice data (for example some static html file)
Example: inc=/contact.html
items[id]Noarray of items to show one after one as fulltext (ids are the long ones - see sh_itm, but there is special 'x' character before each index).
Example: items[x5462876e8ab29ac95462876e8ab29ac9]=1&items[x65ac876e8a555b29543ea76e8ab29a34]=1 (doesn't matter which value is given to element (1 or 'on' or ...) - good for display of the form, where you select which item to show)
hidefulltext=1Noif you add this parameter to url, the fulltext is not shown when you go to page, where the specific item should be displayed. The discussions under the fulltext are not hidden. It is usefull, if you want to show discussions for the item on separate page. On the other hand, probably better results You can get by using fview parameter.
banner=2-38Noby this parameter you are able to display any view (38 in or case) inserted just after the second (2) item in view (number 23). The item shown in inserted view (38) is selected randomly, possibly with weight specified in weight field (number.........1) - just like in random parameter described above. If you do not want use random item (banner), use 'norandom' keyword in place of 'weight field' (good for displaying nested newsbox). See also banner parameter for view.php3. The example of included banner is on http://ecn.cz.
Example: banner=2-38 or banner=2-38-number.........1 or banner=2-38-norandom
nocache=1NoURL parameter for page refresh - the items are not taken from cache (- no matter if allready cached or not). Cache is updated.
searchlogNoif you add searchlog parameter to the slice.php3 script on some search page, all searches (by conds[]) are logged into database table searchlog. There are logged not only the conds[] parameters, but also the time, which database spent on the query. The access to the log is for superadministrators only, right now. You will find it on 'AA' -> 'Misc - View SearchLog' page in AA admin interface (or you can look into searchlog table in the database).
scr_url=script_nameNoscr_url parameter is answer to problem mentioned in apc-aa-general mailinglist (apc-aa-general mailinglist). If you try to include the slice.php3 into your php3 script by calling include("http://www.sitename.org/apc-aa/slice.php3...");, the page scroller do not work, becouse the called script (slice.php3) do not know from which script it was called. But the scroller should know it - scroller should point to the same page - to the calling one. By scr_url parameter you can define the name of calling script.
Example: include("http://www.sitename.org/apc-aa/slice.php3?...&scr_url=%2Fscripts%2Findex.php");
('%2F' stands for ' / ' character).
sh_itmNoid of item to show - if specified, selected item is shown in full text
Example: index.shtml?sh_itm=01ac1b10fae13c0a61c5292ba72d70b1
restrictNofield id used with "res_val" and "exact" for restricted output (display only items with "restrict" field = "res_val"
Example:restrict=category........&res_val=Environment&exact=1
res_valNosee restrict
exactNoif set, restrict field must match res_val exactly (=) otherwise substring is sufficient (LIKE '%res_val%')
orderNoorder field id - if other than publish date add minus sign for descending order
Example: order=headline........-
timeorderNoif rev - reverse publish date order (less priority than "order")
Example: timeorder=rev
scr_goNosets page scroller to specified page
Example: scr_go=2
encapYes for not encapsulateddetermines wheather this file is SSI included to .shtml file (<--#include virtual="... ) or called directly as slice.php3
Example:encap=false
cat_idNoselect only items in category with id cat_id
Deprecated - better to use restrict and res_val parameters - or even better conds[] parameter
cat_nameNoselect only items in category with name cat_name as substring
Deprecated - better to use restrict and res_val parameters - or even better conds[] parameter
srchNotrue if this script have to show search results
Not supported from AA v1.5

The script cron.php3 - similar to Unix cron - is able to run PHP scripts on given time. If you want to send e-mail notifications if some condition is satisfied or if you want to exchange items between slices regularly, you will find it useful.

The reason for this script to exist is that it's not easy to run PHP scripts by the Unix cron. It also allows us to use admin interface (AA -> Misc - Cron) to add/modify new tasks to run.

If you want to run some task on given time (like running admin/xmlclient.php3 for Cross Server Item Exchange each 15 minutes), you have to do two steps:

  1. add new task on cron admin page (AA -> Misc - Cron)
  2. make you sure the cron.php3 is periodically started from unix cron

1. Add new task on cron admin page

The task you can set/edit on cron admin page (AA -> Misc - Cron). The fields (their names are taken from PHP getdate()) have the following meaning: Let's call time units all from: minutes, hours, mday (month day, 1-31), month, wday (week day, 0-7, where 7 and 0 both mean Sunday). You may use three-letter month and week day names (like "jan","feb","sun","mon"). A time unit may be set to:

* not set - jump over this field
10 number: run only when time unit equals
1-5 range: run when time unit equals 1 or 2 or 3 or 4 or 5
0-59/15 range with step: run when time unit (minutes in this case) equals 0 or 15 or 45
5,15-25/5,40 you may combine numbers, ranges and ranges with steps, separated by comma

The task table is allready prefilled on APC ActionApps setup, so you should see something like:

time                 script                       params
* 1          * * *   misc/alerts/alerts.php3      howoften=daily&lang=en      (Alerts - daily diggest)
* 1          * * 1   misc/alerts/alerts.php3      howoften=weekly&lang=en     (Alerts - weekly diggest)
* 1          1 * *   misc/alerts/alerts.php3      howoften=monthly&lang=en    (Alerts - monthly diggest)
* 1          * * *   misc/alerts/admin_mails.php3                        (Alerts - sending of subscription e-mails,...)
* 8,23,38,53 * * *   admin/xmlclient.php3                                (CSN - Item Exchange)
(it is just an example - the set of task could be changed in next release of ActionApps)

2. Start cron.php3 periodicaly from unix cron

This must be done by a system administrator (i.e. someone with root shell access), but only has to be done once no matter how many task are sheduled then.

In order we can shedule tasks from ActionApps we must run periodicaly the script cron.php3 (based in root apc-aa install directory). It is not so easy to start php scripts directly from unix cron, that's why you should use aa-http-request shell script (based in misc/ directory), which will start cron.php3 script for you.

The instructions for setup of the aa-http-request script is also inside the script. For setup follow the nex few steps:

Here are some links you may find useful and interesting:


Detailed, fictional, case studies of uses of apc-aa:
* http://www.apc.org/actionapps/english/general/uses.html (in english)
* http://www.apc.org/actionapps/espanol/general/uses.html (in spanish)


If you are an APC member, I _strongly_ recommend you read the
APC ActionApps Product Development Guidebook. Find it on:
* http://intranet.apc.org/ (password protected)


If you use ActionApps regularly, joining the apc-aa-general
mailinglist is a good idea:
* http://sourceforge.net/mail/?group_id=6341


Here is some additional, less focused, background reading:


PLANNING


(article) Overview of planning a database-backed website (long)
http://www.techsoup.org/articlepage.cfm?ArticleId=375&topicid=13


(list of links) Web-site Management
http://www.itrainonline.org/itrainonline/english/management.shtml
There was changed behavior of string removing in AA v2.6. Now we use much easier steps:
  1. unalias (expand) whole text (replace aliases and any other AA expressions)
  2. remove all specified remove strings
Following worked in AA v2.4 and less, so now is OBSOLETE

Removing of stings works before alias substitution - it never replaces the text filled by user in the field. If you have

=> _#HEADLINE (_#AUTHOR##)

and remove string "()", than it first looks for empty alias content and then removes such aliases.

Let _#HEADLINE = "Hi Ann"
and _#AUTHOR## = "" (empty)

In first step the emtpty aliases are removed:

=> _#HEADLINE ()

Then the "remove strings" are removed:

=> _#HEADLINE

and then the remaining aliases are substituted.

The ? only shows if their is a URL in the morehelp field. This is setup automatically to be http://aa.ecn.cz/aa/doc/help.html.

You can remove it on fields individually via Admin->Fields->anyfield -> More help and deleting the text which is there.

If you are too lazy to do this on every field, then ask your system administrator to run:

UPDATE field SET input_morehlp='' WHERE input_morehlp = 'http://aa.ecn.cz/aa/doc/help.html'

For future refence, the function that creates this link to help is in include/formutil.php3 : function PrintMoreHelp

The Rich Text Editor is a powerful editor allowing to copy content from web pages by copy-and-paste.

Most of the icons used to format your text are self-explained. On the first row in the right half there are icons for table creation and manipulation.

The rightmost icon on the first font switches between Wysiwyg and HTML view, allowing to see and modify your HTML code.

The sweep icon near the font size selectbox is a "<font> eraser". It clears all <FONT ...> and </FONT> tags in your HTML code which is useful when cleaning code copied from some web page. You can find a description of each Field Type and of each Alias Function in the Admin Interface (Slice Admin / Fields / Edit) by clicking on the Param Wizard link at the left of the select box.

A complete list of all Field Types and Alias Functions is now available as well.

With the concept of Reader management slices introduced it is important that some data are not accessible for reading. This is achieved by setting a reading password for slices containing sensitive data. If you fill the field "Reading Password" in Slice Settings, you must always sent this password as a parameter slice_pwd. This may be done by adding this parameter to SSI includes like

<!--#include virtual="/aa/slice.php3?slice_pwd=the_password&slice_id=xy...."-->

If somebody tries to fetch read-protected data without the correct password, all fields are filled with an error message.

If you are interested, the password is prooved in the GetItemContent() function. For AA control panel pages (Item Manager and Item Edit), the function FetchSliceReadingPassword() is used.

In AA v2.6 or current CVS is introduced Reader Management slice and Auth Module. Users for Auth are stored in slice and each user is in fact slice item. So, you can create standard anonymous posting form into the "Reader manager" slice to allow user subscribtions.
You can set the form to put new users (=items) to holding bin, so they have to wait for your approval - just like in normal slice.
There is no possibility (at this moment), how to add common Authors or Editors to AA permission system from public webform. This is a common request, and unneccessarily complicated, (suggestion to developers - create a function like f_b might be created at some point to do this more easily, or just add an "Else" field to f_b)

note, that you cannot use this if you also use the Headline URL to point to a file - you would get a link to that file instead, in this case create a new alias like ?x=1718 but with blank parameters.

Also note that inside a view, you'll need to use the URL as defined in the FAQ

The File Manager enables Slice Administrators to modify their web pages on-line in the AA Control Panel. It appears only when an superadmin sets so in Slice Settings. The File Manager settings are hidden to anybody except superadmins. See File Manager Administration for more details.

Most of the features of the File Manager are very common:

If the superadmin creates some web templates, a select box "Copy template dir" appears. Templates are groups of web files which are copied to your root directory. If there is a file name conflict (a file with the same name already exists), the template is not copied and an error message appears. Rename or delete conflicting files. You can access and modify all the template files after you have copied it.

For most feeds you won't need to map them, unless you want the feed to go to Active rather than Hold bin.

To set the mapping, first create the feed in AA->RSS Feeds, then click on the feed and click Map. (or go to it directly from the AA->Mapping page.

If all you want to do is send it to the Active bin, then go to the bottom and change "Status" to "Value" and "1" (hold is "Value" and "2")

You can set quite complex feeding behavior by setting any field to "RSS field or expression" and then entering an RSS field name, or more complex expression.

Fields have a prefix and a value e.g. DC:TITLE, the allowed fields are:
PrefixAllowed ValuesWhere found in RSS
CHANNEL/ title, description, language, timestamp (AA only), link From the corresponding CHANNEL elements at the top of the feed except slice_id is from dc/identifier
ITEM/ title,description,link,id, guid, pubdate From the corresponding ITEM elements except id is from dc/identitifier)
DC/ title,creator,subject,description,date,source,language,relation,coverage From the corresponding DC elements within the ITEM

In addition, the following syntax is supported:

ITEM/DESCRIPTION|ITEM/TITLE Will look for the Description, and if that is not present use the title
DATE(ITEM/pubdate) Converts the specified field to a unix date
NOW Uses the current date and time
CONTENT Hard coded to find the content and determine if its HTML, given that the RSS standard makers keep moving things! Currently it looks in Item/encoded and and Item/items/bag/li/item/value
headline........ Will look for an APC-AA field, this only works if the sending RSS feed is from APC site, in which case Inter-node feeding would be better anyway.

Notes to Developers

It is relatively straightforward to modify RSS import as the standards mutate

f_v takes a parameter on which certain substitution is done.

 

This FAQ interface was developed by Jason at Commons.ca

APC: Internet and ICTs for social justice and development APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC)
APC - Internet and ICTs for social justice and development