Documentation Mailing Lists FAQ Frequently Asked Questions v2

All Articles

This view is useful for saving offline or printing.

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 .

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

APC members in general, provide the following assistance in using ActionApps. This assistance can include:

• Hosting and maintenance of your ActionApps
• Content sharing with like minded organizations
• Consultation on setting up an application
• Training your staff in using it
• Assistance in customizing and configuring your application
• Continuous user support

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

Mark Surman wrote a good comparison

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

Web Networks' case studies can be viewed here

Also see our growing list of ActionApps examples

Last Edit: Apr 2 2008

Different APC providers offer different services based on ActionApps. So prices vary. For specifics, please ask your APC provider.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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:

• A Reader Management slice created
• Mailman installed, and documented elsewhere how to add lists
• Cron working and running the AA cron function for Alerts

1. In the slice you want to send mail from:
   • Create a Alerts View - (known elsewhere as a Selection)
2. Create Alerts Slice and change settings as follows
   • Create a new Alert Template - Cut and paste from Generic Alerts in a separate window
   • Make sure to set the "From" address to something that can be responded to (a human, not a list)
   • Settings -> Alert, set to the new template
   • Selections, add Alerts View created above
   • Reader Management -> set to your Reader Management slice (see note) and "Add or Refresh" (make note of field names for below)
   • Send Emails -> send a test message to yourself, it should come immediately (check in your spam folder, it often gets filtered as such), note this won't look like it does through mailman
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)
   • Can be useful to Edit item manager to ad a column for this alert (using the field names like alerts1....agxav)
   • Add the address of the new mailing list as a reader, mark it as confirmed, subscribe it to the Alert just created
   • Look for the Alerts welcome mail, which can take time (depending on Cron)
5. Now try and add an item to your slice,
   • Wait for the mail to turn up at the mailing list moderator address,
   • Follow the link into mailman and set the user filter to allow mail from this address to go straight through.

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.

Last Edit: Apr 2 2008

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:
   • name*: “My Alerts Module”
   • form URL*: this will be the public SHTML file with an anonymous form for readers to edit their subscription e.g. http://mysite.com/myalerts/update.shtml (see Step 4 below).
   • update (you can go back and edit more later)
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
   • Fill the 'OK page' with URL to subscribe_ok.shtml and 'Error page' with URL to subscribe.shtml
   • Uncheck all fields except ' Email', 'How often' and 'Selections'. Click on 'Show form'.
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:

• A clear subject line e.g. "Organization X - alerts subscription confirmation"
• Where the message is coming from and why
• A clear request to confirm the subscription by going to _#COLLFORM (alias for update.shtml)
• An explanation of what the alert is for and what kind of content
• Details about your organization.
• Contact details for any technical problems.

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:

• A clear subject line e.g. "Organization X - My Slice Alert"
• Where the message is coming from and why
• "_#FILTERS_" where the selection views of new items will be inserted.
• Details about your organization.
• Contact details for any technical problems.
• A reminder that subscription settings can be updated by going to _#COLLFORM

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Programmer's Notes: For some browsers this does not work - This is a work around and should be revisited. There are some plan for doing a PHP based permissions for Reader Managment.

Last Edit: Apr 2 2008

Last Edit: Apr 2 2008

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.
   • Admin->Views->Full Text->New:
   • Edit this view as you wish, for example it could include the _#FULLTEXT alias which could contain text about the category. This will appear above each group of categories, (assume this is view 99)
2. Create the slice where the data will be stored
   • Admin->Fields->Category->Edit
     • Input = Check box, Selected from Yyyy
     • Create alias _#VIEW_CAT with paramater "vid=99&cmd[99]=x-99-_#this
       • The _#this will be substituted by the short item id of the item related, in this case the one from Yyyy
   • Admin->Index
     • Set "Sort Items by Category"
     • Category Headline = _#VIEW_CAT (plus any other HTML wanted)

Last Edit: Apr 2 2008

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:

• Hierarchical --- uncheck to get back to the standard constant editor,
• Hide value --- hide the value box, the value will be always copied from the name
• Levels horizontal --- should the level boxes be organized horizontal or vertical?
• Level count --- count of level boxes

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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)

• Create a dummy field which will never have any text in it, mark it as Not to be shown.
• Create an alias on this field _#MOREFULL using f_c with parameters: "!:More::full_text......."
  This means print More if the Fulltext has something in it, otherwise print the dummy field, you can't just put this alias on the Full-text field or you'll get the potentially huge full-text field in the middle of those comments.
