APC Action Applications - Home Page

Frequently Asked Questions v2

 

_#BROWSETL

0. What are ActionApps?
1. What's the benefit of Content Pooling?
2. Who can I create a Content Pool with?
3. How do I get ActionApps?
4. What specific ActionApps are available?
5. Where do I go for user support?
6. Is there a manual available?
7. Error: setup.php3 just recycles the same page
8. How to create an aa in an alternate language?
9. Is my information protected?
10. Can the APC ActionApps work in my language?
11. Do I need special computer qualifications to use the APC ActionApps?
12. Can the APC ActionApps infect my computer with viruses?
13. Who will read my information?
14. How can my APC network help me use APC ActionApps?
15. Are APC ActionApps open source?
16. Password-protected public editing
17. File Manager Administration
18. How can I let users with the 'author' permission edit their own items?
19. How do I upload files into a slice
20. How to make item url shorter?
21. Alerts/Mailman Integration
22. What are the plans for the FAQs?
23. How to import big exported slice&data?
24. What is Reader Management?
25. Where is the HTML
26. How does ActionApps compare with PHPNUKE, Zope, and other content management systems.
27. 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?
28. How to use aliases
29. How do I control whether new items appear in the Approved or Holding bins
30. What are the 'Action Aplication Core' and 'News (EN) Template' slices?
31. How do I use add one of the fields in the drop-down at hte bottom of the Admin->Fields screen
32. Rich Text Editor
33. Jump module
34. Create new Wizard
35. How to show integers but not show 0?
36. What is the value of a check box input?
37. How to push/pull data into/from database
38. How to refill conditions on searchform?
39. Searchform extensions
40. How to setup searchform?
41. How can I modify the fonts used in the AA interface?
42. How to use images in a slice ?
43. How does a user retrieve a forgotten password from reader managment?
44. How to display archive (expired items)?
45. How do I create a Reader Mamagement logout function?
46. How are mutual related links propogated?
47. How do I set up Htaccess permissions sync with Reader Management?
48. How to transform the old slice (from AAv1.2-) to the new database structure (used in AAv1.5+)?
49. AA Alerts
50. Alerts step by step walkthrough
51. Alerts Admin
52. How should I return errors
53. two level menu view
54. ERROR: "No slice found for you" - I lost me installation ID ("AA_ID" in config.php3)
55. Constants and Categories
56. What is the parent category?
57. How do I customise the Category breaks in an index view from another slice
58. Hierarchical constants
59. How to integrate APC-AA with email
60. How "No item found" message in view definition works?
61. When are hits counted?
62. Is there a way to allow different users to log in to the same slice but with their own language choice?
63. How to create a simple email alert module
64. How can I include photos to the texts of articles?
65. MultiLingual eXtension for ActionApps / How to setup ActionApps for multilingual web sites
66. How to import lots of data into a slice?
67. What tools are available for importing data
68. How do I make a slice with lots of fields? The web interface takes too long.
69. Which should I use, Item Listing View (View.php3) or Design-Index (slice.php3)?
70. What are Views good for?
71. How to display icon for Highlighted item on Item Manager (or public website)?
72. How do I create a Index of some items
73. How do I include this View in a HTML page?
74. How do I sort items within a View?
75. How do I include Previous and Next in the scroller of a View.
76. How do I select a sub-set of items from a view
77. How do I view just highlighted items on a page.
78. How do I make it view just a single item?
79. How do I link a Index view to show the items in a Full Text view
80. What is a Static View and how do I use it
81. How can I parameterize a view and fill in details from the URL
82. How can I change a piece of content on a page, for example a context-dependent Navigation menu
83. How can I use the related items feature to link items from one slice into another
84. How do I use a Javascript view to see pages on a site where AA is not installed
85. Which parameters can I use with view.php3
86. What are the wizards for parameter generation, and how do I use them
87. How to create a Calendar
88. Field Triggers
89. What is Content Pooling?
90. How do I automatically feed only select items to other slices?
91. How to set the off-line filling up?
92. How to edit items in public website?
93. How to create a form allowing anonymous posting from public website?
94. How to edit items non-anonymous from a website
95. How do I use jsview.php3 to view pages on a site where AA is not installed
96. How do feed items from one slice to another
97. How can I control which fields are fed, and whether they are editable
98. I want to feed highlighted items from several slices to the front page.
99. How to setup Cross server networking (CSN)
100. Feeding: How to access the id field in a parent
101. How can I set mapping on Manual feeding.
102. How to link parent item?
103. What are the different kinds of Views on the Admin->Views page?
104. How do I update my APC-AA installation to the latest version?
105. Designing nice search results
106. Discussions as message boards
107. How do I setup discussions?
108. How to use Site Module
109. How to use Live checkbox (Auto Update Checkbox)?
110. Error: Access denied for user: 'aadbuser@xxxx'
111. What can ActionApps do for my organization?
112. What are real world examples of organizations using ActionApps?
113. How can I manipulate images (e.g. create thumbnails)
114. How do I create an RSS feed from a slice
115. What are the Parameters of the Alias Functions
116. Which parameters can I use with slice.php3
117. How to create new alias function?
118. Cron - how to automatically run tasks on given time?
119. What are the hosting requirements for APC-AA?
120. Where can I read about developing APC-AA applications
121. How much do ActionApps cost?
122. How to contact the developers
123. How to create a new Action Aplication
124. If I am a developer, how can I contribute?
125. How to edit a file and check it back into the distribution
126. Can I run APC-AA on two web servers accessing a common database
127. What are the CVS branch version numbers of APC-AA and how do I check out a specific versio
128. I have limited access to my box, how do I access PHPLIB
129. How do I create my own validation function
130. Can I call apc-aa item-manager from other php3 code
131. How do I fix a corrupt database
132. Which strings exactly are removed from Views?
133. Can I run APC-AA with IIS and Windows
134. How do I get rid of the "?" by each input field
135. How can I look at the database with Perl?
136. Rich Text Editor icons
137. How do I setup my installation for file uploads
138. How does file upload work
139. Language files with Mini Gettext
140. Using remote or remotec to display APC-AA on another web server
141. How to create new module?
142. Field Types and Alias Functions
143. How to configure mod_auth_mysql for HTTP authentication with ActionApps authentication system
144. What coding standards should I follow
145. How to debug Action Apps code and sites?
146. POST to .shtml
147. Protecting sensitive data against reading
148. Is it possible to add new users from public website?
149. How do I link to fulltext if, and only if, there is some fulltext
150. How do Tagged IDs work
151. File Manager
152. How do I set mapping on RSS import
153. What paramater substitution is done in f_v

ActionApps are publishing tools that plug into websites. With ActionApps, publishing news and information online is as easy as filling in online forms. Their unique Content Pooling technology enables organizations to exchange articles between their sites. For more details, see About ActionApps .

There are two general kinds of benefits:

  1. Content - Pooling can give you access to a fresh stream of content for your site (in the form of your partners' articles); and
  2. Publicity - Pooling can help you get your own content out to new audiences (whenever you partners reprint your articles).
You can create a content pool with any number of partner sites. All of your partners must be subscribing to ActionApps with the same APC provider. ActionApps are offered as site plug-in services by individual members of the Association for Progressive Communications (APC). The APC itself does not offer ActionApps services directly. To find an APC provider near you, go to Get ActionApps Different APC providers offer different services based on the ActionApps platform. In general, most APC providers can offer a solution for publishing events, news, action alerts, press releases, contact lists, and similar articles/listings. For specifics, ask your APC provider. Only the service provider providing your ActionApps can support the service. This is likely to be an APC member. The APC itself cannot directly support individual ActionApps users. Yes, there is. It is currently available in English and will shortly be available in Spanish. Visit our downloads section to get your own copy to print out, or read it online.

If hitting "Init" on the setup.php3 page just comes back to the same page, then its probably because your php.ini file contains

"register_globals = Off"

set this to On and restart Apache.

See the manual section 3.7 for instructions.

If you want to translate the ActionApps to another language, you can look at:

The information you post on the WWW using AA is equally secure as it is without it. Permissions of the users of ActionApps are individually defined, and unless you give your password out, or you choose a too trivial password that is easy to guess, your items are only available (for republishing) to those whom you deliberately share them with. Yes. It is the responsibility of your local APC service provider to create local language versions of the applications. The software is specifically designed to flexible language management. No. You can handle every aspect of the work by using a Web browser (Netscape or Internet Explorer), and simply copy and paste (or type) text. When setting or changing the layout of your application, an html (Web editor) expert is needed, but your APC provider can give you the necessary assistance.

No. ActionApps use only HTML (web) files, which cannot contain viruses. If an item in somebody’s application contains a link to a downloadable file (word document, excel sheet, image or sound files, etc.), those files my be infected just as any other file of those kinds, which are downloadable from any sorts of Websites.

Your information is posted on an Internet Web site, where any Internet user can read it who learns about its address (unless you use ActionApps for internal purposes in a Web site, where readers access is password protected). The advantage of using ActionApps is that posted only once, your information can become available on several Websites and can get more publicity.

APC members in general, provide the following assistance in using ActionApps. This assistance can include: Yes, the ActionApps are licensed under the GNU General Public License. This means you can install the software for free on your own server. It also means you can make modifications or upgrades. These modifications can either be submitted for integration back into the main Action Application code or released as separate modules. Either way, modifications to the ActionApps must be released for public use under the GPL.

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).

New settings in config.php3

# mkdir perms, set by variable because constants don't work with octal values $FILEMAN_MODE_DIR = 0770; # create file perms $FILEMAN_MODE_FILE = 0664;
define("FILEMAN_BASE_DIR","/www/apc-aa/wizard/");
define("FILEMAN_BASE_URL","http://work.ecn.cz/apc-aa/wizard/");
define("FILEMAN_UPLOAD_TIME_LIMIT",600);

