Documentation Mailing Lists FAQ Frequently Asked Questions v2

_#BROWSETL

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

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

"register_globals = Off"

set this to On and restart Apache.

See the manual section 3.7 for instructions.

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

• newer versions: look in include/lang/ [add more details]
  Older versions:
• include/en_common_lang.php3
  
  - this is the file with language constants definions which is common to all slices in the AA instalation (e.g cz_common_lang.php3 is the same file for the Czech language)
  
  
• include/en_news_lang.php3
  
  - this is the file with language constants definions for specific slices. It is possible to have slices in different languages. You can choose the language used on the "Admin" -> "Main settings - Slice" page. Hence if you want to have slices in French, you have to copy en_news_lang.php3 to a new file (fr_news_lang.php3 for example) and translate the texts to French to fit your needs.
  
  
• texts in template slice News (EN) template (see Templates section)
  
  
• texts in fields templateslice Action Aplication Core (see Templates section)

• 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

New settings in config.php3

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


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

Slice settings

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

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

Templates

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

• _#SLICNAME - slice name
• _#SLICE_ID - slice id

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

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

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

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

Set the Validate/Insert field to "File"

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

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

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

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

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

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

or, even better:

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

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

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

This presumes you have:

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

Next suggested steps for the upgrading the FAQ:

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

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

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

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

 - JD- - - --

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

The solution:

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

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

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

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

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

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

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

Exceptions:

• You don't have to put a .shtml at the top - you can just use a more complex URL refering to apc-aa/slice.php3 or apc-aa/view.php3
• You can include a view from within an alias by using the function f_v

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

Database structure used for items

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

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

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

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

To select all extended fields for the item use:

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

Item data manipulationg functions (data API)

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

Main AA data API functions are:

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

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

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

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

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

Item data structure

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

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

<unpacked_item_id>

is 32 characters long hexadecimal id of item (structure holds data for more than one item, generaly)

<field_id>

is field id as you know it from Admin -> Fields page of AA admin interface ( like 'headline........', 'url............2', ...)

<alternative>

is number used for storing multiple values for the same field. Obviously there is only '0' index, but for field, where we store multiple categories (for example) it will utilize indexes '0', '1' ,... up to number of selected categories for the item

<value

is probably what you care about - it is content of the field like 'An article title' or 1092928827 or <fulltext of item>

flag>

special flags for the content - if the content is HTML formatted, ... The list of possible flags follows (defined in include/constants.php3)

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

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

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

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

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

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

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

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

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

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

How to search in multiple slices

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

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.

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

Note: The key expires after 90 minutes

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

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

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

Example of condition fields in a view design:

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

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

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

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

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

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

 

AuthType Basic

  AuthName &quot;Authenticate yourself&quot;

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

    Require user logout

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

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

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

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

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

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

What is Done:

• New slice in new database is created based on oldSliceTemplate (the slice id is the same as in old database)
• old format strings are copied to the new slice
• all fields in new slice are set is in old slice (defaults, visibility, required, ...)
• categories are copied and added to constants as it is obvious in AA v1.5+
• all fields of all items in source slice are copied to the new database
• relation table is updated and feeding relations is stored there

Limitations:

• permissions for slice is not copied in case you are using SQL version of permission system (in fact, the oermission is not copied in LDAP version too, but it is obvious, that old AA and new AA share the same LDAP tree, so the copy of permissions is not needed)
• field names are allways the same and it comes from en_news_lang.php3 (see Admin - Fields for change the names)
• Show on URL (redirect) field is copied to the new database, but alias (_#HDLN_URL, ...) do not count with this field. You should set the new alias in order you get the same result as in old database
• the defaut expiry date can be set different in old and new database in some cases (see Admin - Fields - Expiry date Edit - Default)
• automatical search form is not implemented in AA v1.5+ - all search settings are removed

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

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

to point to new AAv2.0 installation directory:

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

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

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.

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.

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

In general use the $err array to return errors.

Some specific examples follow, please add others here.

Each of the functions: insert_fnc_xxx sets for example

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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

The APC AA has a Two Layer category system:

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

2) Totally flexible page-specific categories

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

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

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

1. Create a slice, called for example Yyyy where your categories will be stored.
   • 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)

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.

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

• nothing - standard "no item found" message is displayed (this setting is historical)
• any text - the text is displayed. From AA v2.6 you can also use aliases and other AA expressions like {switch()...}...
• <--Vacuum--> - if you use this keyword (exactly!), nothing is displayed.

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

The hit is counted in this cases:

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

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

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

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

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

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