• Put _#MOREFULL in your Display/Index.

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

Last Edit: Apr 2 2008

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

• create a new slice
• copy its views from a source slice / template
• copy constants used by it to new constant groups
• add new user with Slice Editor (Item Manager) or Slice Administrator privileges
• and send her/him a welcome email message.

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:

• _#SLICNAME - slice name
• _#LOGIN___ - new user login name
• _#NAME____ - new user name
• _#ROLE____ - new user role (EDITOR / ADMINISTRATOR)
• _#ME_MAIL_ - administrator mail
• _#ME_NAME_ - administrator name
  

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:

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

Last Edit: Apr 2 2008

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

Note:

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

Last Edit: Apr 2 2008

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

Programmer's Notes: This is unstable and still needs testing
Only available in CVS

Last Edit: Apr 2 2008

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

• Don't write any whitespace (spaces, tabs) into the time units.
• Write script name into the "script" field. Use relative path from apc-aa home dir, e.g. "include/myscript.php3".
• If you need to send any parameters to the script, write them into the "params" field in form "var1=value1&var2=value2".

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)

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:

• For security reasons it is better to move the aa-http-request script to some directory, where webserver don't have access to. For example to the directory /usr/local/myscripts/aa-http-request
• Open the aa_http_request script
• Modify the HOST variable to point to your server where ActionApps are installed
  Example: HOST=aa.ecn.cz