FILEMAN_MODE sets the Unix rights for all files and directories maintained by the File Manager. Specific directories for individual slices are created in FILEMAN_BASE_DIR, specify the name of the directory belonging to a slice in Slice Settings (only superadmins!!). The FILEMAN_BASE_URL is the web path to the FILEMAN_BASE_DIR, and FILEMAN_UPLOAD_TIME_LIMIT (in seconds) is useful when uploading large files.

Slice settings

Superadmins can set for each slice if administrators may access the File Manager and set the directory name. A directory name must be filled in order that administrators may use the File Manager. If the directory does not exist, it is created at the first usage of File Manager.

There is a difference between what a superadmin sees and what a slice administrator sees. The base directory for superadmin is FILEMAN_BASE_DIR, so you see the directory name when entering File Manager and you can jump to the parent directory. But slice administrators have access only to the particular directory and they don't see the directory name.

Templates

You can create templates consisting of several files. Some aliases are defined:

Create the templates in directory FILEMAN_BASE_DIR/templates, each in another subdirectory. Use the AA admin / Wizard Templates page to fill info about the templates into database. Write the subdirectory name (without path) and a description.

 

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.

Why are slice IDs and item IDs so long?
Would it be possible to make them shorter?

The 32-digits hexadecimal IDs are quite standard in MySQL/PHP - see uniqid() and md5() functions. These identifiers are intended to be unique worldwide so that each item has an unique ID regardless of where it is stored, such as on Econnect's server or on Colnodo's. This feature helps us in cross-server feeding.

Internally (within the database) the IDs are stored as 16-character strings (for disk-space savings and a little better performance of the database), but this is only important for developers.

Because of long URLs, I made short_id in v1.8 - so that the auto-incremented short IDs are used by default. The URL for an item is now, for example:

http://kalendar.ecn.cz/index.shtml?AA_SL_Session=44ca275c691 842965745f90ab9aee24e&x=27968

or, even better:

http://kalendar.ecn.cz/index.shtml?x=27968

From Mitra (mitra[at]earth.path.net):

I am using alerts/mailman integration, - its one of the most painful AA admin procedures, basically you have to create an alert that goes to a mailman group. Here are the steps (note that I've SIMPLIFIED it, removing sub-steps).

This presumes you have:

  1. In the slice you want to send mail from:
  2. Create Alerts Slice and change settings as follows
  3. Go to mailman, create a mailing list - set yourself (a human) as the owner, set to moderate new subscribers
  4. Go to your Reader Management slice (see note)
  5. Now try and add an item to your slice,

Note that in practice you can only have ONE functioning reader management slice in an entire AA installation since it has email unique - apparently there are historical reasons for this, but it is unclear if there are current reasons.

This is essentially an admin nightmare, do anything even slightly wrong and the mail won't go through, and its very hard to debug.

I believe this could and should be dramatically simplified, we don't have the development resources to build our own mailing list manager in competition to all mailman's functions, better would be to allow an Alerts View to send mail direct to a mailing address - typically the email address of the mailman list.

Next suggested steps for the upgrading the FAQ:

  1. Fix old links within fulltext.
  2. Categorize and fix grammer in all articles
  3. Get popular collections view working (uses related items) and ask key users to submit their favorite collections.
  4. Add more content from email archives and personal notes.
  5. Add email alert feature
  6. Allow for editing on site for logged in users.

Also need to get other language views and content going (e.g. Spanish).

I also plan to create a Requested Feautre slice in the near future that will use the same alert login.

Some help with updating FAQ content would be most appreciated. :^)

 - JD- - - --

We have slice data and structure exported to AA.XML file and we want to import it back to the AA. The problem is, that the AA.XML file is 24 MB.

The solution:

The problem could be in PHP setting. Here's what I had to change in php.ini file to get it going:

1. post_max_size: increased from 8M to 32M
2. upload_max_filesize: increased from 2M to 32M

Those first two were key -- from the php log the upload was clearly exceeding both of these parameters. Obviously, if the upload was bigger than 32M (ours was about 24M) this might need to go even bigger.

I also increased these others. I think the upload wouldn't have completed in the default times, but I'm not sure which parts of the operation count towards which of these:

1. max_execution_time: changed from 30 to 120 seconds
2. max_input_time: changed from 30 to 120 seconds
3. memory_limit: changed to 32M

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:

Mark Surman wrote a good comparison 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.

External SQL query should look like:

SELECT * FROM item, content
  WHERE item.id = content.item_id                // to join the tables
      AND item.id = 'hey67s[o0-78z._d'           // 16 characters long packed id
                                                 // see util.php3 - q_pack_id()
      AND content.field_id = 'headline........';

This SQL query select all fields from item table (where are stored just the most common item fields - id, short_id, slice_id, status_code, post_date, publish_date, expiry_date, highlight, posted_by, edited_by, last_edit, display_count, flags, disc_count, disc_app, externally_fed) plus the content of 'headline........' field from content table (will be in content.text field). You can change 'headline........' to any field id, of course, just like 'category.......1' or 'source.........1'. Also you can use short_ids as well to identify the item.

Database structure used for items

Data for an item is not stored in one table, as it is obvious and as you probably expect. Data are divided to two tables - item and content. Item table stores the common fields, which is requiered for each item. All other columns are sored in related table content (relation 1:N). The content table is quite easy - item_id, field_id, number, text, flag. Each row holds contents (in 'text' or 'number' filed) of one field (identified by field_id - like 'headline........') for one item (identified by 'item_id' - related to id in 'item' table).

Such, say 'virtual table database structure' or 'object oriented database' allows to store items of any number of fields. It also allows to store multiple values for one field (you just add a row with the same item_id and field_id).

More complicated SQL query, which contain more fields from content table could look like:


SELECT item.*, c1.text, c2.text FROM item, content as c1, content as c2
  WHERE item.id = c1.item_id       // to join the tables
      AND item.id = c2.item_id       // to join the tables
      AND item.short_id = '13432' // we can use short id
      AND c1.field_id = 'headline........';
      AND c2.field_id = 'full_text.......';

(this approach is used in main query function of AA - QueryIds() in include/searchlib.php3)

To select all extended fields for the item use:


SELECT * FROM content WHERE item_id = 'hey67s[o0-78z._d';

The data for field are stored in 'text' field of content table or in 'number' depending on 'text_stored' flag in 'field' table.

Item data manipulationg functions (data API)

It is important to know how the data are stored in database, but if you want to write some feature to AA, it is strongly recomended not to use direct database access, but rather use three main data API function to access data (especially for storing data into AA database). The functions are independent on database structure behind and it takes care about feeding, clearing the cache and other stuff.

Main AA data API functions are:


function QueryIDs($fields, $slice_id, $conds, $sort="", $group_by="",
                  $type="ACTIVE", $slices="", $neverAllItems=0,
                  $restrict_ids=array() )
  - stored in include/searchlib.php3

function GetItemContent($ids, $use_short_ids=false)
  - stored in include/util.php3

function StoreItem( $id, $slice_id, $content4id, $fields, $insert,
                             $invalidatecache=true, $feed=true )
  - stored in include/itemfunc.php3

By QueryIDs function you will get array of IDs of items based on your conditions, possiblly sorted. Input conditions are stored in array which you already know from design of searchform (conds[0][publish_date....]=...). This function allows you to get IDs based on any number of conditions. Also it is completely database independent, so you need not to know, which field is stored in item table and which is stored in content table.

The content of an item you will get by GetItemContent function. As input parameter use the IDs of the items you want to get (possibly obtained by QueryIDs). The items are then returned in array structure, which is good to know about, because all data manipulation functions in AA uses this structure to access the item data. This structure is also used as parameter to StoreItem function.

Item data structure

Abstract Data Structure for data manipulation in AA (returned by GetItemContent function):


$content[<unpacked_item_id>][<field_id>)][<alternative>][value|flag]

where
<unpacked_item_id>
is 32 characters long hexadecimal id of item (structure holds data for more than one item, generaly)
<field_id>
is field id as you know it from Admin -> Fields page of AA admin interface ( like 'headline........', 'url............2', ...)
<alternative>
is number used for storing multiple values for the same field. Obviously there is only '0' index, but for field, where we store multiple categories (for example) it will utilize indexes '0', '1' ,... up to number of selected categories for the item
<value
is probably what you care about - it is content of the field like 'An article title' or 1092928827 or <fulltext of item>
flag>
special flags for the content - if the content is HTML formatted, ... The list of possible flags follows (defined in include/constants.php3)

            define( "FLAG_HTML", 1 );      # content is in HTML
            define( "FLAG_FEED", 2 );      # item is fed
            define( "FLAG_FREEZE", 4 );    # content can't be changed
            define( "FLAG_OFFLINE", 8 );   # off-line filled
            define( "FLAG_UPDATE", 16 );   # content should be updated
                                                     # if source is changed
                                                     #   (after feeding)
      

So, to access content of 'headline.........' field for item number 5e72be7289a0be63820a8723837ce21a you can type:


$text = $content['5e72be7289a0be63820a8723837ce21a']['headline........'][0]['value'];

For inserting or changing data of an item you just fill the structure described above and call the StoreItem function.

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.

There are CSS files in the root directory that you can modify or create a new CSS file and point to it from include/config.php3 (line 139). 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">

1) Go to /apc-aa/misc/forgotten_pwd.php3 (may vary depending where AA is installed)
2) Enter either the username or email address
3) Check the email you will receive in case the user has been found and it's you
4) Visit the url in the email - in fact it's the same but with the temporary key that will let you change the password
5) Change your password

Note: The key expires after 90 minutes

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



If you realy think you need a logout, you have to create a special directory
  and Logout page under the restricted area of your website. I've set up a little
example here http://marek.greennet.org.uk/protect/http://marek.greennet.org.uk/protect/">http://marek.greennet.org.uk/protect/>

type jason:jason and you get in. Than you can click on logout ant it will
  take you to the logout page. The trick is that the page is under the same realm,
  so in fact you relogin as user &quot;logout&quot; with password &quot;logout&quot;