No, it is not possible - at least yet.

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

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

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

Step 1: Create a Reader Management Slice

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

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

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

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

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

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

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

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

Alerts Selection Set: “My Slice alert views”

Group by selections (ignore for now)

Alerts Selection 1 Description: “All My Slice Items”

conds[] (ignore for now)

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

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

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

Click Update

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

Step 3: Create an Alerts Module

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

1. AA > Create New > Alert, settings:
   • 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 ...”

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.

• sliceID - ID of slice into which you want to import
• fileName - name of the file being imported
• separator - the string which separates the field values
• actions - an array describing how to import - see further
• postedBy - to be inserted into the postedBy and editedBy fields, the SQL user number or LDAP string (for LDAP users)
• fire - if true, writes the data into the database, if false (default), only shows the data in their final shape
• timeLimit - how many seconds may the script work before the server considers it unavailable (default=120)
• statusCode - where to put the item: 1 (default) - Active items, 2 - Hold Bin
• publishDate - if set to 0 (default), fills in the current date, otherwise fills in given value. Use a Unix time-stamp, i.e. number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT).
• expiryDate - if set to 0 (default), fills in 200 years after publishDate, otherwise fills in given value. Use a Unix time-stamp, i.e. number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT).
• maxRowLength - max length of one line (default = 50000)

Actions

• store - simply stores the content of "from". Params:
  • from - name of a field in the text file
• storeparsemulti - splits content of "from" and stores the result as a multi-value. In our example, Johny Bravo will be in both the categories "VIP" and "fools". Params:
  • from - name of a field in the text file
  • delimiter - string which separates the values
• storetrans - translates the content and stores it. In our example, France Newman will have "english" as his language. Params:
  • from - name of a field in the text file
  • trans - array containing translations
• storeasmulti - takes the values of several fields and stores them as one multi-value. Params:
  • from - array of fields to be stored together. E.g. "from" => array ("Name","Middle Name","Surname")
• storemultiasone - takes the values of several fields nad stores them as a single value seperated by the delimiter. Params:
  • from - array of fields to be stored together. E.g. "from" => array ("Name","Middle Name","Surname")
  • delimiter - string to put between fields e.g. "delimiter" => ", "
• bool - stores "1" if the given field contains "1", nothing else. Params:
  • from - name of a field in the text file
• web - adds "http://" to the field if not beginning with "http" and not empty. Params:
  • from - name of a field in the text file
• storeboolarray - stores constants if the given fields contain "1". Stores the result as one multi-value.
  • from - array of fields and assigned constants. E.g.: "from" => array ("Bool1" => "Bold", "Bool2" => "Italic", "Bool3" => "Underline")

A fully functional example script

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

require "./importer.php3";

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

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

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

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

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

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

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

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

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

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

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

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

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

or in the URL.

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

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

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

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

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

The right alias is _#ITEM_ID#.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

However they can take parameters from the URL

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

For example,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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>

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

The destination page should contain a HTML tag like:

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

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

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

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

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

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

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

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

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

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

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

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

Some examples of what may be done:

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

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

Predefined functions

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

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

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

Field Triggers

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

function aa_onTrigger (fieldid) { trigger body }

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

Solution to the examples

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

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

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

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

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

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

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


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

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

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

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

An example set-up:

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

This answer covers point 3) - jsview.php3

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

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

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

the new javascript code in page.shtml would be:

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

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

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

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

Automatical feeding

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.

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.

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 

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

• Item Listing - these are used like the main Index view to generate a list of some or all the items in a slice.
• Fulltext View - these are used to display a single item.
• Item Digest - not sure what these are.
• Discussion - used for creating discussions
• View of Constants - used to display list of constants (ie. categories).
• RSS Exchange - used to exchange items with Content Management Systems that use this standard
• Static Page - these are a bit like macros, they are not related to a specific item or slice, but can be used where the same content, or parameterised content is needed on many pages.
• Javascript item exchange - used to view items on a site without AA installed.
• URL Listing - special view used mainly for creating list of links to all articles in the slice, which is used for search robots and fulltext indexers like Google, HtDig or MnoGoSearch. It is very similar to Item Listing, but you can use just very limited set of fields and aliases, so there is no problem with "memory limit".
• Calendar view is a complex view used for showing event items within a monthly calendar.

• Link listing and Category listing views are used for Links module - you can customize the design of links listing and category listing just like jot normal AA items. The usage is analogous to Item listing and is quite simple, but deep documentation of those views wait for someone, who will have resources to document Links module.

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

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