• Modify the AADIR variable to be filled by the path to root of AA instalation from server root
  Example: AADIR=/aaa (for AA installed on http://aa.ecn.cz/aaa)
• Set LYNX or PERL to absolute path of lynx or perl if you have either of them. If neither are set, then the script will try telnet, which will not work if your server uses virtual hosts.
  Example:
  LYNX=/usr/bin/lynx
  PERL=/usr/bin/perl
• Save the changes and close the script
• In order to run this script from cron, it must have executable privileges
  ( chmod 755 aa-http-request )
• Test it, by running aa-http-request. If you have already configured some task on AA -> Misc - Cron page (you probably have), then check if 'last_run' column is changed for sheduled tasks
• Set the crontab so the script is started each 15 minutes e.g.
  crontab -e
  and put the line pointing at the aa-http-request:
  1,16,31,46 * * * * /usr/local/myscripts/aa-http-request > /dev/null

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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:

• Alerts step by step walkthrough
• Alerts Admin

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:

• _#CONTENTS - will be replaced by a list of collection filters

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:

• email is the user email address
• collectionid is the numerical collection ID, shown in the admin interface Alerts Collections. It may be an array, allowing to be generated by a multiple select box.
• howoften is one of daily, weekly, monthly
• lang is a two-letter shortcut of the user language (like cz, de, en, es, ja, ro, sk etc.)

and the following optional parameters

• ok_url with URL to jump to if the subscription is successfull
• err_url with URL to jump to if errornous

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:

• c[] is a list of collection IDs, e.g. c[]=17&c[]=25
• multiple creates a multiple select box

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:

• howoften set to one of daily, weekly or monthly
• ss is a stylesheet URL used to format the User Interface

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:

• Collections, which use some filter from some digest view defined in some Slice to which they have Admin access.
• Users which are subsribed to some Collection to which they have access. But they may only change settings for Collections to which they have 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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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

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

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

Last Edit: Apr 2 2008

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

• _#CV_NUM_D is the number of the day (to be used in a day cell)
• _#CV_NUM_M is the number of the month (to be used in a day cell, usually in an URL link)
• _#CV_NUM_Y is the number of the year (to be used in a day cell, usually in an URL link)
• _#CV_TST_1 time stamp of the current day at 0:00 (to be used in a condition)
• _#CV_TST_2 time stamp of the next day at 0:00 (to be used in a condition)

• Top HTML code must contain the <table> tag and may contain e.g. a table row with names of week days (Mon,Tue,...).
• Bottom HTML code must contain the </table> tag.
• Additional attribs to the TD event tag may e.g. set a background color to each event. If the alias _#COLOR___ contains a color, write bgcolor=_#COLOR___
• Event format is the code for the Event description.
• Start date field contains the event start date (must be filled!).
• End date field contains the event end date (must be filled!).
• Day cell top format For "Month List" calendar type it must begin with a <tr> tag. It contains a table cell tag with the day number, usually linked to an daily event list, e.g.
  <td><A href="calendar.shtml?vid=319&cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1&month=_#CV_NUM_M&year=_#CV_NUM_Y&day=_#CV_NUM_D"><B>_#CV_NUM_D</B></A></td>
  
  The view settings cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1 involve appropriate settings in the list view (no. 319 in my case) - see further. The month=_#CV_NUM_M&year=_#CV_NUM_Y&day=_#CV_NUM_D variables are used in the .php3 page to show the appropriate date - see the example in doc/example/calendar.php3
• Day cell bottom format for "Month List" it must end with </tr>
• Empty day cell top format usually the same as Day cell top format, but without the link to the event list
• Condition 1,2,3 you may use conditions with the calendar, e.g. to view only events of some type

Year and month selectboxes

List of events

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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

• group_id is the constant group name
• name is shown on the Add / Edit item page in the select box or other controls
• value is stored in database (table content) and used by slice.php3, view.php3 etc.
• class_id is used only by categories. It is an identifier of some parent - APC wide - category, usefull when importing items between slices.
• pri is the priority used to sort in the select box etc.

When to use different name and value

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

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:

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

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

• Define e-mail template

  To do so, you have to

  • go to any Alerts module (or create one, if you haven't it yet)
  • go to 'Alerts Setting' -> 'Email Templates'
  • create new e-mail template (of 'other' type), where you will use any discussion alias in Subject or Body (see: http://actionapps.org/faq/detail.shtml?x=261)
  Versions of AA prior to 2.6 uses special 'Discussion To Mail' view for e-mail definition. This is deprecated, now.
• Create a field with 'name'! "DiscussionMailList" in the slice, where the discussion items are. The 'type' of the field is unimportant.
• Fill the field in items the discussion of which you want to send by email

  The DiscussionMailList field value is a parameter list in the usual format, separated by ":" and using "#:" instead of verbatim ":". The parameters are:

  1. E-mail template ID (the one created before) prefixed by 't' character (like t21) (without the 't' letter it specifies ID of special 'Discusion to Mail' view, which is no longer used - deprecated)
  2. E-mail address to which to send new discussion comments (probably mailinglist)
  3. The remaining parameters (3rd until 9th) may be used in the view definition as aliases _#ITEMPAR3 .. _#ITEMPAR9. They help you to create only one view reusable for all items.
  
  Example: t13:our-l@list.org.cz

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

Last Edit: Apr 2 2008

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

Default values for discussion view

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

Top HTML

HTML code for index view of the comment

Bottom HTML

Show images

Order by

View image 1

View image 2

View image 3

View image 4

HTML code of the form for posting comment

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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}

Last Edit: Apr 2 2008

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.

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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

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.

Last Edit: Apr 2 2008

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:

• The content of each field is copied to the destination slice (there is one exception - see the STATE_UNFEEDABLE flag in following text)
  
  
• The content is copied including the HTML codded / plain text flag
  
  
• The field is fed to the destination field with the same field_id as default (headline........ goes to headline........ field). This can be changed in the feedmap table, where you can map fields to another ones (See "Admin" -> "Content pooling - Mapping"
  
  
• flag FLAG_FEED is set for each stored value (see FLAG_* definitons in following text)

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

• feedable (STATE_FEEDABLE) - the content of this field is copied to the new slice and user in the new slice can freely edit it
  
  
• unfeedable (STATE_UNFEEDABLE) - the content of this field is never copied to the new slice
  
  
• feedable, but locked (STATE_FEEDNOCHANGE) - the field is copied to the new slice, but the flag FLAG_FREEZE is set for the field, so the user in the new slice can display the content of this field, but she can't change the value
• feedable with update(STATE_FEEDABLE_UPDATE) - the same as STATE_FEEDABLE, but if the content of source field is changed, the content of the destination field is updated too. Editor of the destination slice can change value of such a field, but when someone changes the field in the source slice, the value is rewritten.
  
• feedable with update and locked (STATE_FEEDABLE_UPDATE_LOCKED) - the same as STATE_FEEDABLE_UPDATE, but the editor of the destination slice can't change the value of this field.
  
  

• Feed (= STATE_FEEDABLE) - copy the content of the source field once (to the destination field)
• Do not Feed (= STATE_UNFEEDABLE) - do not copy the content of this field to the destination slice
• Feed locked (= STATE_FEEDNOCHANGE) - copy the content once, but forbid editors of the destination slice to change the value of this field
• Feed & update (= STATE_FEEDABLE_UPDATE) - copy the content and update the content of the destination field each time the source field is changed (content sharing)
• Feed & update & lock (= STATE_FEEDABLE_UPDATE_LOCKED) - the same as before, but editors of the destination slice can't change the content

• FLAG_HTML is allways copied from the source field
  
  
• FLAG_FEED is allways set for fed fields (currently it has no specific use - we just mark the fed content)
  
  
• FLAG_FREEZE is set if the source field has STATE_FEEDNOCHANGE flag set. In other cases this flag is unset. All fields with FLAG_FREEZE are never displayed in the input form so they can't be changed by the user in the destination slice.

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.

Last Edit: Apr 2 2008

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)

Last Edit: Apr 2 2008

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.

• Slice Admin -> Content Pooling -> Nodes
• Set the Node name to the ORG_NAME of the remote node. (You can ask the superadmin of the other node to get their ORG_NAME by looking at their "Nodes" page).
• Set the "URL of getxml.php3" to the url of the script on the remote host. For example if the other nodes admin pages are at http://foo.com/apc-aa/admin then their getxml.php3 is http://foo.com/apc-aa/admion/getxml.php3. (You can ask the other superadmin to look at their Nodes page and tell you their value).
• Agree a password with the other superadmin, and fill it in on both nodes.
• 'Submit' the form.

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.

• Go to the slice which you want to export,
• Go to 'Slie Admin-> Content Pooling -> 'Inter Node Export'
• Select the node from the list of remote nodes. If you do not select any node, the item exchange is permitted to all nodes!
• Fill the user id of the user who has admin permissions on the slice where the input is happening and will set this up. This id you will get from remote node administrator. It can be an LDAP id (like uid=peter,ou=People,ou=AA), or the SQL user number of the user (like 31) (well, it is not easy to get it - you can look into database, or you can display the edited_by....... field in Item Manager). If you do not fill the user, then item exchange can be setup by any remote node slice admin.
• 'Submit' the form.

3.2 On the importing node,

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

• Go to the slice where you want the import
• Go to 'Slice Admin->Content Pooling -> 'Inter Node Import'.
• Select the node from list and click on 'Create new feed from node'.
• This will get the list of slices available for you from the remote server.
• On this page select the slice and click 'Select slice'

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 

Note this is a complex question, with a complex answer I don't quite understand, but it seemed important enough to put here until someone rewrites it!

On 26 Oct 2001 at 16:27, John Hall wrote:


> Here's a question from rabble.ca, reviving a thread started on this
> list in April ("Linking Back to Parent Items ...").
>
> I'll provide a simplified example. The problem involves a sharing
> relationship between two slices: "Child" and "Parent."
>
> ==========
> The slices
> ==========
>
> 1. "CHILD"
> - feeds items to "Parent"
> - slice definition includes a 3-member constant set: "first",
> "second", "third" - any item's full-text shtml template is determined
> by the constant value selected for that item (i.e. ../first.shtml,
> ../second.shtml, ../third.shtml)
>
> 2. "PARENT"
> - receives items fed from "Child"
> - receives items fed from several other slices
> - headline hyperlinks of items fed from "Child" must point back to
> "child" slice (i.e. child shtml templates + child item_id)
>
> ==========
> The problem
> ==========
>
> We can use the go.php script to automatically point "parent" headline
> hyperlinks back to "child" items.
>
> But we can't make this script respect the constant values that
> determine which fulltext shtml template to use.
>
> ==========
> The solution?
> ==========
>
> The simplest-sounding solution would be for "parent" slice alias to
> have access to the corresponding "child" item_id. Is this possible?
>
> If not, does anyone have any other ideas?... :)
>
> (Someone suggested replacing the "parent" slice with a new view on
> "child." This won't work here -- because "parent" aggregates items
> from many slices.)
>
>
>
> Thanks ... John
>
> P.S. This is a lot of info. Please let me know if anything unclear!

Honza replied
Hi John,


I think the easiest solution to this problem is to modify
/admin/se_mapping.php and /include/feeding.php3 scripts in order you can map the
id.............. and short_id........ fields too. From my first look I think, it
is not so big problem to show Id and Short Id in "From" column of
se_mapping.php3. Then you just create any "Child id" field in PARENT slice and
there you will map the short_id (or id) of item in CHILD slice.


Honza

Last Edit: Apr 2 2008

At this point there is a bug that mapping is only available when Automatic feeding is enabled. For now the workaround is:

set automatical feeding between the slices (Admin -> Content Pooling -> Inner Node Feeding)
set field mapping (Admin -> Content Pooling -> Mapping)
disable automatical feeding (Admin -> Content Pooling - Inner Node Feeding).

From this point the manual feeding will accept the mapping.

Last Edit: Apr 2 2008

Add

<a href="/apc-aa/go.php3?sh_itm=_#ITEM_ID#&type=fed">fed from</a>

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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:

Prefix	Allowed Values	Where 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

• The parsing of the mapping syntax is defined in xml_fetch.php3:map1field
• The default mapping, used by new feeds, or where mapping has not defined, is in csn_util.php3:default_rss_map
• The conversion between XML path and field names is in xml_rssparse.php3:charD, endElement and startElement
• The hard coded search for content is in xml_fetch.php3:contentvalue and xml_rssparse.php3/charD

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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:

• sort files by clicking on a column header
• edit Text and HTML files after clicking on them. If you don't have permissions, the file is only viewed.
• view Images by clicking on them
• change file names and download them after clicking on them
• create new files and directories
• upload files
• delete files and directories
• copy templates (optionally, see further)

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.

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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:

• check whether the file to be uploaded has proper type (image) and upload only such files (this works for any file upload fields, for example you can specify limit to application/msword or application/*)
• check if picture is bigger than maximum dimensions set in field parameters. If yes, image will be resampled to maximum dimension (aspect ratio maintained).
• if there are set any "other fields" (in this example "image.......1" and "image.......2"), function will also fill-in these fields with url to the same picture. If there are maximum dimensions set in parameters of these field(s), function will resize image accordingly.

Limits of the function:

• image functions work only if there is GD library installed (GD is standard part of PHP since PHP version 4.3.0)
• Image resampling functions work only with GD supported types (JPG, PNG, WBMP - not GIF - GIF will be supported since July 7th, 2004, when LZW patent expires world-wide)
• secondary image fields must be in the input form after source field
• filling of secondary image fields is not recursive (secondary image fields can not be defined in a chain)
• there is no error reporting

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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

5. go to Admin - Fields - Related field Edit page
6. 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
7. go to 'Admin - Design Fulltext' page (for example)
8. Add next code to 'Fulltext HTML code' field:
   <br>Related: _#SHOWVIEW
9. 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

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>

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

How to search in multiple slices

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

• param --- consists of the constant group name and the parameters like in the Input type "Hierarchical constants" to it --- see the Wizard with Help for more parameter details
• varname --- the name of the select box, e.g. conds[1][value]. Note: the real select box in the page will have [] added to the name, i.e. conds[1][value][]
• optionally lang_file --- the language file to be used, defaults to en_news_lang.php3

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

Last Edit: Apr 2 2008

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> 

• The action atribute on first row points to some file, where slice.php3 script is included (by SSI)
  

• There are two visible search fields on the form --- each of them uses a bit different syntax - conds[0] uses the simplified and conds[1] the extended syntax.

• The conditions are allways joined by AND operator --- items must allways pass all specified conditions.

conds --- simplified syntax

• search only in one field for that specified phrase
  

• use standard searching operator "LIKE" --- the search phrase may be anywhere in the middle of any word (e.g. the phrase "los" will get items with field content "los", "Carlos" or "lost")

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:

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:

[field_id]

Specify the fields to be searched through by their IDs.

sort

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

Last Edit: Apr 2 2008

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

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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

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

Last Edit: Apr 2 2008

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

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

Last Edit: Apr 2 2008

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:

• Modify the setting for the 'News (EN) Template' slice on "Admin" pages. New slices based on the modified template will be set-up by the new setting in template slice.
  
  
• Create a new application (= template)

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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.

Last Edit: Apr 2 2008

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_id	short_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_description	description (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:

   • It runs only on http:// sites (https:// is not supported until PHP v4.3.0 will be released)
   • There is also limited size of included file. The default limit is 400kB, but you can change it by INCLUDE_FILE_MAX_SIZE constant in config.php3.
   • Also you should know, that each include generates one more HTTP request to server. That's why also the performance is not as big as for the other alias types.
   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)
    description	can be any text or html and is displayed before result of expression ("#:" mean ":")
    expression	in 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
    end	text to be shown after page numbers
    add	option to be added to page number <a href=".." class="blue10v">1</a>
    nopage	text 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