http://logout:logout@marek.greennet.org.uk/protect/logout/logout.htmlhttp://logout:logout@marek.greennet.org.uk/protect/logout/logout.html">http://logout:logout@marek.greennet.org.uk/protect/logout/logout.html>

The .htaccess file for the /protect/logout area looks like this



 

AuthType Basic

  AuthName &quot;Authenticate yourself&quot;

    AuthUserFile /home/httpd/htdocs/marek.gn.apc.org/protect/logout/.htpw

    Require user logout



The /home/httpd/htdocs/marek.gn.apc.org/protect/logout/.htpw contains only
  user logout (the file was created using htpasswd), and only this user is allowed
  here.


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".

Htaccess is updated by AuthMySQL module on the Apache server. The access is granted directly from AA (from auth_group and auth_user tables)

You need to:

1) Install mod_auth_mysql (http://modauthmysql.sourceforge.net/)

(This module is standard part of RedHat Linux distribution (rpm mod_auth_mysql). Be carefull, because there are at least two different modules with the same name but with different httpd.conf options and features. We need the described one and not the one described by Ram: http://actionapps.org/faq/detail.shtml?x=1673 !!!)

2) Then you need set auth_group...... field in Reader managment slice as described here: http://actionapps.org/apc-aa/doc/reader.html#d0e236

3) Set the apache to accept MySQL authentication - something like modifying httpd.conf file:

<Directory /data/www/htdocs/actionapps.org>

AllowOverride AuthConfig FileInfo Options Limit

# Authentication

AuthMySQLHost localhost

AuthMySQLUser aa_db_user

AuthMySQLPassword aa_db_password

AuthMySQLDB aa_db

AuthMySQLUserTable auth_user

AuthMySQLGroupTable auth_group

AuthMySQLNameField username

AuthMySQLPasswordField passwd

AuthMySQLGroupField groups

AuthMySQLNoPasswd off

AuthMySQLCryptedPasswords On

</Directory>

 

4) Protect the directory by .htaccess file or by similar lines in httpd.conf file:

AuthType Basic

AuthName "ActionApps Ariel Members Area"

<Limit GET>

require group ariel_members

</Limit>

or

AuthType Basic

AuthName "ActionApps Ariel Parnters Area"

<Limit GET>

require group ariel_partners

</Limit>

5) Done.

 

There is script /misc/oldDb2Db/move.php3. Script move.php3 is database trnansformation script, which copies whole slice from ActionApps v1.2- to the new database structure, which is used for ActionApps v1.5+.

  1. Go on Admin - Slice structure Import
  2. Copy the content of the /misc/oldDb2Db/oldSliceTemplate.txt file to the import area and press 'Send the slices structure' button. (This slice is then used as template for all imported slices. It makes no sence to repeat steps 1) and 2) for importing second slice !!!
  3. Modify next few lines in this script and fill the
  4. Remove the line just before this coment
  5. Run this script (you have to log as SuperAdmin, then)
  6. Done

What is Done:

Limitations:

After import you have to change the include lines in the pages in order the new slice is called - for example change old line in *.shtml file:

<!--#include virtual="/aa12/slice.php3?slice_id=4e6577735f454e5f746d706c2e2e2e2e"-->

to point to new AAv2.0 installation directory:

<!--#include virtual="/aa20/slice.php3?slice_id=4e6577735f454e5f746d706c2e2e2e2e"-->

The slice id is the same. After that, you shoud review all public pages to make you sure, it works as expected. I do not expect many problems. All features of AAv1.2- as possible to implement in AAv2.0. The biggest problem should be the search form, but it is quite easy to create it manually.

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.

Error returns in AA are not consistent, there is a general, low priority, task to clean up the code as we work on it.

In general use the $err array to return errors.

Some specific examples follow, please add others here.

Each of the functions: insert_fnc_xxx sets for example

$err[image.....1] => "Wrong type of file"

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----------

 

If you get the error: "No slice found for you" after logging into AA after doing a CVS update, then you may have forgotten to fill in the AA_ID in the config.php3 file

If you were a loser (like I have been) and did back-up your AA_ID, it can be retrieved from the AA database...

Using phpMyAdmin or your excellent MySQL skills:
Look for entries in "perms" table that have aa in "object_type" column, "objectid" is your installation ID.

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.

The hit is counted in this cases:

1) with slice.php3
   - if you will display an item with x=24425 url parameter
   - if you will display an item with sh_itm=42567a8736342562782abe782c
   - if you will use banner url parameter (banner=2-38)

2) with view.php3
   - if you display an item with cmd[22]=x-22-24425
     Note 1: if you use more than one item with x command
             (like cmd[23]=x-22-24425-24461-23612) only first
             item is counted)
     Note 2: if you want to display an item and do not want to count
             hit for such item, use 'o' command
             (like cmd[23]=o-22-24425), which works exactly in the same
             way as 'x', but it do not count hits.
   - if you use random parameter (ie. set[23]=random-1)

For speedup of database operations we use log table for hits count, from
which it is time to time copied to item table. You can configure this
behavior in include/constants.php3:

// CountHit probability - how offen write logged hits to item table
define ("COUNTHIT_PROBABILITY", 50);

This means that after 50 hits (approximately) (in whole AA) the hits are
written to item table (= displayed to users).

For more info see CountHit() function in include/util.php3

 

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 a tutorial for creating a simple alert module and subscription form, similar to the Sandbox subscription demo at http://actionapps.org/reader_mngmt/sandbox_subscribe.shtml. The alert is for all new items in a slice and the subscription require s only email address and sending frequency inputs, no password or selection of slices in this version. Subscribers can update their alert settings (e.g. change email address, modify frequency, and unsubscribe) by clicking on a unique link at the bottom of each alert they recieve.

The tutorial assumes you are already comfrotable creating and administrating slices and designing views in ActionApps.

Step 1: Create a Reader Management Slice

First you must have a Reader Management slice to store subscriber information. If you already hace a Reader slice, then you can skip this step, but keep in mind the Reader slice used in this example is called "My Readers".

  1. AA > New Slice: Create a new slice from the “Reader Management Minimal” template with the name “My Readers”
  2. Set “Allow anonymous posting” to “Active”
  3. Set “Allow anonymous editing” to “Authorized by a password field”

You now have a Readers slice called "My Readers" that will store each alert subscriber as one item. It also possible to add more fields to store additional data about your subscribers, but that's another tutorial (coming soon).

Next we need to select what items subscribers can be alerted to.

Step 2: Create a Selection of Items to be “Alerted”

An alert modules requires selections from slices. A selection is a condition on an alerts view of a slice. It's a bit confusing but will make more sense once we go through the complete alert module production process.

In this case, we have selected to alert users about new items from the important slice called “My Slice”.