Back-up Your Files and DB

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

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

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

cvs -n update

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

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

If it all looks good, run

CVS update -dPAC

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

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

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

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

On you index view...

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

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

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

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

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

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

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.

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

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

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

Web Networks' case studies can be viewed here

Also see our growing list of ActionApps examples

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

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

Example:

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

• 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

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.

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

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

All you have to do for new function is:

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

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

• $columns - array of content of each field in item (for example
  $columns[headline........][0][value] = "This is item title"
  
  • value last array dimension - select between value and flag. Value is field content flag could be FLAG_HTML | FLAG_FEED | FLAG_FREEZE | FLAG_OFFLINE | FLAG_UPDATE
  • 0 - used for multivalue fields (as categories in some slices). For single values we use just 0, for multivalues we use 0, 1, ...
  • headline........ - field id
    
• $col - field id of column for which the alias is definned
  
  
• $param - parameter passed to function from textfied in alias definition (just like usr_cz_date:1). The name of function is in param too!!!

<?php //usr_aliasfnc.php3  

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

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

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

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

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

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

1. Add new task on cron admin page

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

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

• 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

Requirements for ActionApps Unix Hosting

• Strongly prefer Apache
• Ability to create crontab (but this only needs to be done once, so could be done by the hoster).
• PHP version 4.3+, safe mode turned off, with mail function enabled
• At least one MySQL 3.2x database
• SSIs local to virutal server account
• Shell access (mostly for updating from CVS)

Optional:

• HTACCESS (used for Reader Management permissions)
• Mailman mailing lists with list creation/deletion control (not necessary, but AA Reader Management has some options for admining Mailman list subscriptions.
• SSIs to other virtual server accounts (if you want to share an APC-AA install between different virtual server accounts)
• MysqlAuth (Apache Module) if you want to use Reader Management persmissions

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

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

1. Choose a slice and create the set of fields you want to have in the new application.
   
   
2. For these fields change the default values, help texts, names, priorities, aliases, etc. in the admin interface ("Admin" -> "Main settings - Fields").
   
   
3. Change the design of the fulltext view, list item view and possibly the admin view ("Admin" -> "Design - Fulltext", "Admin" -> "Design - Index", "Admin" -> "Design - Item Manager")
   
   
4. Test the new slice, whether it is working O.K.
   
   
5. Add a new slice based on this one (not a template, but a slice)
   
   
6. Mark the new slice as a Template ("Admin" -> "Main settings - Slice") - to do this you must be the superadministrator (four stars).
   
   

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

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

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

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

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

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

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

Edit the file, then

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

$ cvs add myfile.htm

then upload with for example

$ cvs commit myfile.htm

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

Note, Its best NOT to do a plain

$ cvs commit

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

If you get the error:

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

Then you need the ssh trick.

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

(main) developer 2.1.0
stable 2.0.1

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

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

If you check out the default method:

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

you will get the developer branch, but

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

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

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

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

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

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

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

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

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

1. unalias (expand) whole text (replace aliases and any other AA expressions)
2. remove all specified remove strings

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

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

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

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

In first step the emtpty aliases are removed:

=> _#HEADLINE ()

Then the "remove strings" are removed:

=> _#HEADLINE

and then the remaining aliases are substituted.
IIS is not a supported platform for APC-AA or at least it is not tested on this platform. There were some limitations in IIS v4.0 (I'm not sure, how it is in v5.0), which makes AA half-usable. There was a problem of not passing url parameters
to a script, which is included by SSI include into an shtml page.

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

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

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

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

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

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

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

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

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

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

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

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

Notes for Translators

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

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

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

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

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

Notes for Developers

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

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

_m("any string").

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

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

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

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

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

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

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

Hope you will like my mgettext solution,

Jakub

The coding standards are documented in doc/coding.html

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

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

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

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

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

• 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

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.

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

• _#this is replaced by the content of the field we are working on, typically this is the long id of the item being referenced. If there are multiple id's they are strung together seperated by "-" which is what view.php3 expects in its parameters.
• _#slice is replaced by the slice id.
• _#unpacked_id is replaced by the id of the record as output by f_n.
• _#id.............. will get the id of the record, (unclear if this is unpacked or packed)
• _#short_id........ will get the short id of the record
• _#slice gets the id (unclear if packed or unpacked) of the slice
• _#headline........ (or any other field) will get that field, or a list of them separated by "-"
• In addition any of the { ... } syntax can be used, (See How to Use Aliases)

This FAQ interface was developed by Jason at Commons.ca

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