In My Slice, create a new view, type “Alerts Selection Set”. Set field vaules as:

    Alerts Selection Set: “My Slice alert views”

    Group by selections (ignore for now)

    Alerts Selection 1 Description: “All My Slice Items”

    conds[] (ignore for now)

    Alerts Selection 2 Description and conds[] (ignore for now)

    Fulltext URL: (URL of fulltext view use for _#HDLN_URL)

    Fill the rest of the fields as a simple listing view, probably similar to your index view.

    Click Update

You now have an alerts selection called “All My Slice Items”. Once you are more comfortable with alerts, you can add more selections that use conds[] to allow users to filter in only certain types of items, but that's another tutorial (coming soon).

Step 3: Create an Alerts Module

Next step is to create an alerts module that will send your newly created alert selection.

  1. AA > Create New > Alert, settings:
  2. Selections > Insert “All My Slice Items” from the menu (notice there are also shortcut links at the bottom for quick access to the slices with alerts and editing the alert views).
  3. Click on Reader management, Synchronization with Reader Management Slice, change to “My Readers“ (the page will refresh)
  4. Click on 'Add or refresh fields' at the bottom. A message “2 field(s) added” appears.

Your alert module now contains alert selection "All My Slice Items" and My Readers slice contains two new input fields: “How Often” and “Selections”. You can goto the My Readers fields admin page to see these new fields. If they don't show up, go back to alert module > Reader Management and click on ‘Add or refresh fields’.

More selections can be added later. Everytime you add a section you will need to go back to your alert module > Reader management and click on ‘Add or refresh fields’.

You can now test your alert module by subcribing yourself using: My Readers > Add New Item: input your email address, check "email confirmed", set "How Often" to "instant" and check "Selections: All My Slice Items"

Then go to My Slice and add a new item. You should shortly there after receive an emal from the alert module announcing the new addition. You will notice the alert module messages use ECN related text by default. You can customize your welcome and alert messages at any time (see Step 5). But first let's set-up some public subscription forms...

Step 4: Create a Subscribe Form (and Related Pages)

To allow users to subscribe to your alerts, you will need to create a form using ‘Anonymous Form Wizard’. You should also have an OK page that tells users to check their inbox for an email confirmation and a another page with an anonymous form for updating subscription settings. Thus you will need to create three files, e.g.:

http://mysite.com/myalerts/subscribe.shtml - Invitation to subscribe using anonymous form.

http://mysite.com/myalerts/subscribe_ok.shtml - A notice telling users to "Check your inbox for an email confirmation".

http://mysite.com/myalerts/update.shtml - A subscrition settings update page using anonymous form, accessed only from a link within alert messages generated using _#COLLFORM alias (set in Alerts Admin - Settings: form URL.

To create the required anonymous form for the subscribe.shtml and update.shtml pages...

  1. Within My Readers > Slice Admin > fields: check Required for 'Email' and uncheck Required and Show for 'Password'.
  2. Slice Admin > Anonymous Form Wizard
  3. Copy the form HTML and paste into the file subscribe.shtml. Add some preable text and upload to the URL you specified.
  4. Upload subscribe_ok.shtml to specified URL.
  5. Paste the same form HTML in to update.shtml. In the <form> change the value of the two hidden fileds "err_url" and "ok_url" to the update.shtml URL. Upload.

You should now have a page for users to subscribe to the alert (e.g. origianl sandbox alert subscribe form) that when submitted correctly leads to the OK page saying "Check your inbox for an email confirmation". In the confirmation/welcome email there should be link with unique ID pointing to the the update.shtml URL. When visited, this page will confirm the email address and allow thye user to modify their subscription settings, inluding change their setting to "not subscribed".

You should test this subscritpion process, including updating subscription settings. Add some new items to My Slice and check that subscribers receive them as expeceted.

Make Forms Pretty

You may also want to simplify the anonymous form by hiding the selection check box and possibly the "how often" select box. To hide the selection checkbox, just change the input type from "checkbox" to "hidden", and remove the surrounding text. To hide the "how often" select box you need to create a hidden input with the name and one value pulled from the "how often" select box. The final cleaned up form could look like the sandbox alert subscribe form.

You may also want to similarily modify the update, see sandbox alert update form.

Step 5: Customize Your Alert Messages

If you haven't already, you will want to customize the alert welcome message (sent once upon subscription for email confirmation) and the alert message template.

Alert Welcome Message

Like any important text, you should probably use a word processor to write and check spelling of the message to sent. You can use HTML or plain text. You will want to include:

To update the test, go to you Alert Module > Settings and click edit icon beside welcome email select box. Both the subject and body processes aliases and {} commands.

Alert Message Template

The alert message template is edited the same as Welcome Message, except that _#FILTERS_ will be replace by the views of the new selections. You will want to include:

The views of selections can accessed through My Alerts Module > Selections > click on selection name. It is probably best to put the introduction to each slice's items within the top HTML for each slices Alerts Selection Set view. This is more important when there are multiple selection options within an alert module.


Tips

Filtering readers who are not yet confirmed

Change the design of the Item Manager in Slice Admin to show the alias _#MAILCONF. This alias shows “yes” or “no”. But it is created by the f_c function and the values in the database are 0 or 1. Thus give “0” and not “no” into the Search box.
Filtering readers receiving a selection: Add the Alerts Selections to Item Manager. Create an alias using the function f_h with the parameter , (comma). You will see the selection IDs prefixed by f. Now you understand why you should enter something like “f45” into the Search box.

Customize Result Messages

To customize result messages, (i.e.. confirmation, error or update messages at the top right of anonymous forms) use show_results.php3: Copy the script from doc/script/show_result.php3 to the same location where you created myalerts.shtml.
When creating anon form: Fill the URL of yours show_result.php3 and check the box “Use a PHP script ...”

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.

MLX - MultiLingual eXtension for APC-ActionApps

 

MLX adds content translation and interface translation features to ActionApps. All of this is now part of ActionApps core and these pages are here mainly for documentation and historic reasons.

(or mimo's language extension)

(C) Michael Moritz mimo/at/restoel.net
MLX Screenshots

Changelog

  • 05/11/2004 MLXGet Text Documentation
  • for changelog see APC AA CVS on SourceForge
  • 05/10/2004 -- changed the way ids get stored, optimised sql queries and since MLX is now in APC-AA CVS removed the installation stuff from this page, to upgrade without CVS have a look at MLX installation -- the hard way
  • 04/10/2004 -- now moved into APC AA CVS on SourceForge
  • 03/10/2004 -- apc-aa-mlx-0.2: support for simple slice.php3 calls; better admin integration (using MLX tabs)
  • 29/09/2004 -- first buggy release: basic admin interface functions

Step-by-Step Example of setting up a slice for MLX

  1. Create a new slice based on News Template and call it MLX Control Slice.
  2. Delete all deleteable fields from this slice.
  3. Add two new fields. Call one EN, the other one FR and choose type MLX Control for them.
  4. Unshow all other fields apart from these two. Have a look at MLX Screenshots to see what this should look like.
  5. Create a new slice. This one will hold the actual content (Content Slice). It can be any kind of slice.
  6. In Slice Settings select the MLX Control Slice you created before. Again, MLX Screenshots are your friend.
  7. Check that the slice contains a lang_code....... field.
  8. Add a field for the MLX information. It must be of type MLX Control. It doesnt have to be visible, so in most cases you want to hide it from the user by unticking Show.
  9. Done! You are ready to use the multilingual content slice.

 

Using MLX

MLX adds a little menu to the Add Item / Edit Item pages. This contains something like:

Add German | Edit English (view) | Edit Dari | etc.

Clicking on Add DE takes you to the Add Item page. This is prefilled with the contents of the original item. Once you have translated this content press the Insert button. MLX takes care of storing the information that keeps the original version of the article and the German translation together.
 

MLX and slice.php3 -- Displaying content using MLX on a web site

From version 0.2 MLX does actually do something do the output as well. This is configurable depending on what situation you are in. Here are three scenarios:

  1. You have a multilingual site. Some articles are translated, others only exist in the original language. If a vistor to your site chooses a language into which only some articles are translated you want to display the untranslated ones nevertheless (an example of this is the ESF2004 website). In this case you would use slice.php3 like this: add mlx=FR to the URL if the user selected French as his/her language. E.g. index.shtml?mlx=FR&listlen=10. MLX takes care of showing translations or original items for you. It will display an alternarive article (in this example a non-French one) if it exists one. If more than one other translation exists MLX uses the order in which the languages are defined in the MLX Control Slice. So the step-by-step example above would first look for an English version. But you (or the user may chose to) can even override this behaviour: The same way you pass the user's language choice to slice.php3 you can aslo set the order in which alternatives are used. With two languages this doesnt make sense, but given you had a third translation, let's say in German, you could pass the order like this: index.shtml?mlx=FR-DE-FR This would make MLX first look for a French version of the item, then a German one, and then a French one and display the first one found.
  2. You only want to display articles in the language the user has chosen. Use this syntax for your calls to slice.php3: index.shtml?mlx=FR-ONLY (This is similiar to using a condition)
  3. You want to display all articles including other language versions. Syntax: index.shtml?mlx=ALL. (This ignores MLX information)

MLX and view.php3

MLX supports views as well. Use set[vid]=mlx-(lang code)-(lang code 1)-..-(mode)

The _#MLX_LANG Alias

When using language defaulting this is helpful. It allows to print the current desired or default language in a view. This is hopefully helpful for creating language menus, displaying messages like "currently there isnt a translation for this article, so the original version is displayed". Have a look at the demo in MLX Screenshots for how this works.

FAQ

  1. Q: How do I MLX-alise a slice?
    A: Follow the steps in the Step-by-Step example but skip creating the Content Slice (step 5). Make sure you set the MLX Control Slice as the MLX: Language Control Slice in the slice you want to MLX-alise and that you have a field of type lang_code....... in it. To MLX-alise an item you need to edit it in the Item Manager. This means you click on the headline and the press the Update button. Click on the headline again and MLX is ready.

Bugs & Limitations & TODOS

  • Maybe add to fulltext view also in slice.php3
  • Testing, testing, testing

Credits

  • Huge thanks to Marek Tichy for discussing this and helping implementing it as I did not know anything about Action Apps? code when I started
 

(was on http://mimo.gn.apc.org/mlx)

The script /misc/file2slice/importer.php3 contains a function importer, which can import a CSV (comma-separated-values) file into your slice.

The data file should contain field names (any names, not from AA) on the first line, separated by your chosen separator. The next lines contain the items, one item per line, fields separated by the same separator.

E.g.:
AUTHOR,TEXT,EMAIL,LANGUAGE,CATEGORY
Johny Bravo, he is a real good guy, johny@bravo.uk, fr, VIP+fools
France Newman, a noname boy, france.newman@noname.org, en, nonames+fools

Here, the separator is comma, but it may be any other string.

The function trimmes each field from whitespace. It has these parametres:

You don't have to set all the parametres - the last one required is postedBy, the next ones have default values.

The "fire" parameter works as a safe mode. You can prepare your data with "fire" set to false and when you are sure that what you see on the screen is what you want to be added to the database (by the StoreItem function), you may set "fire" to true.

Actions

The array "actions" should look like this:

$actions = array(
"created_by......" => array("action" => "store", "from" => "AUTHOR"),
"category.......1" => array("action" => "storeparsemulti", "delimiter" => "+", "from" => "CATEGORY"),
"language.......1" => array("action" => "storetrans", "from" => "LANGUAGE", "flag" => 1, "trans"=>array("en"=>"english","fr"=>"french"))
);

It contains the AA field names followed by how to get their content. You may set flags (e.g. "flag" => 1 means HTML content) with any action.

The actions are as follows:

A fully functional example script


<?php
$actions = array(
"category.......1" => array("action" => "storeparsemulti", "delimiter" => ";", "from" => "Category"),
"headline........" => array("action" => "store", "from" => "Title"),
"created_by......" => array("action" => "store", "from" => "Author"),
"full_text......." => array("action" => "store", "from" => "Summary", "flag"=>1)
);

require "./importer.php3";

Importer ( "aa65a21b285c25f9fe0d4b662919b4b2", // slice iD
	"./books.txt",                      // file name
	"t",                               // field separator
	$actions,
	"uid=ada01,ou=People,ou=AA",        // posted by (there should be a number for sql permissions)
	true,                               // write to DB?
	600);                               // time limit in seconds
?>

There are a number of tools for importing, each has different advantages and disadvantages and each needs configuring to specific requirements.

apc-aa/misc/file2slice/importer.php3: Is highly configurable, and can perform functions on the data, however its complex and requires some PHP knowledge to get to do what its capable of. It is documented below. Note that apc-aa/misc/file2slice/import.php3 is an example of its use.

apc-aa/misc/file2slice/tab2slice.pl is much simpler, but it takes the packed field ids as parameters in the first line of the file being imported, it is documented in the top of the file. (this was apc-aa/misc/tabslice.pl)

apc-aa/misc/file2slice/tab2slice_php/ contains a PHP version that can be used with uploaded files (unlike importer.php which reads the file from the file system). It has to be configured to know the packed ids. It does not have the complex capabilities of import.php3 to manipulate fields during import. See apc-aa/misc/tab2slice_php/README for some basic documentation.

It should be possible to merge the uploadability of tab2slice_php with the automatic configuration of importer.php3 but this has not been done yet.

misc/file2slice/array2constants.php3 is also available for importing constants but requires documentation.

There is an command-line-interface for modifying slice structure (the fields).

See apc-aa/misc/txt2fields/README

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.

Content Pooling lets you exchange articles with any number of partner sites. You can create a pool with any number of partners. With Pooling, you always retain complete control: you can withold any item from your pool; and you can reject any item made available to you.

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.

This FAQ assumes you did the original installation from CVS (see Installation of ActionApps Doc )

First, check that you really want to update. There is usually a stable release and a developer release. The instructions below will update to the latest release from CVS - which is what most of the people discussing things on the apc-aa-general mailing list are using. This might not be as stable as a release you may be running.

Back-up Your Files and DB

The CVS will write over your current config file, usually located in /apc-aa/includes/config.php3. The key values you will need to re-enter after updating and may not be able to remember are: AA_ID, DB_HOST, DB_NAME, DB_USER, DB_PASSWORD. Without these correct values, AA will not work.

You should also back-up all your apc-aa files, encase the update fails and you need revert back.

Once you have done your back-ups, login to shell on you account and cd to the apc-aa directory and run

cvs -n update

This will display the changes and potential conflict - look for lines starting "C" these are conflicts that need a developer to figure out. You'll have to ask this list if you get one of these.

NOTE: It is common to get 'timed out' type errors from the CVS, which is hosted at SourceForge.net. Just keep trying every few minutes

If it all looks good, run

CVS update -dPAC

This will:
-d Build directories, like checkout does. (if there is new directory in the repository, then it is created)
-P Prune empty directories.
-A Reset any sticky tags/date/kopts. (allways load HEAD branch of the CVS)
-C Overwrite locally modified files with clean repository copies.
(For more options try "cvs --help update")

You should then compare the version number at the top of /apc-aa/includes/config.php3 to see if it is newer then your backed up config.php3 file. If not, you can simplly upload your backed-up version over the new one. If the new config file is different, you will need to manually write in your settings, based on the backed-up version.

Access http://yourhost/apc-aa/sql_update.php3, this will update the database to the latest version. The script always refreshes the database structure to the newest version - no matter if you allready have the newest structure.

The script makes a backup of the tables, but there is not yet a documented way to restore the old version, and note that re-running the script overwrites the last copy of the backup.

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

Warning: Access denied for user: 'aadbuser@xxxxx' (Using password: YES) in /usr/local/web/phplib/db_mysql.inc on line 73 Database error: pconnect(xanadu.cyborganic.org, aa-user, $Password) failed. MySQL Error: 0 () Please contact foobar@somewhere.com and report the exact error message. Session halted.

Typically this means that the DB_HOST, DB_USER, DB_PASSWORD, DB_NAME setup during editing config.php3 in Install 4.1 don't match the one you gave permissions to in Install4.2. In particular note that if the DB_HOST is absolute e.g. "aa.apc.org" then the permissions are going to have to include the machine name that the Apache server runs on e.g. aadb@bigserver

ActionApps empower anyone to publish online, saving you the money you'd normally spend on web specialists (or training). ActionApps also make your team more efficient—since the people who create your group's information can publish it online themselves. Finally, ActionApps' Content Pooling technology, by letting you trade articles with partner sites, helps you access new content (theirs) and new audiences (for yours). About ActionApps presents more about benefits, while Strategic Uses offers tips on adapting ActionApps to your own needs.

Web Networks' case studies can be viewed here

Also see our growing list of ActionApps examples

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

If you find no alias function is good enough for you, you can write your own. function. The alias functions are stored in include/item.php3 file and its names begins with f_ (but we can name it as g_* or such, as well) and they are three letters long (just like f_a()).

All you have to do for new function is:

  1. Write your own function in item.php3 (say f_9()).
  2. Add description of the function into param wizard definition file include/constants_param_wizard.php3 (structure described inside this file)
  3. Add human readable messages into include/en_param_wizard_lang.php3 language file.

  4. Edit the FAQ item on Alias function paramaters

If you find, that the new alias function is very proprietary (it is unusable for other people, you can create file /include/usr_aliasfnc.php3, which is automaticaly included to code (if exists). There you can define your own alias functions. The function name must be prefixed by 'usr_' prefix. The function have three parameters:


The example listing of /include/usr_aliasfnc.php3 (the file should not be committed to CVS, because it is very proprietary and the content should not be shared between installations):

<?php //usr_aliasfnc.php3  

/** Prints czech date (for Ekolist pages)
* @param columns - array of all field values for all ifelds in current item
* @param col - fileld id of field, for which the alias is defined
* @param param - possibly parameters to alias function passed in alias definition parameter (usr_cz_date:parameter)
*/
function usr_cz_date($columns, $col, $param="") {
$dte = $columns[$col][0][value];
$month = array( 1 => "ledna", "unora", "brezna", "dubna", "kvetna", "cervna", "cervence", "srpna", "zari", "rijna", "listopadu", "prosince");
$weekday = array("nedele","pondeli","utery","streda","ctvrtek","patek","sobota");
$m = $month[ date("n", $dte)];
$end = ( !$param ? "" : " (". $weekday[ date("w", $dte) ]. ")");
return date("j", $dte) .". $m ". date("Y", $dte). $end;
}
?>

Such alias function can be called by defining new alias for some field. Just define alias name (as obvious), alias function should be "f_u - user function" and the parameter should be the name of the function ("usr_cz_date" in our example). It is possible to pass parameters to the function. The parameters are separated by colon (usr_cz_date:parameters).

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:

Requirements for ActionApps Unix Hosting

Optional:

Please add your comments below about AA installs that have and have not worked for you...

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
Different APC providers offer different services based on ActionApps. So prices vary. For specifics, please ask your APC provider. The Action Applications were developed by the Association for Progressive Communications, http://www.apc.org/. They are released as open source and there is a project set up at SourceForge. The Action Applications SourceForge page can be found at http://sourceforge.net/projects/apc-aa/.

The applications in v1.5+ can be created quite easy.

  1. Choose a slice and create the set of fields you want to have in the new application.

  2. For these fields change the default values, help texts, names, priorities, aliases, etc. in the admin interface ("Admin" -> "Main settings - Fields").

  3. Change the design of the fulltext view, list item view and possibly the admin view ("Admin" -> "Design - Fulltext", "Admin" -> "Design - Index", "Admin" -> "Design - Item Manager")

  4. Test the new slice, whether it is working O.K.

  5. Add a new slice based on this one (not a template, but a slice)

  6. Mark the new slice as a Template ("Admin" -> "Main settings - Slice") - to do this you must be the superadministrator (four stars).

If you are a developer and are interested in the ActionApps, we want your help. You can either offer to help our team directly or you can work on your own modules and release them under the GPL. Either way, you should check in with us on current developments and plans. Visit the ActionApps developer Website at http://www.sourceforge.net/apc-aa

To edit a file, you should work on a copy of the full APC-AA distribution, make changes and then check back the changed files

To check out the whole of apc-aa into some directory or other, you need to do it differently from the standard installation instructions if you plan on editing files.

The first time you use a particular CVS host you need to do ....

$ ssh yourusername@cvs.apc-aa.sourceforge.net

It should log you in, and straight out again (accept the host key if it asks you to)

$ export CVS_RSH=ssh #for bash for example
or
setenv CVS_RSH ssh # for tcsh for example
$ cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
yourusername@cvs.apc-aa.sourceforge.net's password:

If it doesn't ask for a password, but you get an error about connection refused its probably because it didn't see the CVS_RSH environment variable.

Edit the file, then

If the file is not already in the CVS repository, for example, because you have created a new file, then first add it to CVS with

$ cvs add myfile.htm

then upload with for example

$ cvs commit myfile.htm

Make sure to put in a useful comment when prompted by CVS.

Note, Its best NOT to do a plain

$ cvs commit

As this will commit files that you probably don't want to, especially config.php3

If you get the error:

Could not chdir to home directory /home/users/y/yo/yourusername: No such file or directory
cvs [server aborted]: can't chdir(/home/users/y/yo/yourusernameNo such file or directory

Then you need the ssh trick.

You can't use pserver: to check the files out, if you are going to commit them back again.

Yes - this works fine,

You need to setup config.php3 correctly,

Assuming you want the same data to appear on both, then
the key variables seem to be.

AA_INSTAL_URL which can either point to one location, or different locations for each server such as http://www1.yyy.com and http://www2.yyy.com.
DEFAULT_ORG_ID will be the same for both
DB_HOST , DB_USER and DB_PASSWORD will be the same in both cases and point to the database server
DB_NAME will be "aadb" in both cases, i.e. they are using the same set of slices.
AA_ID will be the same in both cases.

Cron feeding to other hosts should be run on one machine only.

If you want totally independent data on each web server, for example if they are serving up totally different slices, then set DB_HOST to different values and AA_ID to different values, and have Cron work on both.
There are two branches, currently (9 Jan 2001) these numbers are

(main) developer 2.1.0
stable 2.0.1

Production systems will probably want to work with 2.0.1, although 2.1.0 is fairly stable.

In theory, to discover which version you are using, look in "CHANGES", for example apc-aa.sourceforge.net/aa/CHANGES shows that Sourceforge is still running the stable branch, but note that CHANGES is frequently NOT updated to show the version number of the developer version, and the current developer version shows the same version 2.0.1 with just a few more dated changes.

If you check out the default method:

cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa -r2_0_1 co apc-aa
OR
cvs -d:pserver:anonymous@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co -rv2_0_1 apc-aa

you will get the developer branch, but

cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
OR
cvs -d:pserver:anonymous@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa

Note that you cannot assume that different branches will run with the same Database.

In particular to upgrade from 2.0.1 to 2.1.0 you need to run sql_update.php3 to upgrade the database fields.

If you are unable to edit php.ini, then you won't be able to change the include path to point at PHPLIB, in this case edit the APC-AA/include/config.php3 to add the following lines.

# PHPlib directory if not on include path
$_PHPLIB["libdir"] = "/www/mysite/phplib/php/";

Change the site to point at the location where you have installed phplib.

You can also access PHPLIB by putting the following line in your .htaccess

php_value include_path ".:/usr/local/lib/php:/usr/local/lib/php/phplib" You can create your own usr_validate.php3 with a user validation function in it (sorry at this point there can only be one for an apc-aa installation, we'll fix that later, if you need it to validate multiple fields you can make it switch based on the field name).

Here is a sample validation function. If the file include/usr_validate.php3 is present it will be included automatically.


<?PHP
// ----- Sample code -------
// returns new value for the field.
// or just return $value;
function usr_validate( $varname, $showname, $value, $err, $f, $fields)
// $varname -- name of variable
// $showname - name of variable in the page.
// $value - value of the input field.
// $err - validated or not.
// Standard way:
// $err["$varname"] = MsgErr(L_ERR_IN." $inputName");
// $f - I DON"T KNOW... please read admin/itemedit.php3
// you can get all the info about the field. include name.
// $field - - all the fields
{
if (!$value) // no value set in the input field
return "Hey! It is working."; // set default value of the field
else if ($value == "stupid") { // if value is "stupid"
// set error
$err["$varname"] = MsgErr(L_ERR_IN." $showname".". Do not use the word.");
return "fool"; // return error, and change value to "fool".
}
else
return $value; // same value. no change.
}
?> There are several recent (Mar 2002) changes to make it easier to call apc-aa modules, especially the item manager, from php code.

Sample code to call admin/index.php3 (item manager) from outside.

file: apc-aa/sample/itemmanager.php3
(this need to stay same level of folder with apc-aa/admin/ )

<?PHP
# parameter
# project_id - slice id for project slice.
#
# Usage:
# http://host.name/apc-aa/sample/itemmanager.php3&project_id=<slice id>
# <slice id> : slice id to be open ....
# optional parameter:
# Tab - this is for admin/index.php3 to select Table.
# ="app" - Active bin (default)
# ="appb" - Pending bin
# ="appc" - Expired
# ="hold" - Hold bin
# ="trash" - Trash
#
# AA_CP_Session - session id
#
require "../include/init_page.php3";
// this check AA_CP_Session and open login prompt and call me again.
// also it sets slice_id, is session is already there.


if( isset( $sess ) )
page_close(); // this will store session variables in database.



// === prepair parameters to call admin/index.php3 ===


// use change_id if we open the slice 1st time.
if ($project_id == $slice_id)
$slice_param = "&slice_id=$project_id"; // we may not need this.
else
$slice_param = "&change_id=$project_id";


// table to open (active,trash,hold,expire,pending...)
$tab_param = $Tab ? ("&Tab=".$Tab) : "";


// filter parameter from apc-aa/admin/index.php3
$filter_param = (!$admin_order)? "" :
"&admin_order=$admin_order".
"&admin_order_dir=$admin_order_dir".
"&admin_search=$admin_search".
"&admin_search_field=$admin_search_field";


// parametere for scroller -- set by admin/index.php3 (at callback)
$scroller_param="";
if ($scr_st3_Mv) $scroller_param .= "&scr_st3_Mv=$scr_st3_Mv";
if ($scr_st3_Go) $scroller_param .= "&scr_st3_Go=$scr_st3_Go";


$debug_param = $debug ? ("&debug=$debug") : "";


// parameter to call myself from admin/index.php3 (admin/index.php3 will call me back)
$my_param=
"AA_CP_Session=$AA_CP_Session".
"&project_id=$project_id".
"&projects_item=$projects_item".
$tab_param.
$debug_param;

$MY_URL=urlencode($PHP_SELF."?".$my_param); // &return_url=.... for itemedit.php3, etc.

// So, all parameter to call admin/index.php3 is prepaired we write the page.
?>
<?PHP // -- showing Project Tasks (a slice made from "Project Tasks (template)" )
// -- now , we are using ItemManager of APC-AA as our ItemManger (not slice.php3 with index view) $pts_item_manager = "http://localhost/apc-aa/admin/index.php3". "?AA_CP_Session=$AA_CP_Session". $slice_param. $tab_param. $scroller_param. "&bodyonly=1".
"&action_selected=1".
"&sort_filter=1".
"&return_url=$MY_URL".
$debug_param. ""; include $pts_item_manager; ?>
# action_select=1 turns off "Feed selected" and "View selected"
# sort_filter=1 turns off the sort line
# scr_st3_Mv and scr_st3_Go can be set to work with the scroller

The action apps software uses the mysql database engine to store its data. The mysql database system is very very reliable.

If the server is interrupted in the middle of a transaction, it can corrupt the database. For example, the servers at SangoNet had a power failure, and one of the mysql tables got corrupted. This shows itself in the actionapps by one of the pages not working and reporting a mysql error about a corrupted database.

It is usually easy to fix a mysql database that has been corrupted. In this case, I just went to /var/mysql (where databases are stored) and checked to see if there were any errors. Mysql uses a program called isamchk to detect and fix errors. This command checks to see if any of the table in any of the databases is corrupted:

/var/mysql > isamchk -s */*.ISM

In this case, the aadb/pagecache.ISM file had two errors. So I ran isamchk in recover mode to fix pagecache.ISM:

/var/mysql > isamchk -r aadb/pagecache.ISM

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.
IIS is not a supported platform for APC-AA or at least it is not tested on this platform. There were some limitations in IIS v4.0 (I'm not sure, how it is in v5.0), which makes AA half-usable. There was a problem of not passing url parameters
to a script, which is included by SSI include into an shtml page.

The requirements are on:
<a href="http://apc-aa.sourceforge.net/apc-aa/doc/install-2.html">apc-aa.sourceforge.net/apc-aa/doc/install-2.html</a>

APC-AA is tested at least on Linux/Apache+MySQL+PHP and on Win98/Apache+MySQL+PHP (as a home developer installation).

The easiest way how to run AA on home Windows machine is to install PHPTriad (Apache, MySQL, PHP), which is really easy, see <a href=http://www.phpgeek.com>www.phpgeek.com</a>

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

Sure - here is a little example that shows how to write a little Perl program to execute and return a SQL string.

#!/usr/bin/perl -w


# this script demonstrates how to use perl to look at the
# mysql database for a slice.
# This particular script looks some of the attributes of a slice's fields


# EDIT NEEDED: set these variables!
# $slice_id $user $password $database $host


# create connection to mysql, using perl DBI module
use DBI;
$dsn = "DBI:mysql:$database:$host";
$dbh = DBI->connect($dsn, $user, $password);


# convert a Hexadecimal input into a packed string
$p_slice_id = pack 'H*', $slice_id;


# create a SQL statement handle, and prepare a template.
# Templates make quoting easier.
my $sth_p = $dbh->prepare(
q{ SELECT id, name, feed, input_show_func from field where slice_id = ? }
) or die $dbh->errstr;


# run the statement, using the packed sliceid, and print the results
$sth_p->execute($p_slice_id) or die $dbh->errstr;
DBI::dump_results($sth_p);
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. Create a directory under which a sub-directory will be created for each slice,

either create that under one of your sites, or create it somewhere else and

create an alias in httpd.conf to point at it. Make sure this directory is

"rwxrwxr-- nobody.nobody"

Edit apc-aa/include/config.php3, edit the defines IMG_UPLOAD_PATH and

IMG_UPLOAD_URL to point to this directory. Note the trailing "/".

IMG_UPLOAD_TYPE needs configuring, but its not clear what exactly this means.


All configuration options are in config.php3:

define("IMG_UPLOAD_MAX_SIZE", "400000"); # max size of file in picture uploading
define("IMG_UPLOAD_URL", "http://work.ecn.cz/img_upload/");
define("IMG_UPLOAD_PATH", "/data/www/htdocs/work.ecn.cz/img_upload/");
define("IMG_UPLOAD_TYPE", "image/*");
define("IMG_UPLOAD_DIR_MODE", 508); # mkdir perms (508 = 0774 in octal, but
# octal value in constant don't work)

When you submit first item with image in the slice, AA will create new subdirectory under the IMG_UPLOAD_PATH directory. The name of this directory is the slice id. In this example we can expect the directories like:

/data/www/htdocs/work.ecn.cz/img_upload/f4c90ee8ef46cd6fa0a4521c61a28f4f
/data/www/htdocs/work.ecn.cz/img_upload/5d2b4ed6778fe3ac6db6ec74ceee650d

The directories are created with IMG_UPLOAD_DIR_MODE mask.

The image upload function is quite easy and you can find it in include/itemfunc.php3 file - function insert_fnc_fil().

(c) Jakub Adámek, Econnect, January 2003

Since January 17 2003 AA is using the mini-gettext language environment. The language files are in the directory include/lang/.

Each file is connected with one language and a series of PHP scripts. At run-time, you can only use one file for translations at a time, but you can change freely between files by using the bind_mgettext_domain() function in include/mgettext.php3.

The files are maintained by people — translators and by the PHP function xmgettext() in misc/mgettext/xmgettext.php3. Translators add new translations and xmgettext() adds new strings to be translated which it finds in the source files.

Notes for Translators

To add new translations, you only need to find empty strings "" in your language files, e.g. $_m["not yet translated"] = "". Please mind some following notes.

The language files are regular PHP files, you must not break the syntax. You must not change the ID string in _m["..."]. Even if it contains bad English, it may be changed only in the source code, not in the language file. There is also an English translations file, thus small changes may take place there.

You must follow the PHP syntax for strings, using \" and \$ instead of " and $. You must quote the translation with "". (You might quote it with single quotes as well, but next time xmgettext() will be run, it will reformat all strings to double quotes.)

Each language string is preceded by links to source code where it is used. If you are not sure how to translate a string, go to the source code and have a look. Some language strings contain parameters %1,%2 etc. which will be replaced by some variable content at run-time. Place the parameters appropriately in the translation.

The file begins with a list of "Unused messages" which are there only for your convenience so that you may use the text for the new translations if necessary. You can freely delete any unused messages.

Notes for Developers

Have a look at Notes for Translators. The explanation of using mini-gettext in code follows.

The simple syntax: A string becomes language string by enclosing into _m(" "), e.g.

_m("any string").

It is better to create long strings than to concatenate short ones, because translators may easier understand the meaning.

The parametrized syntax: You must not use variables in language strings. But you can use parameters %1,%2,... with the syntax of

_m("... %1 ... %3 ... %2", array ($param1,$param2,$param3)), e.g.

_m("Click on %1 to get more help.", array ($url)) or
_m("Error %1 in file %2 on line %3", array ($err,$file,$line)).

Always use the array() even when using only one parameter %1.

To update language files, use xmgettext(). Call it by the misc/mgettext/index.php3 script. Have a look on particular settings in the script. You need to provide read-write access for PHP to language files in order to update them. Copy them into another directory (I used ../php_rw/lang, i.e. not a subdir of the AA installation), set permissions, run xmgettext and copy the updated files back. A side remark: If you don't like this overhead, just remember which overhead it took to create and copy all the L_ language constants to new_news_lang.php3 ...

One more thing to take care of is the run-time switching between languages. If you fill in some include file a global variable with translated strings and than change language, it will remain in the old language. You must create a function returning the variable to avoid this.

Hope you will like my mgettext solution,

Jakub

Michael wrote a perl script called 'remote',( in apc-aa/misc/remote/remote)

'remote' could be useful to groups running action-application
servers, by expanding the number of groups that will want to have slices. Imagine a nonprofit wants to start using the apps for their news page, but does not want to move their site to a webhost that has action applications installed.

Using 'remote', the organization's webmaster could:
1. Ask a server with the action applications to setup a slice for them
2. Include the news items from their slice with 'remote', pulling these items into news.html, on their local webhost.

I think this could be especially true of larger organizations.

Note: If this script is not fast enough, consider using 'apc-aa/misc/remote/remotec', a version of 'remote' with caching, or misc/remote/remotec.php which is in php and should be even faster. What is a module?
-----------------
You probably know slices - a part of database with its admin interface
which is able to manipulate with items/articles. The slices are very
configurable, so it can hold news or events as well as database of
links, organizations or members. Slices are great for presenting tabular
data of any type. On the oher hand, there are many cases, where we need
comletely different data structure, behavior of admin interface or
presentation layer. As example we could mention polls, petitions, ...

Because users of AA (including us) wants to manage such data in the same
(ActionApps) environment, we have to find the way, how to incorporate
such data administration into AA. The answer is modules.

It's hard to explain what modules are and how you can create it, because
the is no good example of working module, rihgt now. In fact, there are
two modules - module 'jump' and module 'site'. The Jump module is too
easy (it allows you just to jump to specified page of specified slice in
admin interface) and the site module is too complex and it is not fully
integrated into AA. That's why it is not commited into CVS at this moment.

What the module allows
----------------------
- allows you to create different admin interface for the module data
(You can replace Item Manager and Slice Admin by your own admin pages,
including left menu bar, ...
- allows you to use your own database tables
- allows you to use your own permissions in new module (there is general
permission system with standardized perm API defined, which provides
abstract layer for functions like AddPermObject, AddPermUser,... -
such functions then operates in backroud with LDAP, SQL, ...)

How modules apears to user in AA admin interface
------------------------------------------------
All modules which belogns to logged user are listed in 'Module
selectbox' which you uses for selection of slices, right now (well known
'Switch to' selectbox). The idea is, that in this selectbox then user
switch to administration of news of site XY, to administration of events
of site XY, and to administration of polls for this site. In fact the
slices now became just one of the modules incorporated into AA environment.

When user selects another module type in Module selectbox, then upper
navigation bar will be changed just slightly. User will see probably no
'Item Manager' as well as 'Slice Admin' menu options. (S)he will see
'Poll Manager' and 'Poll Admin', or maybe just Poll Manager (if we speak
about poll module as example).

How to create new module in APC Action Apps
-------------------------------------------
Basic steps, which is needed for module creation are:

1) copy the modules/module_TEMPLATE to the new directory and name it by
the name of module (just for clarity) (modules/poll for example).

2) open /include/constants.php3 and add new module in the $MODULES
array.

3) create database tables for the module and add the definition to
doc/aadb.sql and sql_update.php3

4) modify modedit.php3 script in your module directory - this script is
called after 'Add xy module' is pressed so there should be basic
module settings/creation options (as we already know from 'Slice
Admin' - slicedit.php3).

5) modify index.php3 script, which is the script, which apears after
user selects the module from 'Module selectbox' (for 'slice' module
such page is Item Manager.

6) insert new language file for the module to include/ directory (just
like en_poll_lang.php3), if you want to use module specific texts
(you probably will) (Note: all language files must be in include/
directory)

Done - module is created.

Before we go to detailed description of the steps, we have to mention
some facts, which maight be confusing.
I say, that slices are just on of the modules. That's true, but from
historical reasons there are some differences:
- the code for slice is not placed in module/ directory - it is placed
in admin/ and include/ directory instead
- name of slice configuration file is not modedit.php3, but it is
called slicedit.php3
- the id of the slice is hold in $slice_id variable. Better name for
this variable is module_id (as we use it in other modules). For now
just note, that the module_id is exactly the same as slice_id.

Let's describe the module creation steps in more detail (I will use (non
existant) 'poll' module as an example. Substitute all 'poll' words with
the name of your module, of course):

ad 1) copy module_TEMPLATE
--------------------------
In module_TEMPLATE directory are templates for all interesting scripts,
which we need for new module. So, create new directory (modules/poll/)
and copy there all files from modules/module_TEMPLATE. As steted abobe,
name of the new directory sholud be the same as the name of module.

ad 2) add module to constants.php3
----------------------------------
The only cyhange, which is need in constants.php3 script is to add new
record into $MODULES array. The array looks like:

$MODULES=array('S'=>array('name' => 'slice',
'directory' => AA_INSTAL_URL ."admin/",
'table' => 'slice',
'hide_create_module' => 1),
'W'=>array('name' => 'Site',
'directory' => AA_INSTAL_URL ."modules/site/",
'table' => 'site'),
'A'=>array('name' => 'MySQL Auth',
'directory'=>AA_INSTAL_URL ."modules/mysql_auth/"),
'table' => 'module',

'hide_create_module' => 1),
'J'=>array('name' => 'Jump inside AA control panel',
'directory' => AA_INSTAL_URL ."modules/jump/",
'table' => 'jump'));

There we see listed four modules in the example above. Each module is
identified by a letter. Let's choice any unused letter for new module -
we choose letter 'P' for poll module for example.

There are four values for each module:
- name - just a name of module as will be listed on 'Add module' page,
for example.
- directory - the name of directory, where index.php3 for this module is
stored (index.php3 script is the one, which will be
executed after user selects the module instance from
'Module selectbox' in admin interface). It is good idea to
specify the directory using AA_INSTAL_URL constant
- table - table parameter is just optional. You can specify main
database table of the module, so then you can call
GetModuleInfo() function in order to fill an info_array by
the values specific for selected module:
$poll_info = GetModuleInfo($module_id,'P');
Now you can access $poll_info['number_of_options'],
$poll_info['title'], ... when 'number_of_options' and 'title'
are fields of poll table.
- hide_create_module - set this optional option to true, if you want to
not show the module on 'Add module' page. This
option will be false for most modules.

The record to the $MODULES array for poll module could looks like:

'P' => array( 'name' => 'Poll',
'directory' => AA_INSTAL_URL ."modules/poll/",
'table' => 'poll'),


ad 3) create tables
-------------------
You will probably need the database table(s) for your module. Create it
in database and the table definition add to both:

a) doc/aadb.sql (used for new creation of new databases)

b) sql_updata.php3 script (used for database upgrades)

For clarity, prefix the new table names by the name of module (just like
table poll, poll_options or poll_votes)


ad 4) modify modedit.php3
-------------------------
modedit.php3 is the script, which is called when user on 'Add module'
page click on 'Add' for your module.

This script is used to create and modify module instance. There user
should set all main configuration options. To create such instance you
need to:

a) add a record into 'module' table (and maybe to module specific
table, just like 'poll', ...)
b) assign permissions for the module

ad a) add record into 'module' table
Module table is generalized version of slice table any module
instance (including slices) must have its recocord in module table.
The table have the following fields:

id char(16) NOT NULL,
# world wide unique module instance id. There we store packed
version of 32-digit hexadecimal number (you probably already
know
it from slices and its displaying
(<!--#include
virtual="/apc-aa/slice.php3?slice_id=763511f38a9b960c8e7a99f765e89ff9"
-->)).
The id is there stored packed to 16 characters long string by the
q_pack_id($module_id) function. If you are creating new module
instance, the new module_id should be generated by new_id() (both
functions in /include/util.php3 file). This id is foreign key for
module specific tables (such as poll table), where more
information in the instance is stored.

name char(100) NOT NULL,
# name to be displayed in 'Module selectbox' in admin interface
(Switch to:). From historical reasons it duplicates slice.name
for modules of 'slice' ('S') type

deleted smallint(5),
# boolean value to mark deleted modules. For new module you will
set it to '0'. From historical reasons it duplicates
slice.deleted for modules of 'slice' ('S') type

type char(16),
# module type - 'S' for slice, 'P' for polls (see already described
$MODULES variable in /include/constants.php3)

slice_url varchar(255),
# URL where user could view the module instance, if it is possible
for your module type. This is the url where user jumps after
(s)he click on 'View' in upper navigation bar in admin interface.

lang_file varchar(50),
# used language file for this module instance. Language files are
located in include directory (en_poll_lang.php3,
cz_poll_lang.php3) and they are described in paragraph 6)

created_at bigint(20),
# timestemp of module instance creation. We use unix timestamps -
use include/util.php3 funtion now(). This field should not be
user editable.

created_by varchar(255),
# user id of logged user. The id could be number (if you are using
SQL based permissons) or string like 'uid=honza,ou=People,ou=AA'
(if you are using LDAP permission system. In both cases you will
get such number in $auth->auth["uid"] object variable.

owner varchar(16),
# owner is the link (foreign key) to 'owner' database table

flag int(11) default '0'
# just a module flag. Not used yet. Fill it by '0'.

ad b) assign permissions for the module
The permission to the new instance will use the same functions as the
slice
- it will use AddPermObject($module_id, "slice"). The "slice" is
there from historical reasons and in fact much better name would
be "module", but we MUST use the "slice". Do NOT use any other
string then 'slice'!!!
- Note: you can (and in fact you should) redefine the meaning of
permission letters in permission string for the module (see
/include/perm_core.php3)
- If you want to assign some permissions to specified user, use
AddPerm($user_id, $module_id, 'slice', $perm), where $user_id is
the id described in section a) by the created_by field (see
above) and $perm is the permission letter(s) we mentioned in
'Note' above.
- If you do not assign any permission to any user, only superadmins
of AA will see the module instance in his 'Module selectbox' and
will be able to change it.


The admin interface of modedit.php3 should be inspired by the interface
of 'Slice Admin' (slicedit.php3). There should be upper navigation bar
(which could be slightly modified to better fit your module - see
navbar.php3) and possibly left navigation menu, if you need to split the
module configuration to more than one page.


ad 5) modify index.php3
-----------------------
index.php3 is the script, which apears after user selects the module
from 'Module selectbox'. The admin interface should be inspired by 'Item
Manager' for slice module. This is the main administration page for the
module - most users will probably have the permission to access this
page and only a few administrators will have the permission to access
configuration page - modedit.php3.


ad 6) create language file
--------------------------
Create the language file, where you will store all texts you use in
module. The language file should be named like en_poll_lang.php3,
cz_poll_lang.php3, ... (<language>_<module>_lang.php3). The language
file MUST be stored in include/ directory (just like all other language
files). The name of this file is filled in module.lang_file table field
as described in section 4).

In the language you can define as many language constants as you want,
but you MUST there define the LANG_FILE constant, where you fill the
name of language file:

define("LANG_FILE", "en_poll_lang.php3");

All others language constants are up to you.


Notes:
------
- You can create any file in your module directory, of course. If you
will use functions, prefix its name by Mod<module letter>_, so use
ModP_GetName(), ModP_Display(), ... functions, for example.
- It is good Idea to consult the features of new module on
apc-aa-general mailinglist, before you will start the
programming.
- Please, commit all created modules to CVS (ask us for write
permissions) or send the code to AA administrator.
- Write documentation for the module in order others would be able to
use it. 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. Using mod_auth_mysql and .htaccess, http authentication can be configured to make use of the ActionApps user database.

This involves:
1. Installing mod_auth_mysql
2. Configuring .htaccess to use ActionApps user database for authentication.


Installing mod_auth_mysql
~~~~~~~~~~~~~~~~~~

(The following method works only for apache with mod_so installed)

1) Download mod_auth_mysql module from http://telia.dl.sourceforge.net/sourceforge/mod-auth-mysql/mod_auth_mysql-3.2.tar.gz ( say in /usr/local/src)
(URL for the project site: http://sourceforge.net/projects/mod-auth-mysql)
2) untar the module ( tar -zxvf mod_auth_mysql-3.2.tar.gz)
3) cd /usr/local/src/mod_auth_mysql-3.2
4) Edit the Makefile to suit your requirement. Edit the APXS and OPTS values. Sample Makefile is provided here:
------------------ Sample Makefile -----------------------------
APXS = /usr/local/apache/bin/apxs # Location of apxs binary
APXSFLAGS =
DSO = mod_auth_mysql.so
SRCS = mod_auth_mysql.c
HDRS = mod_auth_mysql.h
OPTS = -I/usr/include/mysql -L/usr/lib/mysql -lmysqlclient

all: $(DSO)

$(DSO): $(SRCS) $(HDRS)
$(APXS) $(APXSFLAGS) -o $(DSO) $(OPTS) -c $(SRCS)

install: $(DSO)
$(APXS) $(APXSFLAGS) $(NAME) -i -A $(DSO)

clean:
-rm -f *.o $(DSO)
---------------------------------------------------------------
5) run make;make install
6) mod_auth_mysql has been installed now. If successfully installed, httpd.conf will now contain the following line:
LoadModule auth_mysql_module libexec/mod_auth_mysql.so

Configuring mod_auth_mysql to work with APC-AA authentication system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Let the APC-AA DB be aadb
aadb has the table, users with the fields uid, password

now, in your httpd.conf , and in your virtualhost configuration, add the following:

Auth_MySQL_Info myhostname aadbuser aadbpassword

where: myhostname is the host where your aadb database is running
aadbuser is the valid username to access the database
aadbpassword is the valid password to access to access the db.

now, create the .htaccess file, with the following:

Auth_MYSQL on
Auth_MySQL_DB aadb
AuthName "APC-AA Secret Area"
AuthType Basic
Auth_MySQL_Password_Table users
Auth_MySQL_Username_Field uid
Auth_MySQL_Password_Field password
Auth_MySQL_Encryption_Types Plaintext Crypt_DES MySQL
order deny,allow
allow from all
require valid-user

Now, when you try visiting this location in your browser, it should prompt you for the uid/password. Provide you apc-aa uid/password to log in.

Note: Currently, this configuration does not take the group into consideration when authentication. This will be done in the next phase.

The coding standards are documented in doc/coding.html

We are moving to use phpDoc, the manual for this is at http://phpdoc.org/docs/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html, its pretty comprehensive, and there is a need for a brief version that shows how we use it - any volunteers!

Here are some hints on debugging APC-AA,
<ol>
<li>Run the same query appending: ?errcheck=1&nocache=1<br>errcheck=1 will activate checks in a few places to make sure assumptions the code is making are valid. Sometimes this helps. It also occasional generates false warnings, especially about trying to pack invalid ids.
<br>nocache=1 will make sure that fresh data is generated rather than old stuff from the cache.
<li>Add: &debug=1
<br>This will cause lots of debugging info to be reported, if the problem is with {...} expansion look for lines starting Unaliasing, Expanding, Expanded and Continuing
<li>If the problem is timeouts, add: &debugtimes=1&time_limit=1000
<br>time-limit will extend the time in view.php3, (but not elsewhere yet)
<br>debugtimes will make every debug line report at what timestamp it was run, this will help narrow the problem down.
<br>(Note: There *have* been problems with regular expressions and long strings - suspect "ereg" and replace with preg_match.)
<li>If none of this helps, Post the url to apc-aa-coders@sourceforge.net (or apc-aa-general@sourceforge.net if you aren't on apc-aa-coders)
</ol>
Unfortunately , I haven't been able to track down any kind of symbolic debugger for PHP, so it doesn't appear to be possible to do the usual ways of debugging code ....
A work-around allowing to use the POST method for sending form data to a .shtml page is in the post2shtml.php3 file. See the comments in this file.

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 concept of Tagged IDS is simple - when we store an id in a field, we sometimes want to say something about it. the idea came from the directional/bidirectional links which in fact are not stored like that, but are used internally to store one or two uni-directional links.

A tagged id consists of some string followed by 24-32 hex digits. (It should be 32, but there are some buggy shorter ids due to old bugs in apc-aa). Typically the string will be a single letter g-zA-Z or a punctuation character.

Tagged id's may not be supported everywhere yet. They are supported ....

In zids.php3, which means that most other places in the code can trivially support them transparently.

In the Slice Admin -> Fields you can set a field to Relational Window, and then use hte parameter wizzard to set which buttons to use (a set of letters matching the values of the tag), then add an extra parameter (not yet supported by the wizzard) that refers to a table.

The table is in the $tps array, defined in itemfunc.php3, if you want to use anything other than the two standard ones "AMB" (Add, Mutual, Backwards) and GYR (Good, OK, Bad) then you need to somewhere in your code do something lke

$GLOBALS[tps][MyTable] => array (
G => array ( prefix => 'Good:', tag => 'x', str => _m("Good") ),
Y => array ( prefix => 'OK :', tag => 'y', str => _m("OK") ),
R => array ( prefix => 'Bad :', tag => 'z', str => _m("Bad") ));

In the Relational window, if you have specified a table, then it will be shown as buttons - just the ones picked in the second parameter.

THIS USED TO WORK, BUT SOME CHANGE TO THE CODE BY SOMEONE ELSE HAS BROKEN IT,, AND I DON'T HAVE TIME TO FIX IT.

Note that the "tag" from this field is what is stored.

You can then use this tagged field in many ways, for example it can form part of a search string, to look for only "Good" links, or you could use a switch statement to figure out how to use it.

You should NEVER have to write code in your site to strip the tag away from the value, for example if you pass a tagged id to e.g.
view.php3?vid=123&cmd[123]=x-123-z1234567890abcdef1234567890abcdef
then view.php3 SHOULD understand this correctly as refering to item 1234567890abcdef1234567890abcdef

A new pseudo-field is created idtag........... contains the tag anywhere that GetItemContent is used to get the fields (i.e. should be everywhere). So you can put {switch({idtag...........})x:GOOD} into your code.

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