|
Frequently Asked Questions v2
|
Browse:
0. What are ActionApps?
1. What's the benefit of Content Pooling?
2. Who can I create a Content Pool with?
3. How do I get ActionApps?
4. What specific ActionApps are available?
5. Where do I go for user support?
6. Is there a manual available?
7. Error: setup.php3 just recycles the same page
8. How to create an aa in an alternate language?
9. Is my information protected?
10. Can the APC ActionApps work in my language?
11. Do I need special computer qualifications to use the APC ActionApps?
12. Can the APC ActionApps infect my computer with viruses?
13. Who will read my information?
14. How can my APC network help me use APC ActionApps?
15. Are APC ActionApps open source?
16. Password-protected public editing
17. File Manager Administration
18. How can I let users with the 'author' permission edit their own items?
19. How do I upload files into a slice
20. How to make item url shorter?
21. Alerts/Mailman Integration
22. What are the plans for the FAQs?
23. How to import big exported slice&data?
24. What is Reader Management?
25. Where is the HTML
26. How does ActionApps compare with PHPNUKE, Zope, and other content management systems.
27. Can apc-aa send email? What is the Email Notification control panel for? How do I notify someone of a new item, or an item in the holding bin?
28. How to use aliases
29. How do I control whether new items appear in the Approved or Holding bins
30. What are the 'Action Aplication Core' and 'News (EN) Template' slices?
31. How do I use add one of the fields in the drop-down at hte bottom of the Admin->Fields screen
32. Rich Text Editor
33. Jump module
34. Create new Wizard
35. How to show integers but not show 0?
36. What is the value of a check box input?
37. How to push/pull data into/from database
38. How to refill conditions on searchform?
39. Searchform extensions
40. How to setup searchform?
41. How can I modify the fonts used in the AA interface?
42. How to use images in a slice ?
43. How does a user retrieve a forgotten password from reader managment?
44. How to display archive (expired items)?
45. How do I create a Reader Mamagement logout function?
46. How are mutual related links propogated?
47. How do I set up Htaccess permissions sync with Reader Management?
48. How to transform the old slice (from AAv1.2-) to the new database structure (used in AAv1.5+)?
49. AA Alerts
50. Alerts step by step walkthrough
51. Alerts Admin
52. How should I return errors
53. two level menu view
54. ERROR: "No slice found for you" - I lost me installation ID ("AA_ID" in config.php3)
55. Constants and Categories
56. What is the parent category?
57. How do I customise the Category breaks in an index view from another slice
58. Hierarchical constants
59. How to integrate APC-AA with email
60. How "No item found" message in view definition works?
61. When are hits counted?
62. Is there a way to allow different users to log in to the same slice but with their own language choice?
63. How to create a simple email alert module
64. How can I include photos to the texts of articles?
65. MultiLingual eXtension for ActionApps / How to setup ActionApps for multilingual web sites
66. How to import lots of data into a slice?
67. What tools are available for importing data
68. How do I make a slice with lots of fields? The web interface takes too long.
69. Which should I use, Item Listing View (View.php3) or Design-Index (slice.php3)?
70. What are Views good for?
71. How to display icon for Highlighted item on Item Manager (or public website)?
72. How do I create a Index of some items
73. How do I include this View in a HTML page?
74. How do I sort items within a View?
75. How do I include Previous and Next in the scroller of a View.
76. How do I select a sub-set of items from a view
77. How do I view just highlighted items on a page.
78. How do I make it view just a single item?
79. How do I link a Index view to show the items in a Full Text view
80. What is a Static View and how do I use it
81. How can I parameterize a view and fill in details from the URL
82. How can I change a piece of content on a page, for example a context-dependent Navigation menu
83. How can I use the related items feature to link items from one slice into another
84. How do I use a Javascript view to see pages on a site where AA is not installed
85. Which parameters can I use with view.php3
86. What are the wizards for parameter generation, and how do I use them
87. How to create a Calendar
88. Field Triggers
89. What is Content Pooling?
90. How do I automatically feed only select items to other slices?
91. How to set the off-line filling up?
92. How to edit items in public website?
93. How to create a form allowing anonymous posting from public website?
94. How to edit items non-anonymous from a website
95. How do I use jsview.php3 to view pages on a site where AA is not installed
96. How do feed items from one slice to another
97. How can I control which fields are fed, and whether they are editable
98. I want to feed highlighted items from several slices to the front page.
99. How to setup Cross server networking (CSN)
100. Feeding: How to access the id field in a parent
101. How can I set mapping on Manual feeding.
102. How to link parent item?
103. What are the different kinds of Views on the Admin->Views page?
104. How do I update my APC-AA installation to the latest version?
105. Designing nice search results
106. Discussions as message boards
107. How do I setup discussions?
108. How to use Site Module
109. How to use Live checkbox (Auto Update Checkbox)?
110. Error: Access denied for user: 'aadbuser@xxxx'
111. What can ActionApps do for my organization?
112. What are real world examples of organizations using ActionApps?
113. How can I manipulate images (e.g. create thumbnails)
114. How do I create an RSS feed from a slice
115. What are the Parameters of the Alias Functions
116. Which parameters can I use with slice.php3
117. How to create new alias function?
118. Cron - how to automatically run tasks on given time?
119. What are the hosting requirements for APC-AA?
120. Where can I read about developing APC-AA applications
121. How much do ActionApps cost?
122. How to contact the developers
123. How to create a new Action Aplication
124. If I am a developer, how can I contribute?
125. How to edit a file and check it back into the distribution
126. Can I run APC-AA on two web servers accessing a common database
127. What are the CVS branch version numbers of APC-AA and how do I check out a specific versio
128. I have limited access to my box, how do I access PHPLIB
129. How do I create my own validation function
130. Can I call apc-aa item-manager from other php3 code
131. How do I fix a corrupt database
132. Which strings exactly are removed from Views?
133. Can I run APC-AA with IIS and Windows
134. How do I get rid of the "?" by each input field
135. How can I look at the database with Perl?
136. Rich Text Editor icons
137. How do I setup my installation for file uploads
138. How does file upload work
139. Language files with Mini Gettext
140. Using remote or remotec to display APC-AA on another web server
141. How to create new module?
142. Field Types and Alias Functions
143. How to configure mod_auth_mysql for HTTP authentication with ActionApps authentication system
144. What coding standards should I follow
145. How to debug Action Apps code and sites?
146. POST to .shtml
147. Protecting sensitive data against reading
148. Is it possible to add new users from public website?
149. How do I link to fulltext if, and only if, there is some fulltext
150. How do Tagged IDs work
151. File Manager
152. How do I set mapping on RSS import
153. What paramater substitution is done in f_v
ActionApps are publishing tools that plug into websites. With ActionApps,
publishing news and information online is as easy as filling in online forms.
Their unique Content Pooling technology enables organizations to exchange
articles between their sites. For more details, see About
ActionApps .
There are two general kinds of benefits:
- Content - Pooling can give you access to a fresh stream of content for
your site (in the form of your partners' articles); and
- Publicity - Pooling can help you get your own content out to new audiences
(whenever you partners reprint your articles).
You can create a content pool with any number of partner sites. All of your partners must be subscribing to ActionApps with the same APC provider.
ActionApps are offered as site plug-in services by individual members of the Association for Progressive Communications (APC). The APC itself does not offer ActionApps services directly. To find an APC provider near you, go to Get ActionApps
Different APC providers offer different services based on the ActionApps platform. In general, most APC providers can offer a solution for publishing events, news, action alerts, press releases, contact lists, and similar articles/listings. For specifics, ask your APC provider.
Only the service provider providing your ActionApps can support the service. This is likely to be an APC member. The APC itself cannot directly support individual ActionApps users.
Yes, there is. It is currently available in English and will shortly be available in Spanish. Visit our downloads section to get your own copy to print out, or read it online.
If hitting "Init" on the setup.php3 page just comes back to the same page, then its probably because your php.ini file contains
"register_globals = Off"
set this to On and restart Apache.
See the manual section 3.7 for instructions.
If you want to translate the ActionApps to another language, you can look at:
- 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)
The information you post on the WWW using AA is equally secure as it is without it. Permissions of the users of ActionApps are individually defined, and unless you give your password out, or you choose a too trivial password that is easy to guess, your items are only available (for republishing) to those whom you deliberately share them with.
Yes. It is the responsibility of your local APC service provider to create local language versions of the applications. The software is specifically designed to flexible language management.
No. You can handle every aspect of the work by using a Web browser (Netscape or Internet Explorer), and simply copy and paste (or type) text. When setting or changing the layout of your application, an html (Web editor) expert is needed, but your APC provider can give you the necessary assistance.
No. ActionApps use only HTML (web) files, which cannot contain viruses. If an item in somebody’s application contains a link to a downloadable file (word document, excel sheet, image or sound files, etc.), those files my be infected just as any other file of those kinds, which are downloadable from any sorts of Websites.
Your information is posted on an Internet Web site, where any Internet user can read it who learns about its address (unless you use ActionApps for internal purposes in a Web site, where readers access is password protected). The advantage of using ActionApps is that posted only once, your information can become available on several Websites and can get more publicity.
APC members in general, provide the following assistance in using ActionApps. This assistance can include:
- 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
Yes, the ActionApps are licensed under the GNU General Public License. This means you can install the software for free on your own server. It also means you can make modifications or upgrades. These modifications can either be submitted for integration back into the main Action Application code or released as separate modules. Either way, modifications to the ActionApps must be released for public use under the GPL.
Items posted from a public website may be protected by a password. Suppose you have a field with ID "password.......x" (just like password.......1) in your slice and this field is visible on the public posting page. The user fills in the password when creating a new item. When using the script fillform to edit a public posted item on public pages, the password is not re-filled (all other fields are). But the script filler.php3 does not store the changes if the user does not refill the password correctly.
The scripts recognize the password field by ID "password.......x" - you can add such field in standard way on "Slice Admin" -> "Fields" page - derived from "Password" field template (the Reader Management slices already have such field in its default configuration).
New settings in config.php3
# mkdir perms, set by variable because constants don't work with octal values
$FILEMAN_MODE_DIR = 0770;
# create file perms
$FILEMAN_MODE_FILE = 0664;
define("FILEMAN_BASE_DIR","/www/apc-aa/wizard/");
define("FILEMAN_BASE_URL","http://work.ecn.cz/apc-aa/wizard/");
define("FILEMAN_UPLOAD_TIME_LIMIT",600);
FILEMAN_MODE
sets the Unix rights for all files and directories
maintained by the File Manager. Specific directories for individual slices are
created in FILEMAN_BASE_DIR
, specify the name of the directory
belonging to a slice in Slice Settings (only superadmins!!). The FILEMAN_BASE_URL
is the web path to the FILEMAN_BASE_DIR
, and FILEMAN_UPLOAD_TIME_LIMIT
(in seconds) is useful when uploading large files.
Slice settings
Superadmins can set for each slice if administrators may access the File Manager
and set the directory name. A directory name must be filled in order that administrators
may use the File Manager. If the directory does not exist, it is created at
the first usage of File Manager.
There is a difference between what a superadmin sees and what a slice
administrator sees. The base directory for superadmin is FILEMAN_BASE_DIR
,
so you see the directory name when entering File Manager and you can jump to
the parent directory. But slice administrators have access only to the particular
directory and they don't see the directory name.
Templates
You can create templates consisting of several files. Some aliases are defined:
- _#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.
The 'posted_by......' field must be recorded for each submitted item.
So, it should be a required field in 'Admin->Fields' . It does not have to
be 'Shown', just 'Required'.
If this is done, only items that a user has permission to edit will be visible in the item manager for them.
First, your System Administrator has to setup the apc-aa, see below
Then edit one of the fields, e.g. SliceAdmin-Fields-ImageURL-Edit
Set the type to "File upload" and use the Wizard to set the file type to for example image/* or */*
Set the Validate/Insert field to "File"
The field will then show up with a pair of fields, one where a URL can be entered, and the other where a file can be chosen. You may wish to take care on picking the help text for these fields as it can be confusing to figure out whether to fill out both fields or just one.
Why are slice IDs and item IDs so long?
Would it be possible to make them shorter?
The 32-digits hexadecimal IDs are quite standard in MySQL/PHP - see uniqid() and md5() functions. These identifiers are intended to be unique worldwide so that each item has an unique ID regardless of where it is stored, such as on Econnect's server or on Colnodo's. This feature helps us in cross-server feeding.
Internally (within the database) the IDs are stored as 16-character strings (for disk-space savings and a little better performance of the database), but this is only important for developers.
Because of long URLs, I made short_id in v1.8 - so that the auto-incremented short IDs are used by default. The URL for an item is now, for example:
http://kalendar.ecn.cz/index.shtml?AA_SL_Session=44ca275c691 842965745f90ab9aee24e&x=27968
or, even better:
http://kalendar.ecn.cz/index.shtml?x=27968
From Mitra (mitra[at]earth.path.net):
I am using alerts/mailman integration, - its one of the most painful AA admin procedures, basically you have to create an alert that goes to a mailman group. Here are the steps (note that I've SIMPLIFIED it, removing sub-steps).
This presumes you have:
- A Reader Management slice created
- Mailman installed, and documented elsewhere how to add lists
- Cron working and running the AA cron function for Alerts
-
In the slice you want to send mail from:
- Create a Alerts View - (known elsewhere as a Selection)
-
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
- Go to mailman, create a mailing list - set yourself (a human) as the owner, set to moderate new subscribers
-
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)
-
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:
- Fix old links within fulltext.
- Categorize and fix grammer in all articles
- Get popular collections view working (uses related items) and ask key users to submit their favorite collections.
- Add more content from email archives and personal notes.
- Add email alert feature
- Allow for editing on site for logged in users.
Also need to get other language views and content going (e.g. Spanish).
I also plan to create a Requested Feautre slice in the near future that will
use the same alert login.
Some help with updating FAQ content would be most appreciated. :^)
- JD- - - --
We have slice data and structure exported to AA.XML file and we want to import it back to the AA. The problem is, that the AA.XML file is 24 MB.
The solution:
The problem could be in PHP setting. Here's what I had to change in php.ini file to get it going:
1. post_max_size: increased from 8M to 32M
2. upload_max_filesize: increased from 2M to 32M
Those first two were key -- from the php log the upload was clearly
exceeding both of these parameters. Obviously, if the upload was bigger
than 32M (ours was about 24M) this might need to go even bigger.
I also increased these others. I think the upload wouldn't have
completed in the default times, but I'm not sure which parts of the
operation count towards which of these:
1. max_execution_time: changed from 30 to 120 seconds
2. max_input_time: changed from 30 to 120 seconds
3. memory_limit: changed to 32M
Reader Management is a special kind of slice that is designed to contain data about subscribed "readers" (aka public web site users). A Reader Management slice can be used to send automated email alerts of new AA items, personalize page views, send bulk target emails, and generally act as a contact database. Anonymous forms can be set-up to allow users to change their subscriptions and contact data in the Reader slice.
The HTML for a typical APC-AA site can come from many places which can confuse
people used to doing all their HTML in a single place.
Location |
What to put there |
.shtml file |
static HTML that doesn't repeat, and is not changed often. Can be edited
with any standard web editor by someone who has write permissions on the
web server. The HTML has lines like <!--#include "/apc-aa/view.php3
--> (or apc-aa/slice.php3) to include a PHP file which will fetch information from the Slice's design. |
Design section of the Slice |
This is used to list a range of items in a slice, or display a single
item. Someone with Admin permission on the slice can go to apc-aa/admin
-> Admin -> Views or apc-aa/admin -> Admin -> Display/Index
or Display/Fulltext. HTML can be placed here associated with the top and
bottom of a listing, with each item, and with groupings of items. The HTML
includes alias such as _#HEADLINE |
Aliases such as _#HEADLINE |
Each alias defines how to show a particular field, it does this by choosing
a function (e.g. f_h) and parameters. For example _#HEADLINE is usually
just output, while a Link might be output surrounded by <a href="
and ">. They can be edited by anyone with administrator priviliges
on your slice by going to Admin->Fields->choose field ->Edit. A
field can have several different ways of being output, for example a date
could have aliases for both short (1/1/200) and long (1 January 2000) forms
of output. |
Functions such as f_h |
These define functions certain common ways fields are output. They are
defined in the PHP code, and so have to be edited by developers, except
that there is an extension function f_u that calls functions from apc-aa/include/usr_aliasfnc.php3,
these can be written by anyone who understands PHP3. |
Data |
Lastly of course, the HTML could be in specific fields in your data. |
Exceptions:
- 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
Mark Surman wrote a good comparison
ActionApps can send email.
Go to the Admin -> Email Notification control Panel.
There are four sections:
New Item in Holding Bin
Item Changed in Holding Bin
New Item in Approved Bin
Item Changed in Approved Bin
Each section has three fields
* Email addresses, one per line
* Subject of the Email message
* Body of the Email message
Each of these section configures how action apps will respond to
an event. For example, if a new item arrives in the Holding Bin,
apc-aa will send an email notification to everyone listed in the Email addresses field.
The Subject cannot use aliases (this should be fixed in a later version)
The Body can use any aliases that you have defined for the slice, just as you use aliases in the Design control panels.
NOTE: a bug was fixed in the sourcecode on Jan 18, 2002, so
if you get errors, you might upgrade your apc-aa version to
the most recent version.
The output generated by AA is controlled by aliases. The aliases are 10
letters long words defined on 'Admin' -> 'Fields' -> 'Edit' page. Aliases
are obviously expanded to the content of some database field or its
modification (like How to use aliases alias). For modification of behavior of the
alias we use alias functions, as described on
http://apc-aa.sourceforge.net/faq/#216.
http://apc-aa.sourceforge.net/faq/#291.
Since the AA version 2.1 there is possibility to use the aliases NESTED,
which means that you can use another alias in the alias definition. For
example this Parameters to f_c alias functions are possible:
!:<img src=":" _#PHOTO_WI _#PHOTO_HE alt="photo">::
which displays image (if it is defined). The aliases _#PHOTO_WI _#PHOTO_HE
must be defined, of course.
You can use there not only the aliases, but it is possible to use any of
database field directly there. Imagine, we store type of record in
switch.........1 field (for example text/audio/video). If we create three
images - icon_text.gif, icon_audio.gif, icon_video.gif, we can add an icon
before each link by the following Parameters to f_m alias function:
<img src="img/icon_{switch.........1}.gif" width="14"> :text...........1::href:class="green10"
The AA version 2.2-pre (04/25/2002) give you new possibilities in alias definition -
IN-LINE ALIAS DEFINITION. The parsing of format strings was rewritten, so
now you can define aliases not only on 'Admin' -> 'Fields' -> 'Edit' page,
but you can define it directly inside the format string (= 'Fulltext HTML
code' on 'Design' -> 'Fulltext' page, for example). The new features are
100% backward compatible.
The alias definitions are surrounded by curly braces. There are the
possibilities:
- direct display of some field
... there is displayed headline: {headline........} <br> Source: ...
- 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) |
- 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. |
- 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).
- 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'. ...
- 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 ...
- 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}
- 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}}
- 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)
- 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
- 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.
- 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}
- 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:
- approved
- holding bin
- trash bin
So, change the default value for the status_code..... field to 2 and the items will be posted directly into holding bin.
It is possible to display this field in inputform (possibly as selectbox), so the editors could be able to decide, where the item should go).
There are two (and should be more in the future) odd slices in slice listbox. Why?
Both - the 'Action Aplication Core' and 'News (EN) Template' are
only visible to superadmins and both should not have any items.
News (EN) Template
The 'News (EN) Template' slice is just a template for creating new slices.
This template is shown as an option in "Admin" -> "Add Slice"
dialog in templates listbox. If you feel a setting for the new created slices
is not optimal you have two possibilities:
- 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:
description |
Generic Item Manager Welcome |
email |
Welcome, you have been assigned an _#ROLE____ for the slice _#SLICNAME.
Your username is _#LOGIN___. See http://apc-aa.sf.net/faq for help on AA. |
subject |
Welcome, AA _#ROLE____ |
mail_from |
"_#ME_NAME_" <_#ME_MAIL_> |
The new constant group names are found by trying to add "_1", "_2",
"_3", ... at the end of the group name until a group with such name
does not exist.
The code used by the Wizard is shared with the Add Slice, Add User and Pemissions/Assign
scripts, so you can expect the same behavior and AA developers may easily maintain
it..
In this example, we are trying to only show alias for page numbers
(_#NM_PAGES) when it is greater than zero.
The field input has Validate: Number, so it generates a zero when
left blank. To not show the alias and label when zero,
use:
{switch({_#NM_PAGES})^0:: _#NM_PAGES pages }
This switch will show nothing when the number starts with 0, otherwise it
will show e.g. "15 pages". Since number validation removes preceeding zeros e.g.
0020, this should always work.
It depends on Fields - Edit -> Insert' setting. If you set it to
'Text', then the value is stored exactly, how it is send by form checkbox (which
means 'on' or nothing). However, default and suggested setting is
'Boolean', which means '0' or
'1' is inserted.
External SQL query should look like:
SELECT * FROM item, content
WHERE item.id = content.item_id // to join the tables
AND item.id = 'hey67s[o0-78z._d' // 16 characters long packed id
// see util.php3 - q_pack_id()
AND content.field_id = 'headline........';
This SQL query select all fields from item table (where are stored just the
most common item fields - id, short_id, slice_id, status_code, post_date,
publish_date, expiry_date, highlight, posted_by, edited_by, last_edit,
display_count, flags, disc_count, disc_app, externally_fed) plus the content
of 'headline........' field from content table (will be in content.text
field). You can change 'headline........' to any field id, of course, just
like 'category.......1' or 'source.........1'. Also you can use short_ids as
well to identify the item.
Database structure used for items
Data for an item is not stored in one table, as it is obvious and as you
probably expect. Data are divided to two tables - item and content. Item
table stores the common fields, which is requiered for each item. All other
columns are sored in related table content (relation 1:N). The content table
is quite easy - item_id, field_id, number, text, flag. Each row holds
contents (in 'text' or 'number' filed) of one field (identified by field_id -
like 'headline........') for one item (identified by 'item_id' - related to
id in 'item' table).
Such, say 'virtual table database structure' or 'object oriented database'
allows to store items of any number of fields. It also allows to store
multiple values for one field (you just add a row with the same item_id and
field_id).
More complicated SQL query, which contain more fields from content table could
look like:
SELECT item.*, c1.text, c2.text FROM item, content as c1, content as c2
WHERE item.id = c1.item_id // to join the tables
AND item.id = c2.item_id // to join the tables
AND item.short_id = '13432' // we can use short id
AND c1.field_id = 'headline........';
AND c2.field_id = 'full_text.......';
(this approach is used in main query function of AA - QueryIds() in
include/searchlib.php3)
To select all extended fields for the item use:
SELECT * FROM content WHERE item_id = 'hey67s[o0-78z._d';
The data for field are stored in 'text' field of content table or in 'number'
depending on 'text_stored' flag in 'field' table.
Item data manipulationg functions (data API)
It is important to know how the data are stored in database, but if you want
to write some feature to AA, it is strongly recomended not to use direct
database access, but rather use three main data API function to access data
(especially for storing data into AA database). The functions are independent
on database structure behind and it takes care about feeding, clearing the
cache and other stuff.
Main AA data API functions are:
function QueryIDs($fields, $slice_id, $conds, $sort="", $group_by="",
$type="ACTIVE", $slices="", $neverAllItems=0,
$restrict_ids=array() )
- stored in include/searchlib.php3
function GetItemContent($ids, $use_short_ids=false)
- stored in include/util.php3
function StoreItem( $id, $slice_id, $content4id, $fields, $insert,
$invalidatecache=true, $feed=true )
- stored in include/itemfunc.php3
By QueryIDs function you will get array of IDs of items based on your
conditions, possiblly sorted. Input conditions are stored in array which you
already know from design of searchform (conds[0][publish_date....]=...). This
function allows you to get IDs based on any number of conditions. Also it is
completely database independent, so you need not to know, which field is
stored in item table and which is stored in content table.
The content of an item you will get by GetItemContent function. As input
parameter use the IDs of the items you want to get (possibly obtained by
QueryIDs). The items are then returned in array structure, which is good to
know about, because all data manipulation functions in AA uses this structure
to access the item data. This structure is also used as parameter to
StoreItem function.
Item data structure
Abstract Data Structure for data manipulation in AA (returned by
GetItemContent function):
$content[<unpacked_item_id>][<field_id>)][<alternative>][value|flag]
where
- <unpacked_item_id>
- is 32 characters long hexadecimal id of item (structure holds data for
more than one item, generaly)
- <field_id>
- is field id as you know it from Admin -> Fields page of AA admin
interface ( like 'headline........', 'url............2', ...)
- <alternative>
- is number used for storing multiple values for the same field. Obviously
there is only '0' index, but for field, where we store multiple
categories (for example) it will utilize indexes '0', '1' ,... up to
number of selected categories for the item
- <value
- is probably what you care about - it is content of the field like 'An
article title' or 1092928827 or <fulltext of item>
- flag>
- special flags for the content - if the content is HTML formatted, ...
The list of possible flags follows (defined in include/constants.php3)
define( "FLAG_HTML", 1 ); # content is in HTML
define( "FLAG_FEED", 2 ); # item is fed
define( "FLAG_FREEZE", 4 ); # content can't be changed
define( "FLAG_OFFLINE", 8 ); # off-line filled
define( "FLAG_UPDATE", 16 ); # content should be updated
# if source is changed
# (after feeding)
So, to access content of 'headline.........' field for item number
5e72be7289a0be63820a8723837ce21a you can type:
$text = $content['5e72be7289a0be63820a8723837ce21a']['headline........'][0]['value'];
For inserting or changing data of an item you just fill the structure
described above and call the StoreItem function.
The script fillform.php3 allows to easily refill condition variables as well.
If you have some search form using the conds[] array,
you may call fillform.php3?fillConds= 1 to create JavaScript, which will automaticallyrefill the condition input fields. You may use it by SSI, e.g.
<!--#include
virtual="/aaa/fillform.php3?form=formname&fillConds=1"-->
Place it after the HTML code for the search form, otherwise it will only make a JavaScript error.
Replace "formname " with the name of the form containing input fields.
The script can refill multiple select boxes like
<select name="conds[0][value][]" multiple>
as well. Don't forget the [] after [value].
Don't use quotes around field IDs, otherwise some values will not refill (e.g. checkbox <INPUT TYPE="checkbox" NAME="conds[1][highlighted.....]">
must not be 'highlighted.....'
).
There are special dateConds[] parameters which I use to
refill AA-like dates (three selectboxes for day, month and year), but this is a
bit difficult. If you are interested, write me and I will explain.
How to search in multiple slices
The searchform may be extended to seach for items in several
slices at once. This is done by adding the slices[] parameter, e.g.
<input type=hidden name="slices[0]" value="517d65d9936c98a1537a5fecbddc7d42">
<!-- news -->
<input type=hidden name="slices[1]" value="849d65d9936c98a1537a5fecbddc7d52">
<!-- events -->
The comments <!-- news -->
are useful because you perhaps
don't remember, which slice has which id (value="
slice_id"
).
All other settings remain the same as in the usual searchform. The only difficulty
is that sometimes the field ids do exist in some slice and do not exist in another
one. Than you must rename the fields (menu Slice Admin --- Change field IDs).
To view the items found, you must set the same aliases (Searchform extensions etc.) in
all the slices searched through. Each item will be shown using the aliases of
the slice to which it belongs.
Tip: If you want to show checkboxes to choose in which slices to search,
use something like
<input type=checkbox name="slices[0]" value="517d65d9936c98a1537a5fecbddc7d42"
checked> News
<input type=checkbox name="slices[1]" value="849d65d9936c98a1537a5fecbddc7d52"
checked> Events
How to search in discussion items
The discussions are not stored in the same database tables as other item content.
You may use the conds[discussion][] parameters, e.g.
<input type=hidden name="conds[0][discussion][subject]"
value="1">
<input type=hidden name="conds[0][discussion][body]" value="1">
Specify the discussion fields in which to search: you may use this fields ---
date, subject, author, e_mail, body, state, flag, url_address,
url_description, remote_addr, free1 or free2. The other fields (conds[0][operator],
conds[0][value] etc.) remain the same as usual.
To view the discussion items found include aa/discussion.php3 by SSI. You must
pass a view ID of some discussion view to the script, e.g. when the view ID
is 22:
<!--#include virtual="/aa/discussion.php3?vid=22"-->
The top HTML code, index view code and bottom HTML code are used to create
a listing of the items found, nothing other.
How to use hierarchical constants in searchform
To show hierarchical constants like in the AA control panel Edit item, use
the aa/hiercons.php3 script. You must send the following to the script:
- 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]¶m=Keywords:3:60:5:0:1&lang_file=cz_news_lang.php3"-->
Warning: constants in the multiple select box must be selected, otherwise they are not send to the server. Do this by JavaScript.
One benefit: fillform.php3 knows how to refill multiple select boxes as well.
The keywords selected by the user will be joined by OR or AND, that means any
keyword or all keywords must be present in an item. You must specify the operator
by conds[1][valuejoin], e.g.
<input type=hidden name="conds[1][valuejoin]" value="OR">
Tip: If you want to show a select box to choose whether the keywords
should be joined by OR or AND, use something like
<select name="conds[1][valuejoin]">
<option value="OR">Find items with ANY keyword
<option value="AND">Find items with ALL keywords
</select>
How to use a multiple select box
If you want the user chooses keywords from a multiple select box, use the similar
settings as in hierarchical constants: set the name of the select box to [value][],
e.g.
<select name="conds[1][value][]" multiple>
and add the [valuejoin] field (see above).
It is possible to create searchform manually in HTML. There is no possibility
to create it automaticaly as it is known from AA v1.2., yet. Special possibilities
for searching in multiple slice at once, searching in discussions, choosing
keywords from hierarchical constants and using a multiple select box are described
at other places in this FAQ.
Form example:
<form action="index.shtml" method="get" name="sf" id="sf">
Search Author: <input type="text" name="conds[0][created_by......]"><br>
Search in Headline and Fulltext: <input type="text" name="conds[1][value]">
<input type="hidden" name="conds[1][operator]" value="LIKE">
<input type="hidden" name="conds[1][headline........]" value="1">
<input type="hidden" name="conds[1][full_text.......]" value="1">
<br>
<input type="hidden" name="sort[0][headline........]" value="a">
<input type="submit" value="Search" >
</form>
Let's notice:
-
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
The simplified syntax is <input type="text" name="conds[i][field_id]">
(see conds[0][created_by......]
in the example). It is easy and good, if you want to
conds --- extended syntax
The extended syntax sets an [operator], [value] and one or more [field_id]
for each condition. See conds[1]
in the example.
[value]
Contains the search phrase (like conds[1][value]="Prague"). Usually this is
the only visible text box (<input type="text" name="conds[1][value]">).
The search phrase may be a boolean expression, but you don"t need to think about
it if you are using the standard LIKE [operator].
The phrase may contain ANDs, ORs, parenthesis ({[]}) and NOT. When the user
gives apple OR cherry, she will get all items containing any or both
of the two in any of the fields specified by [field_id] (see further).
Spaces are considered as AND:
Prague Spring becomes Prague AND Spring
With the standard LIKE operator this works fine: it finds all items
containing both Prague and Spring at any place (not necessarily Prague space
Spring).
Hyphen is considered as AND NOT if not between two letters:
North-West remains as it is, but
North -West becomes North AND NOT West because of the space on
the left of the hyphen
To avoid this behavior, use quotes or single quotes:
"Prague Spring" or "North -West"
[operator]
If you don't specify it, the default operator is LIKE. You can change the default by using the defaultCondsOperator
parameter (e.g. defaultCondsOperator=RLIKE
). Other
posibilities are:
Operator |
Description |
= |
equals (or "e:=" with modifiers) |
<> |
not equals |
< |
less than |
> |
more than |
<= |
less or equals |
>= |
more or equals |
BETWEEN |
in interval: the [value] must contain two numerical values, comma separated |
LIKE |
substring search (SQL: LIKE "%phrase%") |
RLIKE |
substring which begins with phrase (SQL: LIKE "phrase%") |
LLIKE |
substring which ends with phrase (SQL: LIKE "%phrase") |
XLIKE |
string (SQL: LIKE "phrase") |
ISNULL |
not set (good for boolean values - like values from checkbox) |
NOTNULL |
is set (the field must be filled - no match for NULL or epmty string '') |
date modifiers
Date values are stored in the database as UNIX timestamps
(no. of seconds since 1.1.1970). You can use modifiers to convert it from human
format. The modificators are written before a comparison operator separated
by colon (like "d:>="). The possibilities are:
Operator modificator |
Example |
Description |
d |
d:>= |
Used for english style datum transformation. If used, the "value" can
be in format like "06/24/2001" or "10 September 2000" see strtotime
PHP function definition |
e |
e:>= |
Used for european style datum transformation. If used, the "value" can
be in format like "24.12.2001" |
m |
m:>= |
Used for comparison with current time. If used, the "value" is substracted
from current time (time()) and result value is used in comparison. The value
should be in seconds. This modifier is good for displaying items newer than
two days, for example. |
[field_id]
Specify the fields to be searched through by their IDs.
sort
Specify the sort order by the sort[] form fields. For example:
<input type="hidden" name="sort[0][headline........]" value="a">
<input type="hidden" name="sort[1][full_text.......]" value="d">
The value is "a" for ascending and "d" for descending order.
The items are sorted first by sort[0], second by sort[1] etc.
If no sort[] variable is defined, items are sorted by Publish date -
descending.
It is possible to sort items not only by the value, but there is possibility to sort by 'priority' for the fields which uses 'constants' (Slice Admin -> Fields -Edit -> Constants) - like category field:
<input type="hidden" name="sort[0][category........]" value="1">
<input type="hidden" name="sort[1][unspecified.....]" value="9">
The value is "1" for ascending sorting by priority and "9" for descending order.
See another example on the
APC
Demo Site, where publish date field is used.
There are CSS files in the root directory that you can modify or create a
new CSS file and point to it from include/config.php3 (line 139).
Using this method, you can, in the "add item" form, use an image from an existing URL or upload an image to use it.
1) in the ActionApps main menu, choose "Slice Admin" option
2) In the list of fields, there will be a field called "Image URL"
3) Edit the properties of the field...
a. Change input type to "File Upload"
b. Edit the parameter to "image/*"
c. Set Validate to "URL"
d. Set Insert to "File"
4) Now, you can use the alias _#IMAGESRC like :
<IMG SRC="_#IMAGESRC">
1) Go to /apc-aa/misc/forgotten_pwd.php3 (may vary
depending
where AA is installed)
2) Enter either the username or email address
3) Check the email you will receive in case the user has been found and it's you
4) Visit the url in the email - in fact it's the same but with the temporary key that will let you change the password
5) Change your password
Note: The key expires after 90 minutes
Expired items are normaly not visible on the public website.
However is it usefull to sometimes show expired items such as for
archives.
There are two easy steps to show expired items in a view:
- Make sure display of expired items is permitted
by setting ALLOW_DISPLAY_EXPIRED_ITEMS constant to true in
config.php3
- 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 "logout" with
password "logout"
http://logout:logout@marek.greennet.org.uk/protect/logout/logout.html
http://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
"Authenticate yourself"
AuthUserFile
/home/httpd/htdocs/marek.gn.apc.org/protect/logout/.htpw
Require user
logout
The
/home/httpd/htdocs/marek.gn.apc.org/protect/logout/.htpw contains only
user logout (the file was created using htpasswd), and only this user is
allowed
here.
When you update an item that includes a mutual related link it will update
the matching relation field ID in the related slice. Make sure both slices are
using the exact same ID and that the input
Insert is set to "Item IDs".
Htaccess is updated by AuthMySQL module on the Apache
server. The access is granted directly from AA (from auth_group and auth_user
tables)
You need to:
1) Install mod_auth_mysql (
http://modauthmysql.sourceforge.net/)
(This module is standard part of RedHat Linux distribution (rpm
mod_auth_mysql). Be carefull, because there are at least two different modules
with the same name but with different httpd.conf options and features. We need
the described one and not the one described by Ram:
http://actionapps.org/faq/detail.shtml?x=1673 !!!)
2) Then you need set auth_group...... field in Reader managment slice as
described here:
http://actionapps.org/apc-aa/doc/reader.html#d0e236
3) Set the apache to accept MySQL authentication - something like modifying
httpd.conf file:
<Directory /data/www/htdocs/actionapps.org>
AllowOverride AuthConfig FileInfo Options Limit
# Authentication
AuthMySQLHost localhost
AuthMySQLUser aa_db_user
AuthMySQLPassword aa_db_password
AuthMySQLDB aa_db
AuthMySQLUserTable auth_user
AuthMySQLGroupTable auth_group
AuthMySQLNameField username
AuthMySQLPasswordField passwd
AuthMySQLGroupField groups
AuthMySQLNoPasswd off
AuthMySQLCryptedPasswords On
</Directory>
4) Protect the directory by .htaccess file or by similar lines in httpd.conf
file:
AuthType Basic
AuthName "ActionApps Ariel Members Area"
<Limit GET>
require group ariel_members
</Limit>
or
AuthType Basic
AuthName "ActionApps Ariel Parnters Area"
<Limit GET>
require group ariel_partners
</Limit>
5) Done.
There is script /misc/oldDb2Db/move.php3. Script move.php3 is database trnansformation script, which copies whole slice from ActionApps v1.2- to the new database structure, which is used for ActionApps v1.5+.
- Go on Admin - Slice structure Import
- 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 !!!
- 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
- Remove the line just before this coment
- Run this script (you have to log as SuperAdmin, then)
- 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.
THIS ITEM IS COMPLETELY DEPRECATED. A COMPLETELY NEW ALERTS DESIGN IS DESCRIBED IN THE NEW DOCUMENTATION. ALSO SEE READER MANAGEMENT DOCUMENTION AND DEMOS FOR USEFUL ALERTS DEMOS AND TUTORIALS
Related FAQ items:
AA Alerts are designed to deliver new AA items to users by e-mail. Slice Administrators
choose the design and which kind of items from which slices to include, creating
Collections. Users subscribe for Collections and receive them optionally once
a day, week or month.
A user interface allows users to change their subscriptions. Users are identified
by e-mail and they must confirm their e-mail address by a confirmation code
received by e-mail to make sure the address is working.
The admin interface allows AA admins to define new Collections, list users
subscribed to Collections and list Collections subscribed by users.
Collections
Collections are created by Slice Administrators on the page Slice Admin /
Alerts / Collections. They are based on Filters, which are defined in the Digest
type of Views.
A Collection is an ordered list of Filters. Each Filter is associated with
one Digest and filters items to be sent by using the search
form conds[] and sort[]. Digests are views suiting Alerts needs (see below).
You may define Editorial for each Collection, which will be printed before
Digests' texts. In the Editorial you can use these aliases:
_#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
- Usually users subscribe on subscription forms in your pages
- They receive an email message telling them to click on the confirmation
URL or copy it to a browser
- The confirmation URL contains a 4-letter confirmation code which identifies
the user
- After clicking on the URL the login screen appears with the user email filled
in and the confirmation code is deleted from the database
- When the user clicks once more on the URL, the code is not more valid: a
subscription page appears
- If the user doesn't remember her password, she clicks on "Send confirmation",
receives another confirmation email and her password is deleted
- 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 ITEM IS COMPLETELY DEPRECATED. A COMPLETELY NEW ALERTS DESIGN IS DESCRIBED IN THE NEW DOCUMENTATION. ALSO SEE READER MANAGEMENT DOCUMENTION AND DEMOS FOR USEFUL ALERTS DEMOS AND TUTORIALS
This walkthrough does not describe all details, you must look into the FAQ
item AA Alerts for them.
To set up Alerts on your computer, first ask some Superadmin to set up default
Collections and cron:
- Jump to Alerts / Collections
- 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.
- Set the email headers for the special collections
- Set up cron on your server
- 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:
- Switch to the slice the items of which you want to send
- Create a view of type Alerts Digest, fill in a plausible design
- 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[]
- Jump to Alerts / Collections
- Create a new Collection, fill at least the Description
- After clicking on Insert, a list of Filters and Users will appear
- Add Filters to the Collection
Hurrah, we have a new collection!
Now how to offer it to users? On any of your web pages, create a subscription
form. See AA Alerts for details. If you want to see a
list of users subscribed to your collection, click on Edit in Alerts / Collections.
THIS ITEM IS COMPLETELY DEPRECATED. A COMPLETELY NEW ALERTS DESIGN IS DESCRIBED IN THE NEW DOCUMENTATION ALSO SEE READER MANAGEMENT DOCUMENTION AND DEMOS FOR USEFUL ALERTS DEMOS AND TUTORIALS.
To learn about AA Alerts, click here.
To handle problems with users who did not confirm their subscription, AA superadmins may use Alerts Admin (in Control Panel menu Slice Admin / Alerts / Admin).
You can delete not confirmed users after a number of days and / or send them an email demanding them to do confirmation after a smaller number of days.
To switch either of the actions off, set number of days to 0. The two last fields are for your information only, they inform you about the subscription time boundary for the action.
To run the actions, you must have cron set up with a row running
misc/alerts/admin_mails.php3
. This row is added automatically by the sql_update.php3 script.
Error returns in AA are not consistent, there is a general, low priority, task to clean up the code as we work on it.
In general use the $err array to return errors.
Some specific examples follow, please add others here.
Each of the functions: insert_fnc_xxx sets for example
$err[image.....1] => "Wrong type of file"
This example uses 1 view, 3 categories, and 2 levels of constants. The
catgories are not important but maybe you like to use them so I left them in
there.
The view below manages a two level side bar menu. It highlights the branch
you are in and the (sub)item you have selected. Example can be seen here http://pi.gn.apc.org
The constants are used as the menu entries. You have to use hierarchical
constants and define the constants like this:
Level 0: Name Value
Terrorism Terrorism
Policy Policy ...
Level 1: Name Value
Politics of Terrorism Terrorism::Politics of Terrorism Defining
Terrorism and Emergencies Terrorism::Terrorism and Emergencies
IGOs and Laundering Policy Policy::IGOs and Laundering Policy
...
Now create a new constants view Paste the text
below into Odd Rows. Set the Group by to "Value Select"
the hierarchical constant group created above View 342 is the listing view I use
to display items from my slice.
The slice has 3 categories. This menu only manages the selection of the first
category (category........) which is set to use the constant group created
above. Further it's first confition is set to LIKE (name of category........).
You will have to replace 342 in the text below with your listing view. You can
leave away most of the {country}-stuff. To work this just needs {theme} and
{_parent_}.
TODO: use better names for the aliases. 'theme' and 'country' might be
substrings in the constants. That would cause havoc! All left to do now is to
create your style sheet. Have fun!
----------SNIP SNIP----------
{switch({_#LEVEL##_})0:<br>
{switch({theme}).*theme.*:
<div class="constView_ContentThemes_ListEntry">
:{_#NAME###_}.*:
<div class="constView_ContentThemes_ListEntry_Hl">
:<div class="constView_ContentThemes_ListEntry{switch({_parent_}){_#NAME###_}.*:_Hl}">
}
<a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}{switch({_#VALUE##_}){theme}.*:&als[_parent_]={theme}}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_ListEntry_link">_#NAME###_</a>
</div>
:1:<!--{theme}--_#VALUE##_--_#NAME###_-->
{switch({_parent_}).*_parent_.*:
{switch({theme}).*theme.*::
{switch({_#VALUE##_}){theme}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={theme}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
}
:{switch({theme}).*theme.*::
{switch({_#VALUE##_}){_parent_}.*:<div class="constView_ContentThemes_SubListEntry{switch({theme}){_#NAME###_}.*:_Hl}"><a href="/index.shtml?cmd[342][]=c-1-{_#NAME###_}&als[theme]={_#NAME###_}&conds[1][category........]={_#NAME###_}&als[_parent_]={_parent_}{switch({country}).*country.*::&cmd[342][]=c-3-{country}&als[country]={country}&conds[3][category.......2]={country}}" class="constView_ContentThemes_SubListEntry_link">{_#NAME###_}</a></div>}
}
}
}
----------SNIP SNIP----------
If you get the error: "No slice found for you" after logging into AA after doing a CVS update, then you may have forgotten to fill in the AA_ID in the config.php3 file
If you were a loser (like I have been) and did back-up your AA_ID, it can be retrieved from the AA database...
Using phpMyAdmin or your excellent MySQL skills:
Look for entries in "perms" table that have aa in "object_type" column, "objectid" is your installation ID.
Some fields have a predefined set of possible values --- a constant group.
These are usually shown in a select box, multiple check / radio boxes etc. Edit them in Slice Admin -- Fields -- Constants -- Edit / New.
Categories
are constants with some special properties. The constant table structure is:
CREATE TABLE constant (
id char(16) NOT NULL,
group_id char(16) NOT NULL,
name char(150) NOT NULL,
value char(150) NOT NULL,
class char(16),
pri smallint(5) DEFAULT '100' NOT NULL,
PRIMARY KEY (id),
KEY group_id (group_id)
);
- 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
How the 'Display' and the 'Store in Database' parts are supposed to be used?
For example the "State" select box (if you want to see it on input
form) has the names and values of:
Name | Value |
Approved bin | 1 |
Holding bin | 2 |
Trash bin | 3 |
Another example, more real-life - colors select box. There can be
names of "Red", "blue", "very bright green", ... and values will be
"#FF0000", "#0000FF", "#EEFFEE". In input form you see Red...
and on page is then #FF0000
The third example is kind of hint. Suppose you want to have
different kinds of item - for example "public", "private", "other" and you
want to see this words on compact view. No problem, but you want to see each
in different color. So you can define:
name: Private
value: <font color="#FF0000">Private</font>
Order Categories on Input Form as You Wish
You can set the priority order in the constant editing page, and then if you want the output in this order as well, then in the View set the sorting to be "Ascending (or Descending) by Priority"
Propagate changes into current items
Usually if you change a constant value, the current items in the database remain
the same. By checking this box you force the changes to be made on the items
too. If you change "red" to "cyan", all items with color
"red" will be changed to "cyan".
Remember that the constants may be shared by several slices --- if you change
a value, the changes may be propagated to some places which you didn't count
with. Another danger is that if there were some items with "cyan"
before, you can never ever find which item are converted from "red"
and which are not.
Changing the constant name doesn't have any effect in the database but changes the look
in all Edit / New item pages using the constant group.
Displaying list of constants on a page
For displaying list of constants on the page you can use specila type of view - Constant view
Constant view is quite normal view, just like item listing view. You can use aliases, conditions or sorting (conds[], sort[], als[]) (from AA v2.6). Following table shows aliases, which you can use for the design. Many of the aliases have also its own "field_id", which is presented in the second table column. The "field ids" you can use, if provided aliases do not fill your needs or if you want to use conds[] or sort[].
_#NAME###_ | const_name | Constant name |
_#VALUE##_ | const_value | Constant value |
_#PRIORITY | const_pri | Constant priority |
_#GROUP##_ | const_group | Constant group id |
_#CLASS##_ | const_class | Category class (for categories only) |
_#COUNTER_ | | Constant number |
_#CONST_ID | const_id | Constant unique id (32-haxadecimal characters) |
_#SHORT_ID | const_short_id | Constant unique short id (autoincremented from '1' for each constant in the system) |
_#DESCRIPT | const_description | Constant description |
_#LEVEL##_ | const_level | Constant level (used for hierachical constants). If you want to display hierarchical constants in its hierarchy (so constant on second level have two spaces before the name), you can use following AA expression:
{switch({_#LEVEL##_})1: :2: :3: } |
The APC AA has a Two Layer category system:
1) One set of broad categories set at the network level
These are useful so that people can 'browse' and find the information they
are looking for without a specialized understanding of the content area.
2) Totally flexible page-specific categories
Individual page owners can setup any specialized categories that work for
them. They 'map' their specialized categories to the APC-wide parent
categories.
We also want to be able to map between different languages, so
categories can be displayed in the local language, but stored as a
universal constant.
This requires relating items in the first slice to the second, and using a related view.
- 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)
- 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
|
Template for Email |
Who gets the email |
How sent |
Bugs, Limitation and further development |
Notification |
Admin -> Slice -> Email Notification |
Directly from script updating |
Can't use aliases in Subject line
Can't self-manage recipients
|
Alerts |
Admin -> Slice -> Views -> Alerts View |
Readers from Reader slice, who can choose which to recieve |
By Cron |
Complex to setup (anon forms) |
Email Discussion |
Not applicable - its email to email |
Members managed by Reader Management slice |
Mailman handles all sending |
Requires understanding mailman to setup, reports of failure partly due to server setup
Cant subscribe/unsubscribe by email
No slice -> email or email -> slice
|
Discussion -> Email |
Admin -> Slice -> Views -> Discussion to Email |
One hard-coded email address |
Not sure, probably cron. |
Doesn't integrate with Alerts so no recipient management at all
Doesn't seem to work (Mitra).
Has to be added to each item in slice. |
Note:
There is no integration for receiving email, although there has been discussion
(where?) about posting articles by mail
In view you can specify "No item found" message, which is displayed if
view (due to its current conditions) do not find an item to display.You can
enter there:
- 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".
- AA > New Slice: Create a new slice from the “Reader Management
Minimal” template with the name “My Readers”
- Set “Allow
anonymous posting” to “Active”
- 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.
- 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)
- 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).
- Click on Reader management, Synchronization with Reader Management Slice,
change to “My
Readers“ (the page will refresh)
- 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...
- Within My Readers > Slice Admin > fields: check Required for 'Email' and
uncheck Required and Show for 'Password'.
- 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'.
- Copy the form HTML and paste into the file subscribe.shtml.
Add some preable text and upload to the URL you specified.
- Upload subscribe_ok.shtml to specified URL.
- 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.
- In the slice "Photogallery" make a view or views, which will show a single photograph.
- 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}"
- In the slice "Articles", for the field "full_text......." create an alias e.g. _#FULLTEXT with fuction "f_y" and with no defined parameters.
- During the editing of items you can just copy the aliases from the slice "photograph" to the places in the text, where you would like to have the photographs
See an example.
MLX - MultiLingual eXtension for APC-ActionApps
Submitted by mimo on Fri, 07/10/2009 - 18:01
MLX adds content translation and interface translation features to ActionApps. All of this is now part of ActionApps core and these pages are here mainly for documentation and historic reasons.
(or mimo's language extension)
(C) Michael Moritz mimo/at/restoel.net
MLX Screenshots
Changelog
- 05/11/2004 MLXGet Text Documentation
- for changelog see APC AA CVS on SourceForge
- 05/10/2004 -- changed the way ids get stored, optimised sql queries and since MLX is now in APC-AA CVS removed the installation stuff from this page, to upgrade without CVS have a look at MLX installation -- the hard way
- 04/10/2004 -- now moved into APC AA CVS on SourceForge
- 03/10/2004 -- apc-aa-mlx-0.2: support for simple slice.php3 calls; better admin integration (using MLX tabs)
- 29/09/2004 -- first buggy release: basic admin interface functions
Step-by-Step Example of setting up a slice for MLX
- Create a new slice based on News Template and call it MLX Control Slice.
- Delete all deleteable fields from this slice.
- Add two new fields. Call one EN, the other one FR and choose type MLX Control for them.
- Unshow all other fields apart from these two. Have a look at MLX Screenshots to see what this should look like.
- Create a new slice. This one will hold the actual content (Content Slice). It can be any kind of slice.
- In Slice Settings select the MLX Control Slice you created before. Again, MLX Screenshots are your friend.
- Check that the slice contains a lang_code....... field.
- Add a field for the MLX information. It must be of type MLX Control. It doesnt have to be visible, so in most cases you want to hide it from the user by unticking Show.
- Done! You are ready to use the multilingual content slice.
Using MLX
MLX adds a little menu to the Add Item / Edit Item pages. This contains something like:
Add German | Edit English (view) | Edit Dari | etc.
Clicking on Add DE takes you to the Add Item page. This is prefilled with the contents of the original item. Once you have translated this content press the Insert button. MLX takes care of storing the information that keeps the original version of the article and the German translation together.
MLX and slice.php3 -- Displaying content using MLX on a web site
From version 0.2 MLX does actually do something do the output as well. This is configurable depending on what situation you are in. Here are three scenarios:
- You have a multilingual site. Some articles are translated, others only exist in the original language. If a vistor to your site chooses a language into which only some articles are translated you want to display the untranslated ones nevertheless (an example of this is the ESF2004 website). In this case you would use slice.php3 like this: add mlx=FR to the URL if the user selected French as his/her language. E.g. index.shtml?mlx=FR&listlen=10. MLX takes care of showing translations or original items for you. It will display an alternarive article (in this example a non-French one) if it exists one. If more than one other translation exists MLX uses the order in which the languages are defined in the MLX Control Slice. So the step-by-step example above would first look for an English version. But you (or the user may chose to) can even override this behaviour: The same way you pass the user's language choice to slice.php3 you can aslo set the order in which alternatives are used. With two languages this doesnt make sense, but given you had a third translation, let's say in German, you could pass the order like this: index.shtml?mlx=FR-DE-FR This would make MLX first look for a French version of the item, then a German one, and then a French one and display the first one found.
- You only want to display articles in the language the user has chosen. Use this syntax for your calls to slice.php3: index.shtml?mlx=FR-ONLY (This is similiar to using a condition)
- You want to display all articles including other language versions. Syntax: index.shtml?mlx=ALL. (This ignores MLX information)
MLX and view.php3
MLX supports views as well. Use set[vid]=mlx-(lang code)-(lang code 1)-..-(mode)
The _#MLX_LANG Alias
When using language defaulting this is helpful. It allows to print the current desired or default language in a view. This is hopefully helpful for creating language menus, displaying messages like "currently there isnt a translation for this article, so the original version is displayed". Have a look at the demo in MLX Screenshots for how this works.
FAQ
- Q: How do I MLX-alise a slice?
A: Follow the steps in the Step-by-Step example but skip creating the Content Slice (step 5). Make sure you set the MLX Control Slice as the MLX: Language Control Slice in the slice you want to MLX-alise and that you have a field of type lang_code....... in it. To MLX-alise an item you need to edit it in the Item Manager. This means you click on the headline and the press the Update button. Click on the headline again and MLX is ready.
Bugs & Limitations & TODOS
- Maybe add to fulltext view also in slice.php3
- Testing, testing, testing
Credits
- Huge thanks to Marek Tichy for discussing this and helping implementing it as I did not know anything about Action Apps? code when I started
(was on http://mimo.gn.apc.org/mlx)
The script /misc/file2slice/importer.php3 contains a function importer, which can import a CSV (comma-separated-values) file into your slice.
The data file should contain field names (any names, not from AA) on the first line, separated by your chosen separator. The next lines contain the items, one item per line, fields separated by the same separator.
E.g.:
AUTHOR,TEXT,EMAIL,LANGUAGE,CATEGORY
Johny Bravo, he is a real good guy, johny@bravo.uk, fr, VIP+fools
France Newman, a noname boy, france.newman@noname.org, en, nonames+fools
Here, the separator is comma, but it may be any other string.
The function trimmes each field from whitespace. It has these parametres:
- 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)
You don't have to set all the parametres - the last one required is postedBy, the next ones have default values.
The "fire" parameter works as a safe mode. You can prepare your data with "fire" set to false and when you are sure that what you see on the screen is what you want to be added to the database (by the StoreItem function), you may set "fire" to true.
Actions
The array "actions" should look like this:
$actions = array(
"created_by......" => array("action" => "store", "from" => "AUTHOR"),
"category.......1" => array("action" => "storeparsemulti", "delimiter" => "+", "from" => "CATEGORY"),
"language.......1" => array("action" => "storetrans", "from" => "LANGUAGE", "flag" => 1, "trans"=>array("en"=>"english","fr"=>"french"))
);
It contains the AA field names followed by how to get their content. You may set flags (e.g. "flag" => 1
means HTML content) with any action.
The actions are as follows:
- 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
?>
There are a number of tools for importing, each has different advantages and disadvantages and each needs configuring to specific requirements.
apc-aa/misc/file2slice/importer.php3: Is highly configurable, and can perform functions on the data, however its complex and requires some PHP knowledge to get to do what its capable of. It is documented below. Note that apc-aa/misc/file2slice/import.php3 is an example of its use.
apc-aa/misc/file2slice/tab2slice.pl is much simpler, but it takes the packed field ids as parameters in the first line of the file being imported, it is documented in the top of the file. (this was apc-aa/misc/tabslice.pl)
apc-aa/misc/file2slice/tab2slice_php/ contains a PHP version that can be used with uploaded files (unlike importer.php which reads the file from the file system). It has to be configured to know the packed ids. It does not have the complex capabilities of import.php3 to manipulate fields during import. See apc-aa/misc/tab2slice_php/README for some basic documentation.
It should be possible to merge the uploadability of tab2slice_php with the automatic configuration of importer.php3 but this has not been done yet.
misc/file2slice/array2constants.php3 is also available for importing constants but requires documentation.
There is an command-line-interface for modifying slice structure (the fields).
See apc-aa/misc/txt2fields/README
The Item Listing View (View.php3) and Design-Index (slice.php3) provide overlapping features. Which to use will depend on which features you need. Here are some of the differences.
Available features | View | Index |
Search conditions from URL | Yes | Yes |
Search Form | No | <#215>Yes |
?x=1699 | No (workaround) | Yes |
Scroller | No | Yes |
Slice id | Implicit, can be overridden by parameter | Parameter in include or URL |
Copy with Template | Yes with new wizard, but may need to edit HTML because numbers change | Yes |
Sorting | From Admin only | From URL parameters only |
Views are useful when you want functionality a little bit different from the
standard Index, or Full-Text views. You can use them to customize sorting,
or pick certain items or only a subset
of the items.
Highlight is normal field, so You are able to display the icon or a text for highlighted items (on Item Manager or on website).
You can add the column for showing Highlighted item flag on admin interface:
1) Go to Admin - Design Item Manager
2) Add new column in Item Format (and Top HTML). For Item Format use the _#HIGHLGHT alias (not deffined, yet) just as in following example:
<tr class=tabtxt><td align=center><input type=checkbox name="chb[x_#ITEM_ID#]" value=""></td><td><a href="_#EDITITEM">_#HEADLINE</a></td><td align=right>_#PUB_DATE</td><td align=center>_#CATEGORY</td><td align=center>_#HIGHLGHT</td></tr>
3) Go to Admin - Fields - Highlight - Edit
4) Define the _#HIGHLGHT alias:
Alias 1: _#HIGHLGHT
Function: f_c - condition
Parameter: 1:<img src="/aaa/images/highlt.gif"><!--:-->: 
Help Text: Highlighted item shown as bulb icon
This will show bulb for Highlighted items. If you want to Display just Yes/No text use:
Parameter: 1:Yes<!--:-->:No
You have to be the slice administrator, then from the standard admin page select
Admin -> Views, then you select "Item Listing" and click New.
The first few items are the same as for creating Index views (see the manual).
You can then specify how to sort items, and specify a condition (that
can take a parameter in the URL).
<!--#include virtual="/aa/view.php3?vid=5"-->
Will embed view number 5 into your page. The view knows which slice it applies
to, so this can be embedded in an Index or Full Text View.
View.php3 will take parameters either in the "include" line, or in
the URL of the page to which it refers.
You can sort items by specifying in the definition of the view (Admin->Views
then select an existing View or click New) which fields to sort by, and wether
to sort ascending or descending. The primary sort is the main ordering, and
the secondary sorts within this. So for example you might specify Category as
the primary sort, and sub-category as the secondary. Note that if you sort
on a field then there is a bug (or feature) where items without that field defined
will not show up in the index view.
Because views do not currently use sessions. There is no way, how to add 'Previous
1 2 .. Next' scroller to the 'view'.
This is the biggest limitation of 'Views' and we have
to count with it.
To select just a sub-set of the items, specify a Condition, or set of conditions,
you can then parameterise that in the include statement or URL. So for example,
if you set Condition 1 to "Category" and "LIKE" then you
can specify a parameter of "cmd[5]=c-1-News" to set the first condition
on View 5 to "News" so that it would list any item with a category
containing the string "News". This condition could be set in either
the Include statement or the URL e.g.
<!--#include virtual="/aa/view.php3?vid=5&cmd[5]=c-1-News"-->
or in the URL.
?cmd[5]=c-1-News&.....
If there are special characters in the search term, i.e. dashes (as in E-mail)
or spaces then quote it, and escape the quotes, for example to select a category=Social
Ecology would require a URL of the form:
conds[0][category........]=%22Social%20Ecology%22
(%22 is a double quote (") and %20 is space). If you are constructing
this URL from somewhere else and do not know what could be in the field then
make sure to quote and urlencode the string.
If you want to put highlighted items on a page, you should create a view.
In the view, one of the conditions is that highlight is not ''
(note there is a bug so that once you've set the condition to '' if you try and edit this view, you will need to reset the condition to '' before you hit update or you will get a SQL syntax error
Create a Full-Text view by going to Admin->Views and selecting "Full
Text" and clicking "New". Then you can specify cmd[5]=i-5-1a2b3c4d
in the URL or include statement. You can also use cmd[5]=x-5-934 where 934 is short _id
The right alias is _#ITEM_ID#.
For example, to show an item in a full text view, the view.php3 script should
get the parameters like:
vid=110&cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf
( the 'i' command to view.php3 script takes as argument unpacked (long) item
id)
So if we pass the vid parameter directly in fulltext.shtml page:
fulltext.shtml:
<!--#include virtual="/aaa/view.php3?vid=110"-->
Which then needs us to pass the cmd parameter through url:
<a href="fulltext.shtml?cmd[110]=i-110-2548e4b7ae7b8874ee4a4bf">
fulltext </a>
So we can generate this by placing in the Odd rows field of an index view
<a href="fulltext.shtml?cmd[110]=i-110-_#ITEM_ID#"> fulltext
</a>
If you want to link to a view appearing in the same place on the same page (as for the main index going to a full text), then if your Index view has vid=109 then the URL should be:
"?cmd[109]=i-110-_#ITEM_ID#"
which will redraw the same screen, replacing view 109 with view110, for the item specified.
Static Views are a bit like macros, they are not related to a specific item
or slice, but can be used where the same content, or parameterised content is
needed on many pages.
It is a view that only has one format - the 'Odd Row' format. It does not lookup
the values for any items or fields, but just prints the 'Odd Row format'.
However they can take parameters from the URL
You can use aliases defined in the URL parameter 'als'. For a detailed description
of the als parameter, see "What parameters can I
use with slice.php3"
For example,
There are 13 navigation pages. For example, there is a page on 'Communication
Rights' which has a report on Internet Rights in general and links to the pages
'Communication Rights in South Africa'
'Communication Rights in Morocco'
'Communication Rights in Senegal'
etc...
I did not want to write 13 pages, so I used 2 static views -- one for country
pages, and one for topic pages.
The topic page is /topic.shtml. It has this include
<!--#include virtual="/apc-aa/view.php3?vid=2-->
topic.shtml will be called with parameters. To create the 'Communication Rights'
topic page, it will be called as
/topic.shtml?als[MY_TOPIC]=Communication+Rights&als[URLE_TOP]=Communication%2BRights
URLE_TOP is an alias similar to MY_TOPIC, but it double URL encodes the value.
It will be used to generate links. %2B represents the +. A + in url encoding
is a space.
In this topic.shtml I want to create links to these pages. To create these
links, view #2 has this 'odd row' format:
<a href="/resource.shtml?cmd[1]=c-1-South%2BAfrica-c-2-_#URLE_TOP">South
Africa - _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Morocco-c-2-_#URLE_TOP">Morocco
- _#MY_TOPIC </a>
<a href="/resource.shtml?cmd[1]=c-1-Senegal-c-2-_#URLE_TOP">Senegal
- _#MY_TOPIC </a>
and the MY_TOPIC and URLE_TOP are substituted from the als parameters in the
URL.
Views can be swapped in and out from the URL, using syntax like "cmd[5]=v-8"
to display view 8 at the place where View 5 was expected (for example by <!--#include="/aa/view.php3?vid=5"-->
For example, if you want a navigation menu that redraws itself depending on
what is clicked on, you should create each of the different views you want to
appear and then include one view in the shtml page. Then you can switch between
displayed views using the url parameter.
For Example:
----------- index.shtml ----------
[...]
<h3>content</h3>
<!--#include virtual="/apc-aa/view.php3?vid=9"-->
<p> page footer... </p>
[...]
--------- code for this menu in the Odd row field of view #9-----
[...]
<a href="index.shtml?cmd[9]=v-13">News</a><br>
<a href="index.shtml?cmd[9]=v-14">Calendar</a><br>
<a href="index.shtml?cmd[9]=v-15">About us</a><br>
[...]
When the index.shtml page is redrawn the initial view #9 will be replaced by
the appropriate view, for example view #13 will appear in the News slice and
view #14 in the Calendar slice.
Because the PHP is interpreted via an include on the server, you cannot easily
change the view at run-time, for example changing it based on a mouse-over event,
it requires a page to be redrawn.
** Input (setting the admin interface)
- go to Admin - Fields
- add new field to the slice, where you want to store related item
- go to Edit page for the new field (Admin - Fields - Edit)
- 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)
- 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.
- Select the 'Item IDs' option in Insert field to be the related items ids
correctly written to database.
- 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
- go to Admin - Design Views page
- 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)
- 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
- Click on 'Update'
- Create page which includes the view. Say the view number is 110:
related.shtml
APC - ActionApps Test Site
- go to Admin - Fields - Related field Edit page
- 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)
- go to 'Admin - Design Index' page
- Add next code to 'Odd rows' field:
<a href="related.shtml?cmd[110]=i-110-_#RELATED_">Related</a>
- 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)
- go to Admin - Fields - Related field Edit page
- 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
- go to 'Admin - Design Fulltext' page (for example)
- Add next code to 'Fulltext HTML code' field:
<br>Related: _#SHOWVIEW
- click Update - related items displayed
Output (2) describes how to create view alias. With such alias you can work
as with any other aliases.
Tip:
In step 6) of Output (2) we used field content as list of displayed items:
vid=110&cmd[110]=i-110-_#this
In some cases we may want to switch between the views depending on field content.
Then you can use parameter like:
vid=110&cmd[110]=v-_#this
or more complicated:
vid=110&cmd[110]=i-_#unspecified.....-_#this
Then the fields <this> in example a) or unspecified..... in example b)
should contain the ids of view to show (112, 113...).
How do I create a View which indexes all items that relate to that item.
An example might help..
I have two slices 'authors' and 'articles'.
In articles I have a field 'author' which relates to the slice 'authors' (in
it is stored ID or IDs of author/authors of the article).
So in articles on the web is displayed information from the 'authors' slice.
But now I would like to show references to articles on the pages of their authors.
And I don't want to make it by a new relation field in the slice 'articles',
because I would have to after addition of a new article go to the slice 'authors'
and edit the author's profile - make a relation to the new article.
Do you have some idea, how to display the information from the slice 'articles'
in the slice 'authors' if the relation field is in the slice 'articles'?
Yes, it should be possible to display author's articles, because there is the
"relation" field for Author (the created_by.....1 in your case) in
the Article slice. There are the ids of 'Author' records (items) stored in this
field. So, it is possible to create view (say number 123) in 'Article' slice
where the first condition will be
Author =
Then, you just create the page which includes the view:
---author.shtml ---
<!--#include virtual="/aaa/view.php3?vid=123"-->
The link to this page then should look like:
author.shtml?cmd[123]=c-1-5254422456eab4763bea34
where 5254422456eab4763bea34is item (=author) id in Author slice. Such link
can be generated automaticaly Index - Odd row (for example):
<a href="author.shtml?cmd[123]=c-1-4f35cd6ab328690caffbe7d646eded78">_#NAME####</a>
Javascript item exchange View is a type of View. It works exactly the same
as a standard view, but the primary usage for this type is to show items on
any page around the Internet. For a simpler way of doing this, see "How
do I use jsview.php3 to view pages on a site where AA is not installed."
The destination page should contain a HTML tag like:
<SCRIPT LANGUAGE= "JavaScript"SRC="http://aa.ecn.cz/apc-aa/view.php3?vid=1"></SCRIPT>
This tag includes the output of view to any page on Internet (there is no restriction
to one server).
Because such tag requires javascript as output of view.php3, the format strings
for the view (Admin -> View) should look like:
Top HTML |
document.write("<TABLE WIDTH='100%' BORDER='0' CELLPADDING='2'
BGCOLOR='#FFFFFF'>") |
Odd Rows: |
document.write("<TR><TD VALIGN='TOP'>12/05/2001</TD><TD><a
href='?x=1735'>How do I use a Javascript view to see pages on a site where AA is not installed</a></TD></TR>") |
Bottom HTML:
|
document.write("</TABLE>") |
Note that there is (or was) a bug where if the item would
generate no items then you'll get an error rather than empty Javascript.
The only required parameter to view.php3 script is number of view
to show. This parameter is given by vid url variable. All
remaining parameters are optional.
Each optional view parameter begins with cmd[x],
where x is view number in which the parameter should be
used. This is needed because of possibility to include more than view
to one shtml page. That's why we need to specify, for which view the
command should work.
It is impossible to specify more than one cmd for one view. If you
want to use cmd[]=d for the view, you can't use it with
combination with cmd[]=c, for example.
Above is still true, even after CVS snapshot 20031109,
since when you can also use this syntax: vid=x&cmd[x][]=c-1-<something>&cmd[x][]=c-2-<something>.
Note the extra [].
However, you can use more settings (set[x]) per view. Just
seperate settings with a comma, like: set[23]=from-10,to-20.
After the cmd[x]= is always character, which specify
which command is used - how modify the view. The c command
modifies conditions, for example. The values after command character
are user parameters and its meaning is different for each command. The
parameters are separated by '-' character. If you need to use a
hyphen '-' in a parameter, use 2 hyphens '--' instead.
Description of parameters is in following table of examples.
Parameter example |
Description |
vid=4 |
id of displayed view |
cmd[23]=v-25 |
show view id 25 in place of view id 23 |
cmd[23]=i-24-7464647 |
view number 23 has to display item 7464647
in format defined in view 24 |
cmd[23]=x-24-1589 |
The same as i, but there you can use both - short_id
or long item id (as the last parameter) |
cmd[23]=x-24-1589-1545-1612 |
Display all three specified items. You can use as many ids
as you want (the same works also for 'i' and 'o' cmd). This behavior
is used for related fields, where related fields are displayed
by{view.php3?vid=33&cmd[33]=x-33-{@relation.......1:-}}. |
cmd[23]=x-24-url |
keyword url means, that item id is taken from url
parameter 'x=...' |
cmd[23]=o-24-1589 |
The same as x, but the number of item display
(countHit) is not increased (as opposite to 'x' or 'i') |
cmd[23]=c-1-ICT |
display view no 23 in place of view no 23
(that's normal), but change value for condition 1 to "ICT" |
cmd[23]=c-1-ICT-2-%22Jane%20Smith%22
|
the same as above, but there are redefined two conditions.
All three conditions could be redefined, notice how "Jane Smith"
requires urlencoded double quotes %22 or the search won't work, and the
space turned urlencoded to %20 otherwise it would be interepreted as
Jane OR Smith
Since CVS snapshot 20031109 you can also use this syntax:
cmd[23][]=c-1-ICT&cmd[23][]=c-2-%22Jane%20Smith%22
You do need to use this e.g. when you want to specify the first
condition in your .shtml file, while second one comes from the URL
|
cmd[23]=d-headline........-LIKE-Profit-source.........1-=-Ecn-publish_date....-m:>-86400 |
displays view no 23 and redefines the conditions. The
conditions are in format field-operator-value.
For list of possible operators see search
caption. The operators could be with its modifiers,
too. The unlimited number of conditions should be there specified. The
speciefied conditions allways replaces all conditions specified in view
definition (through admin interface). There are three diferences from cmd[]-c
command - 1)operators and fields are specified, 2) default view
conditions are ingnored, 3) there can be unlimitted number of
conditions. The example would show items in which the headline
contains 'Profit' and source field is 'Ecn' and the
item is newer that one day. |
cmd[23]=d-headline.......1,category........-RLIKE-Enviro |
You can use more than one field in one condition. Example
displays items where headline.......1 OR category........
begins with Enviro |
set[23]=listlen-20 |
setings to modify view behavior (can be combined with cmd)
- sets maximal number of viewed items in view 23 to 20
- there can be more settings - comma separated |
set[23]=sort-headline.......1 |
set item order (use 'sort-headline.......1-' for
descending sort order |
set[23]=from-10 |
- displays items from 10-th (in view 23) - it
can be combined with listlen, to, ... parameters
(set[23]=listlen-20,from-5) |
set[23]=to-15 |
- displays items to 15-th (in view 23) -
usefull if combined with from parameter (set[23]=from-2,to-9) |
set[23]=page-2-3 |
- displays second page from 3 (in view 23)
- it didvides all matching items into 3 pages and displays the second
one. If you do not specify the second parameter (3 in our
example), the page will be listlen items long. |
set[23]=random-1
set[23]=random-number.........1 |
selects item(s) to show randomly. If you use the 'random-1'
parameter, any item in Active bin is displayed. If You use field_id
instead of '1', then the content of field specified by field_id is used
as probability to show the item. Let's have two items. The parameter
looks like 'random-number.........1'. The first item has the
number.........1 filled with number 10, the second with 50. Then the
second item will be displayed 5x more offten than the first one. The
'weight numbers' and 'number of displayed items' are unlimited. This
feature is very good for banners. |
set[23]=banner-2-38
set[23]=banner-2-38-number.........1
set[23]=banner-2-38-norandom |
by this parameter you are able to display any view (38
in or case) inserted just after the second (2) item in view
(number 23). The item shown in inserted view (38) is
selected randomly, possibly with weight specified in weight field (number.........1)
- just like in random parameter described above. If you do not
want use random item (banner), use 'norandom' keyword in place of
'weight field' (good for displaying nested newsbox). See also banner
parameter for slice.php3. The example of included banner is on http://ecn.cz. |
set[23]=noitem-Not%20found |
- redefines the 'Not item found' message in view. |
set[23]=slice_id-79a69a0ad73c81ac332b0e8c4c3cea93 |
- redefines the slice from which the items will be displayed. |
set[23]=slices-79a69a0ad73c81ac332b0e8c4c3cea93-45639a0ad73c81ac332b0e8c4c3cea44 |
- display items from specified two or more slices. |
als[alias] |
user alias definition - you can define your own aliases in
url (for both - slice.php3 and view.php3). Aliases names MUST!!! be 8
characters long. Don't forgot, that the alias value have to be
urlencoded.
Example: als[MY_ALIAS]=Summary%20Page (or maybe better:
als%5BMY_ALIAS%5D=Summary%20Page)
defines alias _#MY_ALIAS. If used in formatstring ('Admin - Design
Index' for example), it prints 'Summary Page' |
nocache=1 |
URL parameter for pagerefresh - the view is not taken from
cache (- no matter if the view is allready cached or not). Cache is
updated. |
The parameter wizard helps you to design parametres when setting input type of function aliases.
It describes the input type / function and all parametres. Under each input box is a description, left of the box is the type of the parameter value. It allows you to set each parameter individually, not concerning about the ":" syntax. You run it by clicking on a link in the admin pages. You can reread the old parametres, write the new ones or watch example parametres. Some of the input types / functions
have more examples showing different groups of parametres.
This wizards now replaces the previous 'What is the Prameters in Alias Function definition' section in the FAQ.
The script is a universal mechanism based on a help array (see constants_param_wizard.php3 and xx_param_wizard_lang.php3). It only takes a few parametres (names of the fields on the web page) and is prepared to be perhaps used for another tasks as well.
The AA now enable to create a Calendar. Events lasting for several days are supported, repeating events are not supported.
Usually three parts of a calendar view are needed. First, a table showing the days and perhaps some caption of events which happen. This is prepared by the calendar view type. Second, some select boxes to choose the year and the month. Prepare these in a .php3 page. Third, a list of events to be shown after clicking on a date. This may be done by a list view with the conditions set as explained further.
To put the view and the caption together, use a .shtml page --- an example of a very simple one is in doc/script/calendar.php3.
Calendar view
Create it by Admin - Views - Calendar - New. Two calendar types are available: Month List shows a month with days in one list under each other, Month Table shows a table with one row for each week. Some new aliases are defined:
_#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)
New parameters to the view command are introduced: month and year. E.g.
set[301]=month-3&year-2002
The view setting are as follows:
- 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
These may be created by a .php3 script. An example of one is in doc/script/calendar.php3. The script is commented
List of events
An ordinary view of the type "Item listing" will do. You must set two conditions. The first condition must be "Start date <"
where Start date
is the name of the field containing event start date, the second must be "End date >="
where End date
is the name of the field containing event end date.
The conditions are controlled by the command cmd[319]=c-1-_#CV_TST_2-2-_#CV_TST_1
described above.
If you want to add functionality to the Add / Edit item page, you can use JavaScript
code. This may be useful in many cases. JavaScript is executed on the client
computer and works in most web browsers, e.g. Internet Explorer and Netscape
on PC / Mac. There are many enhancements which work in IE only or in Netscape
only but enough features are available for both. I assume you know about JavaScript
or will look for some more info on web.
Some examples of what may be done:
Events lasting one or more days. You need two fields -- event start
and event end. But most events are one-day events and the users hate to fill
the same date twice. You can add a link "Copy date from Start date"
which will copy the value. Or you can add an "aa_onSubmit" trigger,
which will copy the value before submitting the form when End date is not changed.
Combining two fields. You want to join values from several fields into
another field. You can do it just after leaving any of the fields by the "aa_onChange"
trigger or just before form submit by the "aa_onSubmit" trigger.
Predefined functions
Some useful functions are ready to work with fields. These are defined in indclude/fillform.js.
Have a look at the file to see other more general and more powerful functions.
The file is included with the Add / Edit item page if anything is defined on
the Field Javascript page. The two basic functions are:
setField (fieldid, newValue) -- sets a value to various control types,
to a text box, text area, select box, check box etc. Works even with AA dates
(shown by three select boxes for day, month and year) -- use a UNIX timestamp
(number of seconds since 1.1.1970) to set a date.
getField (fieldid) -- gets the value from various control types. Works
with AA dates, returns the UNIX timestamp.
Field Triggers
If anything is written in this page, the file include/fillform.js
is included with the Add / Edit item page. You can write any JavaScript code
in the page. AA will look for triggers and add them to all controls if it founds
them. Each trigger must be defined with
function aa_onTrigger (fieldid) { trigger body
}
where Trigger is a name of any allowed trigger -- these
are listed at the bottom of the Field Javascript page. You can add whitespace
(spaces, tabs, line ends) but you must use the parameter fieldid
.
The ID of the field to which a control belongs or the name of the form ("inputform")
is sent in it.
Solution to the examples
Combining two fields. You want to copy headline and expiry date to abstract
after editing any of them:
function aa_onChange (fieldid) {
switch (fieldid) {
case 'headline........':
case 'expiry_date.....':
var
myDate = new Date (getField('expiry_date.....')*1000);
textdate
= myDate.getDate()+'.'+(myDate.getMonth()+1)+'.'+myDate.getYear();
setField
('abstract.......2',getField('headline........')+' '+textdate);
break;
}
}
Events lasting one or more days. Suppose you are using the Expiry date
and Publish date as event end / start date. You can add this code to the Before
HTML code in Admin -- configure Fields:
<tr><td></td><td class=tabtxt>
<a href="javascript:setField('expiry_date.....',getField ('publish_date....'));">Copy
from post date</a>
</td></tr>
Remember to add something to the Triggers page (e.g. "//" which is
a commentary in JavaScript), otherwise fillform.js with the functions getField
and setField won't be loaded.
If you want to use the trigger, add this code to the Field Triggers:
function aa_onSubmit (fieldid) {
var myDate = new Date (2001,0,1); // the
default date is 1.1.2001
if (getField('expiry_date.....') == myDate.getTime()
/ 1000)
setField('expiry_date.....',getField
('publish_date....'));
}
This will change the end date before submitting but only if it is set to 1.1.2001,
which is default.
Content Pooling lets you exchange articles with any number of partner
sites. You can create a pool with any number of partners. With Pooling, you
always retain complete control: you can withold any item from your pool; and you
can reject any item made available to you.
Through Value field on
the Mapping page you can specify not only a new value, but also
any AA expression, which is
unaliased - example:
<a href="{source_href.....}">{source..........}</a>
In the Value field you can specify, which items should be
fed and which not. It is done by modifying the value of the ‘Status Code’ of the
receiving slice, according to field in the feeding slice.
Status codes are:
1=active, 2=Holding, 3=Trash, 4=Do not fed)
An example set-up:
1) Set Feeding, as usual ('Slice
Admin' -> 'Inner Node Feeds') (see feeding FAQ)
2) Go to 'Slice Admin' ->
'Mapping' and select the your source slice
3) fill something like:
{switch({category.......1})Enviro:1:4} for 'Status Code' and set FROM to '--
Value --'
After this all items from the source
slice with category 'Enviro' will be fed into Active ('Status Code' value=1).
Other will not be fed ('Status Code' value=4).
The offline filling currently works only in IE with Java support (there are some problems with Netscape and file manipulation permissions).
All files used for off-line filling are stored in /mics/offline2slice directory. All of them should be copied to local computer, where you want to use offline filling. There are a few steps to do for sucessfull installation.
- Create directory on your local computer (default is c:java).
- Copy files from /mics/offline2slice directory of apc-aa installation to created directory.
- Add row "set classpath=c:java" to your autoexec.bat file, in order java finds the class definitions.
- Restart computer in order the changes in autoexec.bat tekes efect.
- Open the delete_file.html file and change the location of main filling form
row 11: document.location='c:\java\fillform.html';
- Change the location of the file, where form data are stored
row 19: <PARAM NAME="filename" VALUE="C:\offlinedata.txt">
- 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.
- 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">
- 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">
- 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">
- Change the path to delete_file.html to point to your install directory, where the file is stored
row 361: <INPUT NAME="del_url" TYPE="hidden" VALUE="C:/java/delete_file.html">
The offline filling is now installed on your computer and you can try it (open your local fillform.html file in your browser). There you can fill as many items as you want and after all send it to the server.
Before sending the filled forms to server make you sure, that the slice you want import to, permit this operation (see 'Admin' - 'Slice' - 'Allow off-line item filling').
After the sucesfull sneding the items to server, your browser should be redirected to the page, where you can delete the file (offlinedata.txt). In this file the filled data are locally stored. The deletion is not necessary - the offline filling script offline.php3 will recignize, if the data for each item is already stored in database or not (the CRC for each item is computed). However, the better practice is to delete the file. This saves the capacity of line, because the data will not be transfered to server for second time.
Other documentation
You have prepared a public anonymous posting form and want to use it to edit items as well. How to do it?
There is a script fillform.php3 with associated JavaScript utilities in include/fillformutils.php3. This script takes the long item id from var my_item_id and calls JavaScript functions to look for the fields and fills them appropriately.
You may use it this way:
file anonymous.shtml
<!--#include virtual="/anonym.html"-->
<!--#include virtual="/aaa/fillform.php3"-->
<!--#include virtual="/bottom.html"-->
Than you can call anonymous.shtml?my_item_id=... to show the edit form filled with old values.
There are two additional parameters which most users will not need: use "form = formname" when you changed the name of the form containing the fields (usually it is "f"). Use "notrun = 1" if you want to fill the controls e.g. only after clicking somewhere.
Only items posted by public website and not updated in the AA admin can be
edited this way - a flag ITEM_FLAG_ANONYMOUS_EDITABLE cares about it. It is
reset every time you send an item with itemedit.php3.
The same script may be used to refill conditions on a search page - see
this.
Abstract
Explains the basic idea, creation and settings of Anonymous forms. The name
“anonymous” is in some cases not accurate, as the form
is used for reader personal info and the readers must be authorized to edit
their own info.
See also: doc/reader.html, doc/alerts.html, doc/script/show_result.php3
1. General usage of
Anonymous Forms
Anonymous forms are similar in function and design to the Add / Edit item
page. The main difference is they are placed outside of the AA Control Panel and
thus do not provide the AA authorization and have a design of their own.
The most common usage is to allow web readers to suggest new content. After
filling the Anonymous form it is sent to the Holding Bin and a Thank you page appears. But you can also allow
readers to edit items with the Anonymous form.
Two scripts handle the anonymous forms. The first, filler.php3, stores the info coming from the form into the
database. It also validates the data and prooves permissions to edit or update
the item. The second, fillform.php3, refills the data
into the form shown to the reader. It retrieves the data from database or in
some special cases directly from filler.
3. Creating Anonymous
Forms with the Wizard
In the previous AA versions until version 2.4, the process of creating
Anonymous forms was very simple: Copy the code of the “Add
item” page with only a few necessary changes. But as the form now allows
to edit items and to use several options for it, a new wizard was created. This
wizard creates the HTML code for a complete form with the SSI include of fillform.php3 necessary to edit items. The resulting form
differs depending on whether Anonymous editing is allowed or not.
You may change these settings in the wizard or later in hidden fields:
Table 1. Wizard settings
err_url |
The URL to which the script filler.php3 jumps
when some error occurs. It may be the same page on which the form is
shown. |
ok_url |
Like err_url, for successful changes. |
show_result |
The URL of a PHP script which receives the results from filler.php3. This allows for a completely free design
of how the errors are presented to the user. See below. |
If you are interested to know more about what the form contains, here are
some remarks:
- The fields shown in AA but not shown in the anonymous form are mentioned
in the notshown[v7377697463682e2e2e2e2e2e2e2e2e2e]
hidden variables. This allows to set these fields to default values on posting
and to store old values on updating.
- The setting use_post2shtml allows to use the POST
method for the form even though it is on a shtml page. See more info in the
script post2shtml.php3.
4. Editing with anonymous forms
If you want to edit items with anonymous forms, first you must allow to
choose which item to edit. You can create a view and add a link to the
headlines, which links to the anonymous form and contains the parameter my_item_id=11a7cc0908d77c22bf2c7ca43cdd8480. Another approach is used in Reader
management slices, see below.
You must choose the correct setting in Slice Admin - Settings - Allow
anonymous editing of items, which is used by the filler.php3 script on an item update request. The options
are:
Table 2. Anonymous editing options
Not allowed |
Never allow to update items |
All items |
Always allow |
Only items posted anonymously |
For items posted anonymously, filler always
sets the ITEM_FLAG_ANONYMOUS_EDITABLE flag. By
choosing this option you allow only items with this flag set to be
edited. |
Only items posted anonymously and not edited in AA |
Similar to the previous one, but when you edit the item in the control
panel, the flag is cleared and thus the item is no more allowed to be
edited anonymously. |
Authorized by a password field |
filler looks for a field of type Password
(with Id beginning with password....) and requests
the password sent by the user to match. The password may be set on item
creation. If the field is not flagged required, an empty password may be
used. The new Field Input Type, Field Insert Function and Field Validate
Functions “Password and Change Password” provide
the usual edit boxes for changing, deleting and entering password, which
is stored encrypted. The disadvantage is the password must be sent on
every update. |
Readers, authorized by HTTP auth |
This is a special option, useful only for Reader management slices.
The username given to the browser on HTTP authentification is looked for
in the database. Each reader may edit only his or her personal
info. |
-
It is possible to send images and other files by the form (unlike the
anonymous posting in version prior 1.5)
-
It is possible to set values to a non-displayed field by just adding a
hidden field for such a field:
<input type=hidden name="v696d675f6865696768742e2e2e2e2e2e" value="Anonymous author">
Note: This solution is easy and good
working in many cases, but it is by no means secure. Any experienced user can
change the values of the hidden fields so do not rely on such data. A better
solution is to completely omit such fields from the input form and set the
default values for the fields in "Admin" -> "Main setting - Fields" ->
"Edit" -> "Default". The values are than set directly from the database.
This solution is a little bit more secure.
-
The inputs are validated as if they were typed in the standard itemedit.php3 form. When there are any invalid data, the
whole item is not updated. The javascript validation used in itemedit.php3 is also included in the form created by the
wizard
-
You can disable the standard AA validation by adding a hidden field
notvalidate in the form:
<input type=hidden name="notvalidate" value="1">
-
Be cautious when using two anonymous forms on one page. You must rename the
form and the Javascript variables so that
they do not conflict with each
other.
If your form includes HTMLarea, you will need to include <body onload="HTMLArea.init()"> in your form page.
6. Reader management
specifics
Each reader has her or his own item in the Reader management slice. Thus the
HTTP authentication described above may be used directly to determine which item
(reader personal details) to show in the form.
In this case two forms are needed, one being the publicly accessible
subscribe form and the second being the HTTP protected “Change
personal details” form. Because the fields on both the forms may be the
same, you can use one form and include it into two different .shtml pages.
For webs not using Auth we need a way to ensure nobody not only edits but
even views the data. This is achieved by assigning a special “Access Code” (see the Reader management documentation) to each reader, which
must be added to the URL in order that the data are prefilled. The password
authorization described above is than used on item update.
Sending the data to AA results in adding the data into database or in an
error. Some of the errors may be excluded in advance by Javascript validation
(function proove_fields). But some of them, like a
username being already used, can not.
By default, the fillform.php3 script shows standard
error messages. They always appear at the place where fillform.php3 is SSI-included in your shtml page.
You may create your own PHP script (see an example in doc/script/show_result.php3) and send its URL as a value of
a show_result variable. Add it as a parameter to the fillform.php3 SSI include created by the Wizard, e.g.
<!--#include virtual="/aaa/fillform.php3?show_result=http://ecn.cz/show_result.php3&form=..."-->
An array $result with the results will be sent to the
PHP script and you may print appropriate messages, see the example.
The $result array content is created at various
places in filler.php3 array. Look there for accurate
info. At this moment the messages are:
Table 3. Results from filler.php3
fatal |
Fatal error. Several messages related to the slice, not to the
particular item. These errors help on creating the web page. |
validate |
Array with not validated fields, field_id =>
message, e.g. headline........ => This username
is already used created on field validation. You may create your own
messages depending on the field_id. |
permissions |
Missing permissions. Depending on the setting for Anonymous editing
(see
above), this item did not fullfill the requirements. |
store |
Some error in StoreItem. Usually this points to an inner AA
error. |
success |
No error. The operation was successfully done. The value is “insert” or “update” (i.e. $result["success"] == "insert" or $result["success"] == "update" in the show results
script). |
email_confirmed |
Added by fillform.php3 on Reader management
slices: When the reader successfully confirms his or her email by using
the URL sent in an email, fillform adds a message
“email_confirmed => OK”. This message is added
only when the email has not yet been confirmed. |
unsubscribed |
Added by fillform.php3 on Reader management
slices: When the reader unsubscribes from Alerts (which is achieved by
setting How often to an empty value). |
Discussion: A similar result may be achieved
by adding several fields to the form, e.g. fields
err_page[validate][username......]="err_username.shtml"
err_page[validate][*]="err_validate.shtml"
err_page[*]="err_unrecognized.shtml"
and by creating the .shtml pages with a static message concerning the
particular error. The main advantage of this approach is the web administrator
may not know PHP. The disadvantage is the necessity of creating many pages but
using SSI includes the pages could look only like:
<!--#include file="err_top.shtml"-->
The username you entered has already been used. Please try another username.
<!--#include file="err_bottom.shtml"-->
If you want to be able to go into the admin interface to edit an item, you can now put the alias
_#EDITITEM, into a view, the user will be asked to login, there are other ways to edit items anonymously.
After editing the item, the user will be returned to the page they were viewing.
The user will only be prompted to login the first time they try and edit an item, after that the AA_CP_Session parameter is added to the URL. In some cases this might not get through to the _#EDITITEM, (hints on how to make this work could go here). In which case a return URL can be
specifically written into the URL using {alias:headline........:f_e:edit:full url}
If you want to display some view on page, which is stored on site where is
not installed AAs, you have three possibilities.
- use remote, remotec or remotec.php
- create javascript view - this is good if you
want to do something complex with the Javascript.
- use the jsview.php3 to display existing view.
This answer covers point 3) - jsview.php3
The usage is easy. Just replace SSI include in original shtml age with the
javascript one. The jsview.php3 takes exactly the same parameters as view.php3.
For example, if the old SSI code in page.shtml was:
<!--#include virtual="/apps/aa/view.php3?&vid=2&cmd[2]=c-1-APC"
-->
the new javascript code in page.shtml would be:
<script type="text/javascript" src="http://www.apc.org/apps/aa/jsview.php3?vid=2&cmd[2]=c-1-APC"></script>
There are two feeding methods - authomatical and manual. Automatical feeding
works only for new/updated item. By manual feeding it is possible to feed any
selected item to another slice (if you have permission to do so).
Manual feeding
In Item Manager select the items you want to send to another slice. Select "Export"
on the toolbar just below the itemlist. After clicking on "GO" a new
window is shown where you can select destination slices. (You must have a permission
in the destination slice - at least Author. If you are Editor or more in the
destination slice, you can set the "Active" checkbox, which means
to copy the items in the destination slice into the Active Bin. If the checkbox
stays unchecked, the item is copied to the Holding bin).
The feeding is error-safe, it is impossible to feed one item to the same destination
slice more than once.
Automatical feeding
Each Feed needs to be configured in both the slice where the items are entered
and which will export items, and for the slice where the items are imported.
Select the slice where the items are entered. Select Admin->Content Pooling
-> Inner Node Feeding. If you are willing for items to go to any other slice
on the same host then check "Enable export to any slice". Otherwise
uncheck this box, and move slices that you want to receive items to the Export
Enable box.
Select the slice where items will be received. Make sure the slice you want
to recieve from is in the Import box. As a courtesy send an email to the administrator
of the slices you want to receive from.
The import process can be fine tuned in two ways.
In Admin->Content Pooling->Filters you can select which of the exporting
slice's categories items come from, and to which categories of the importing
slice they are delivered. Select the Active box if you want items in this category
to be made Active, otherwise they will go in the Holding Bin for manual approval.
There is currently no way to control which items are fed, only which category
they go to.
In Admin->Content Pooling->Mapping you can control which fields of the
source slice end up in which fields of the destination slice.
If you want to export items already in the slice, then go to the Item Manager,
check the items to export, and choose "Export" and Go. This will give
a choice of destination slices, which you can check along with whether they
should be Active, or go to the Holding Bin for manual approval.
When you write an item which goes into the Active bin or when you approve an
item, the feeding function is invoked. This function finds all slices
where the item should be fed (depending on current feeding permissions ("Admin"
-> "Content pooling - Import & Export") and feeding setings ("Admin"
-> "Content pooling - Filters")). The feeding goes deeper and deeper between the slices until a cycle is detected or feeding into Holding bin is set.
Feeding one item from one slice to another means:
- 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.
These settings can be done on the "Admin" -> "Main settings -
Fields" -> "Edit" -> "Feeding mode" page, where you can set for each 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
Depending on field table flags, the flags for content table are set:
- 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.
There is solution for 'Internal feeding':
It could be done using field 'Mapping' ('Slice Admin -> Mapping').
One of the possibilities there is to select '-- Value --' for a field. The 'Value' is not ony static text, but you can use any AA alias construct there (just like: <a href="{source_href.....}">{source..........}</a>).
The solution is to specify such expression for 'status_code' field (which controls, in which bin resulting items appear:
1 - Approved
2 - Holding bin
3 - Trash
4 - Item is not fed
So, if you specify something like:
{switch({highlight.......})1:1:4}
for status_code field, only highlighted fields are fed (into Approved).
There is no way to do it for external (Inter Node or RSS) feeds. The only solution there is to feed all the items into one slice
and then show only highlighted items in destination slice (the
highlighted flag will be copied too, so there is no need for manual setting "highlighted" in destination slice)
CSN is a feature which allows item exchange between two servers.
Developers note: The implementation is based on Moritz Both's specification:
http://plus.aldebaran.de/apc-aa/csn.html
http://plus.aldebaran.de/apc-aa/csnspec.html
--------------------------------------------------
A. Installation
Node = one installation of ActionApps.
Assume there are two nodes, which want to exchange items
Step 1 Set up the node details,
- must be done by sysdadmins, with shell access on both nodes, but they only
have to be done once, no matter how many slices and how many nodes are configured,
normally it will have be done when ActionApps was installed.
Set the ORG_NAME in config.php3 file to the name of your organization, e.g.:
define ("ORG_NAME","Econnect");
Step 2 Set the information about the collaborating nodes.
- must be done by a Superadmin on both nodes, once for each node that it imports
or exports to.
- 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
In order the task from cron are started regulary, the cron must be well configured
by the system administrator. If the cron is configured, the column 'last_run'
on 'AA -> Misc - Cron' page is not empty and the value is time to time changed.
Please read section:
or such link to your index (or fulltext) design (Admin -> Design -> Index -> Odd Rows). This will point to fulltext of parent item or to the fulltext of the same item, if the item is not fed.
Normally you will want either a Item listing, Full text or Static Page view.
- 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.
You need to:
The program is implemented in discussion.php3, function send2mailList. It is called from filldisc.php3.
AA v2.0.0 supports discussions. The example, how the dicussions could look
is on:
http://aa.ecn.cz/template/news.shtml?x=39124
Discussions are quite configurable (through views and aliases). Discussions
can be easily managed in Item Manager - you can edit posted comments, Hide/Show
them and Delete it.
Note, that each discussion is allways related to one item in slice.
There are some steps you have to do, if you want to add discussion to items,
some of the steps depend on whether you are showing slices through slice.php3
or site.php3:
Design the Discussion
- Switch to slice, where you want to have discussions
- Go to 'Admin - Design Views'
- Choose 'Discussion' in the listbox and click 'New'
- 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)
- 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" ...)
- if you want comments to be approved before displaying then add the code:
<input type=hidden name=d_state value=1>
after the
- click on Insert to create the view
- The code below assumes the view created is number 55
Integrate into Full text View (if you are using slice.php3)
- Go to 'Admin - Design Fulltext'
- Select the created view in 'Show discussion' listbox
- 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.
- Go to 'Admin - Design Item Manager'
- Change the 'Item format' using _#EDITDISC alias. For example you can add
new column just like:
<td class=tabtxt><a href="_#EDITDISC">Edit</a>
(_#D_APPCNT/_#D_ALLCNT)</td>
- Possibly change 'Top HTML' for header of item manager and click OK.
Add to Listing views
typically you want the number of comments, and a link to either View or Add
Commends depending on whether there are any, code if called from site.php3 might
look like....
<a href="?{relargs}&i=_#SITEM_ID({switch({disc_app........})0:&add_disc=1}#disc">{switch({disc_app........})0:Add::_#D_APPCNT}
Comments.</a>
Done. Discussions works.
Aliases usable for discussions
Discussion design is defined in special view - 'Discussion' view. Following table shows aliases, which you can use for the design. Many of the aliases have also its own "field_id", which is presented in the second table column. The "field ids" you can use, if provided aliases do not fill your needs. If you want (for example) to modify date format, you can use
{alias:d_date..........:f_d:j. n. Y}
expresssion, instead of the _#DATE###_ alias.
_#SUBJECT_ | d_subject....... | subject of the discussion comment |
_#BODY###_ | d_body.......... | text of the discussion comment |
_#AUTHOR#_ | d_author........ | written by |
_#EMAIL##_ | d_e_mail........ | author's e-mail |
_#WWW_URL_ | d_url_address... | url address of author's www site |
_#WWW_DESC | d_url_descript.. | description of author's www site |
_#DATE###_ | d_date.......... | publish date |
_#IP_ADDR_ | d_remote_addr... | IP address of author's computer |
_#CHECKBOX | | checkbox used for choosing discussion comment |
_#TREEIMGS | | images |
_#DITEM_ID | d_item_id....... | comment ID (the same as _#ITEM_ID_) |
_#ITEM_ID_ | d_item_id....... | comment ID |
_#DISC_ID_ | d_id............ | item ID |
_#URL_BODY | | link to text of the discussion comment |
_#URLREPLY | | link to a form |
_#DISC_URL | | link to discussion |
_#BUTTONS_ | | buttons Show all, Show selected, Add new |
| d_parent........ | id of parent discussion comment |
| d_state......... | state of this discussion comment (0 - visible, 1 - hidden) |
Default values for discussion view
If the default values for the view design are missing, here are some values that work:
Top HTML
<table bgcolor=#000000 cellspacing=0 cellpadding=1 border=0 align="center"><tr><td
class="discuss"><table width=100% bgcolor=#f5f0e7 cellspacing=0
cellpadding=0 border=0>
HTML code for index view of the comment
<tr><td width="10"> </td><td class="discuss">_#CHECKBOX</td><td
width="10"
class="discuss"> </td><td align=center nowrap
class="discuss">_#DATE####</td><td width="20"
class="discuss"> </td><td nowrap class="discuss">_#AUTHOR##
</td><td class="discuss"><table
cellspacing=0 cellpadding=0 border=0><tr><td>_#TREEIMGS</td><td><img
src=http://work.ecn.cz/apc-
aa/images/blank.gif width=2 height=21></td><td nowrap class="discuss"><a
href=_#URL_BODY>_#SUBJECT#</a></td></tr></table></td><td
width="20"
class="discuss"> </td></tr>
Bottom HTML
<tr><td align="center" class="discuss" colspan=8><br>_#BUTTONS#<br><br></td></tr>
</table></td></tr></table>
Show images
on
Order by
thread
View image 1
<img src=http://work.ecn.cz/apc-aa/images/i.gif width=9 height=21>
View image 2
<img src=http://work.ecn.cz/apc-aa/images/l.gif width=9 height=21>
View image 3
<img src=http://work.ecn.cz/apc-aa/images/t.gif width=9 height=21>
View image 4
<img src=http://work.ecn.cz/apc-aa/images/blank.gif width=12 height=21>
*HTML code for fulltext view of the comment*
<table bgcolor=#000000 cellspacing=0 cellpadding=1 border=0 align="center"><tr><td
class="discuss">
<table width=100% bgcolor=#f5f0e7 cellspacing=5 cellpadding=0 border=0>
<tr><td class="discuss"><b>_#SUBJECT#</b></td></tr>
<tr><td class="discuss"><A href="mailto:_#EMAIL###">_#AUTHOR##</a>,
_#DATE####</td></tr>
<tr><td class="discuss"><br>_#BODY####<br><br></td></tr><tr><td
align="right"><a
href=_#URLREPLY>Reply</a></td></tr></table></td></tr></table><br>
HTML code of the form for posting comment
<SCRIPT Language="JavaScript"><!--
function checkData() {
var text="";
if(!document.f.d_subject.value) {
text+="subject "
}
if (text!="") {
alert("Please, fill the field: " + text);
return false;
} return true;
} // -->
</SCRIPT>
<form name=f method=post action="/aaa/filldisc.php3" onSubmit="
return checkData()">
<table bgcolor=#000000 cellspacing=0 cellpadding=1 border=0 align="center"><tr><td
class="discuss"><table width=100% bgcolor=#f5f0e7 cellspacing=0
cellpadding=5 border=0>
<tr><td class="discuss"><b>Author</b></td><td
class="discuss"><input type=text
name=d_author></td></tr>
<tr><td class="discuss"><b>Subject</b></td><td
class="discuss"><input type=text name=d_subject
value="_#SUBJECT#"></td></tr>
<tr><td class="discuss"><b>E-mail</b></td><td
class="discuss"><input type=text
name=d_e_mail></td></tr>
<tr><td class="discuss"><b>Comment</b></td><td
class="discuss"><textarea rows="5" cols="40"
name=d_body ></textarea></td></tr>
<tr><td class="discuss" colspan=2 align="center"><input
type=submit value="Send"><input type=hidden
name=d_parent value="_#DISC_ID#"><input type=hidden name=d_item_id
value="_#ITEM_ID#"><input
type=hidden name=url value="_#DISC_URL"></td></tr></table></td></tr></table></form>
Site Module
Current APC ActionApps are very good
for creation of small or not so complex database driven sites. It
was not so easy to create complex websites with many cooperating
slices and views, so far. The “site module” is the answer
for those, who wants to build complex websites using APC AA.
At the time I wrote the text, the only
sites driven by “site module” is the Econnect site
http://ecn.cz. ChangeNet site
http://changenet.sk and example
site on Sourceforge
http://action.org/slices/. I describe the
site module on Econnect's site. You will see, that the principles are
similar to all “site module” based websites.
The site module is part of AA admin
interface, just like other modules are. You can access it from
'Switch to' selectbox, if you have permission to. Site module allows
you to describe structure of the site – you modify there so
called sitetree. Sites based on the module do not need any special
files (like shtml, ...) - whole site could be managed using AA admin
interface (there is no need for FTP access (with one exception –
'main control script' file described later)). How to describe the
structure we will see latter in this text.
Idea - State and sessions
The first estimation in creation of
site module was the need to write it as fast as possible. The complex
sites used to be sites with many visitors a day. For better
performance is good to be able cache the generated pages. However, in
“pre-site module” approach each user gets its own session
id, which is unique for the user and help us to store the state,
where the user user is within the site (which page on page-scroller
she is on, ...). It is good, but it is extremely hard to cache such
informations. That's why we develop the site module without sessions
variables given to each user. We use “state string”
instead. There we store the state, where the user is within the
website.
State string is variable which we call “apc”
(stands for “Application Pointer Cache” :-) the name of
this variable is given – it have special behavior inside APC AA
(it is automatically added to all links generated by APC AA, for
example).
The “apc” variable is added to all links in
AA so you every time know, where the user was in step before.
For
example: if you get the link http://ecn.cz/index.stm?apc=zzvx1--&...,
you know, that user was in
“news-alerts-all_categories-all_regions-page1” page on
the site. How it is coded into “apc” state string is
another thing (and it is in most cases up to you) – will be
described in next caption.
“apc” state string
As you can see, the Econnect's apc
state string consist of seven state variables – each character
in the string is one variable in our case, but it is not a rule (in
fact the fifth state variable - “p” - page could be more
than one character long). All the state variables are defined in main
control file for the site - /module/site/sites/site_xxx.php3 (or its
alternative called (for security reasons) through http:// call). In
this file you define not only the number of state variables, the
regular expression for extraction the variables from apc state
string, but you specify there also the ways, how we have to change
the state. For example, if the site_xxx.php3 file gets the following
url parameter:
http://ecn.cz/index.stm?apc=zzvx1--&p=3
the state variable is changed to
apc=zzvx3--, which means that you are on the same webpage, but on the
page 3.
Now we describe the variables used on
Econnect's site, but keep in mind, that the variables used in your
site could be different (if you will).
Position in apc state string
|
Name of state variable
|
Possible states of the variable
|
description
|
1
|
w (web)
|
z,e,n
|
Main classification of pages – Econnect's pages are
divided into three webs: z – zpravodajstvi (news) e –
econnect n – nno (NGO related news)
|
2
|
s (subweb)
|
z,m,k,t,a,s (for w=z) 1,2,3,4,5,6,7,8,9 (for
w=e) N,F,P,I,J,V (for w=n)
|
Each web (w) is divided into subwebs, so for example web z –
zpravodajstvi contains: |z – news k –
comments t – press releases ...
|
3
|
f (filter)
|
Any letter
|
Primary use of this variable is to select category of shown
items (environment, human rights, culture,...), but each page
could utilize this variable for its own purpose (category of
grant, job, ...)
|
4
|
r (region)
|
Any letter
|
The same as f – primary use for region selection
|
5
|
p (page)
|
Any number
|
Stores the page number, where user is (switched by
page-scroller). Could be more than one character long in our
case.
|
6
|
t (type)
|
Any letter
|
Special type of output – like 'text only', 'printer
friendly', ...
|
7
|
x (item)
|
Any number
|
Id of item to show (like 24365) – as you see it could be
again more than one character long
|
You can use any number of any state
variables in your site and combine it together into apc state string.
The only thing you have to keep in mind is that apc state string must
be splittable into state variables. In Econnect's example we are
using following regular expression to get state variables from 'apc
state string'.
{w} {s} {f} {r} {p} {t} {x}
ereg( "^([a-zA-Z0-9_])([a-zA-Z0-9_])([a-zA-Z0-9_-])([a-zA-Z_]+)([-]|[0-9]+)([a-zA-Z_-])([0-9]*)", $apc, $vars ))
Main control file
Main control file is the only file you
will need to edit in the process of site creation. The file contains
script (probably in PHP) and its purpose is just parse 'apc state
string' into state variables and possibly change the state of the
variables based on the parameters it gets through url.
The script is called before any page of
the site is displayed. There is easy, but functional example of such
script. All comments are inside.
If $apc is not defined, we probably
access the main page (like http://ecn.cz).
if( !$apc ) $apc = 'zzvx--'; # initialize 'state string', if not set, yet
Split $apc state string into state variables (for now prefixed by 'o');
if( ereg( "^([a-zA-Z0-9_])([a-zA-Z0-9_])([a-zA-Z0-9_-])([a-zA-Z_]+)([-]|[0-9]+)([a-zA-Z_-])([0-9]*)", $apc, $vars ))
list($ostate,$ow,$os,$of,$or,$op,$ot,$ox) = $vars;
else # if the $apc is in wrong format, initialize it
list($ow,$os,$of,$or,$op,$ot) = array( 'z', 'z', 'v', 'x', '-', '-');
Now we have to program the reactions on special url requests. Wherever we are in the site and we click on the link containing w=z (like http://ecn.cz/index.stm?apc=zzvx1--&w=z), we change the state to 'news' section
if( isset($w) ) { # w stands for WEB
switch($w) {
case 'z':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('z','z','v','x','-','-',''); break;
case 'n':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('n','N','1','-','-','-',''); break;
case 'e':
list($ow,$os,$of,$or,$op,$ot,$ox)=array('e','1','1','-','-','-','73161');
break;
}
}
The same with state variable s, but we are switching within the same WEB (variable {w} remains unchanged)
if( isset($s) ) { # s stands for SUBWEB
$os=$s;
$ox=''; # $ow stays the same – we change subweb, not web
$op='1';
if( $old_w != 'z' ) # the format in zpravodajstvi stays the same
$old_f='';
}
Write rule for each possible url request.
if( isset($f) ) {$of=$f; $ox=''; $op='1';} # f stands for FILTER
if( isset($r) ) {$or=$r; $ox=''; $op='1';} # r stands for REGION
if( isset($p) ) {$op=$p; $ox='';} # page
if( isset($t) ) {$ot=$t; $ox='';} # switch to special mode
if( isset($x) ) {$ox=$x;} # item id to display
if( isset($scrl) ) { # page scroller
$pagevar = "scr_".$scrl."_Go";
$op = $$pagevar;
$ox='';
}
Finaly, save the final state of variables into $apc_state array. The key 'state' is used for storing new 'apc state string', other keys of the array are variables, which we can use in site module administration (in next chapter). There should be not only state variables, but any other variables which you want to use in site module, as well.
$apc_state = array ('state' => "$ow$os$of$or$op$ot$ox",
'w' => $ow,
's' => $os,
'f' => $of,
'r' => $or,
't' => $ot,
'p' => $op,
'x' => $ox,
# helper variables used in site module – you can define as many such
# variables as you want
'archive' => (($op>10)? 'archive' : ''),
);
You can find example of such file
in /modules/site/sites/ directory of ActionApps installation
Site administration
The HTML code for the pages is managed
from site administration page. The code is divided into pieces, which
is structured into tree structure – called sitetree. The
sitetree you can see on the left side of the administration
interface. During the displaying of the page, AA starts with the
first HTML piece and then goes down and prints the right branch of
the tree, based on the state of state variables. The piece of HTML
code could contain not only HTML code, but there could be
incorporated results of some slice view, as we see later.
We recognize two kind of HTML pieces –
'spots' and 'choices'.
a) spot
spot is HTML code which is simply
displayed. AA prints the contents of the spot and then the evaluation
continue with the spot just below. On the other hand 'spot' (as well
as choice) could be also the root of some branches of code. You can
make spot as root of branch by assigning any (decision) variable to
the spot. For example, if you assign variable 'w' to the 'start'
spot, you create the root of branches (choices). The evaluation will
continue in the branch (choice), where w satisfy the conditions.
b) choice
As you see, each choice belongs to a
spot, where a 'decision variable' is defined. Each choice has defined
a condition for the decision variable. AA prints only FIRST choice,
which satisfy the conditions. After evaluation of the chioce
(printing the output), AA continues with the spot on higher level of
the sitetree.
You can use regular expressions in the
conditions. You can also combine the condition for more than one
'decision' variable. The conditions are joined by the logical AND
operator.
Incorporating database views into output.
You can use not only HTML cote in the
spots, but you can incorporate here the outputs from any slice. The
slice output is always controlled by view in site module (we do not
use Fulltext or Index in site module). To include slice output use
the following construct:
{view.php3?vid=353}
This includes in the output the result
of view number 353. Although the {view.php3...} is just language
construct (it have only a little to do with view.php3 file), we can
use all the well known parameters we know from view.php3. So, the
following example is the one, we surely use in our site for
displaying the fulltext of the item x:
{view.php3?vid=217&cmd[217]=x-217-{x}}
As you see from the example, we can use
another language construct {x}, which is substituted by the content
of variable x (x is the state variable defined in 'main control file'
in $apc_state array).
Language construct to be used with site module
Syntax
|
description
|
{<variable>}
|
Returns content of variable (like {w})
|
{view.php3?vid=<vid>&<view parameters>}
|
Returns content of view <vid>. View uses the <view
parameters> just like the view.php3 script. (like
{view.php3?vid=122&cmd[122]=c-1-{f}} )
|
{switch(var1,var2,..)val1,val2,..:<printed
text1>:val1,val2,..:<printed text2>}
|
Returns <printed text1> or <printed text2> or ...
based on conditions val1,val2 for variables var1, var2, ... The
only first matching text is printed. You can use regular
expressions in conditions. (like
{switch(w)z:News:e:Econnect:.*:NGO} )
|
{# any text}
|
Comments – no output is printed
|
The construct could be nested –
the level of nesting is unlimited.
If you are using highlight field for displaying items on homepage and you want to allow people to be able to switch the highlight on and of quickly, then Live checkbox is the solution for you. It allows you to display checkbox directly in Item Manager, so users just check or uncheck in there. They do not need to go in item editing page and edit each item.
How to set it up
- Go to 'Slice Admin' -> 'Fields' and choose 'Edit' for field you want to use live checkbox (probably highlight....... or other Boolen field)
- Set alias (for example _#LIVECHBX) using f_k - Auto Update Checkbox
- Go to 'Slice Admin' -> 'Design - Item manager'
- Incorporate new alias (_#LIVECHBX) into Item Manager design
- Done
Warning: Access denied for
user: 'aadbuser@xxxxx' (Using password: YES) in
/usr/local/web/phplib/db_mysql.inc on line 73 Database error:
pconnect(xanadu.cyborganic.org, aa-user, $Password) failed. MySQL Error: 0 ()
Please contact foobar@somewhere.com and report the exact error message. Session
halted.
Typically this means that the DB_HOST, DB_USER, DB_PASSWORD, DB_NAME setup
during editing config.php3 in Install 4.1 don't match the one you gave
permissions to in Install4.2. In particular note that if the DB_HOST is absolute
e.g. "aa.apc.org" then the permissions are going to have to include the machine
name that the Apache server runs on e.g. aadb@bigserver
ActionApps empower anyone to publish online, saving you the money you'd
normally spend on web specialists (or training). ActionApps also make your team
more efficient—since the people who create your group's information can publish
it online themselves. Finally, ActionApps' Content Pooling technology, by
letting you trade articles with partner sites, helps you access new content
(theirs) and new audiences (for yours). About ActionApps presents more about benefits, while Strategic Uses offers tips on adapting ActionApps to
your own needs.
Web Networks' case studies can be viewed here
Also see our growing list of ActionApps examples
In Slice admin interface form for configuring fields there is an input box
for parameters of insert function. For field with insert function "File = uploaded
file",
you can set these parameters:
type of file : maximum image width : maximum
image height : secondary image fields delimited with ## separator
Example:
if you insert parameters:
image/*:450:600:image.....1##image......2
function will do these actions after submitting the item/article:
- 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
Setup your slice as normal, got to Slice Admin -> Views -> type:RSS News.
You can edit the feed to more precisely pick what you want for each item. Use the _#RSS_* aliases to refine it.
The URL of the RSS feed should be at /apc-aa/view.php3?vid=xx
When we setting up aliases for database field on se_fields.php3 page, we sometimes need to change the behavior of alias in som way or we need to pass some parameter for alias handling function such as f_f. The Parameters field is the right place, how to do it. The list of parameters for each alias function follows.
In some cases we need to pass more than one parameter to alias function. In such case the aliases are separated by colon character. If we need to use colon inside parameter, we just use #: string instead of : character.
Function | Parameter | Description |
f_x | transformation |
| content value (pairs) pairs | the content of the field and the value to return, the content can be a regular expression as in http://www.php.net/manual/en/ref.regex.php |
| default | value returned if no match |
f_0 | null function (nothing shown) |
| none | |
f_h | print field content due to html flag set (escape html special characters or just print) |
| delimeter | if delimeter parameter is specified, the field with multiple values are displayed as list, delited by delimeter |
f_d | prints date in user defined format |
| format | format string just like in PHP (like "m-d-Y") - see PHP manual |
f_i | prints image scr (<img src=...) - NO_PICTURE for none (the functionality of this alias function can be created as conditional f_c function as well) |
| none | |
f_n | unpacked id |
| none | |
f_g | prints image height atribut (img height=...) or clears it (the functionality of this alias function can be created as conditional f_c function as well) |
| none | |
f_w | prints image width atribut (<img width=...) or clears it |
| none | |
f_a | prints abstract or grabed fulltext text field |
| length | length - number of characters taken from field_id (like "80:full_text.......") |
| field_id | id of fulltex field |
f_f | prints link to fulltext (hedline url) |
| link_only | field id (like "link_only.......") where switch between external and internal item is stored |
| redirect | url of another page which shows the content of item (like "link_only.......:http#://www.ecn.cz/articles/solar.shtml") (note the #: in previous example!)
this page should contain SSI include ../slice.php3 of course |
f_b | prints text with link to fulltext - more general version of f_f function param: link_only:url_field:redirect:txt:condition_fld (hedline url) |
| link_only | field id (like "link_only.......") where switch between external and internal item is stored |
| url_field | field id of external url for link_only
(like hl_href.........) |
| redirect | url of another page which shows the content of item (like "link_only.......:http#://www.ecn.cz/articles/solar.shtml") (note the #: in previous example!)
this page should contain SSI include ../slice.php3 of course |
| txt | if txt is field_id content is shown as link, else txt |
| condition_fld | field id - if no content of this field, no link |
| addition | additional parameter to <a tag (like "target=_blank") |
f_t | converts text to html or escape html (due to html flag) |
| none | |
f_s | print database field or default value if empty (the functionality of this alias function can be created as conditional f_c function as well) |
| default | default value (like "javascript: window.alert('No source url specified')") |
f_l | prints field as link, if field_id in $param is defined, else prints just field |
| field_id | field_id of possible link (like "source_href.....") |
f_e | http://actionapps.org/aa/admin/itemedit.php3?AA_CP_Session=f48237b26098d261a71de80ded1c49c4&edit=1&encap=false&id=6525acb6a0ceb34e3db375618efe19f0 used on admin page index.php3 for itemedit url |
| none | |
f_c | prints "begin".field."end" if field="condition", else prints "none"
if no cond_col specified - this $col is used
condition can be reversed (negated) by "!" character at the begin of condition
param: condition:begin:end:none:cond_col |
| condition | |
| begin | |
| end | |
| none | |
| cond_col | |
| Example: 1:Yes<!--:-->:No
This example is usable for example for Highlight field - it shows Yes or No depending on highlight field |
| Example: !:Email#:::
If e-mail field is filled, it shows "Email: email@apc.org" (for example), but if it is not filled, it shows nothing |
f_u | calls user defined function (see How to create new aliases) |
| function | name of called function in include/usr_aliasfnc.php3 file |
| parameter | parameters passed to function |
f_m | mailto link - prints: "begin<a href="(mailto:)$col">field/text</a>" if no $col is filled, prints "else_field/text" |
| begin | text before link (for example "e-mail") |
| field/text | if field id specified, the field is used as link text else the text is used insteed. |
| else_field/text | if no e-mail addres specified in $col, the field content (or text) is displayed |
| linktype | mailto / href (default is mailto) - it is possible to use this function for links, too - just type "href" as last parameter |
i_s | image size and other properties - as default prints: 'height="xxx" width="yyy"', where xxx and yyy are the height and width of the image in pixels. Other properties can be printed as well.
Returns empty string if it cannot determine the width or height. |
|
information |
- html (default) - returns image size as HTML atributes (height='xxx' width='yyy')
- width - returns width of image in pixels
- height - returns width of image in pixels
- imgtype - returns flag indicating the type of the image: 1 = GIF, 2 = JPG, 3 = PNG, 4 = SWF, 5 = PSD, 6 = BMP, 7 = TIFF(intel byte order), 8 = TIFF(motorola byte order), 9 = JPC, 10 = JP2, 11 = JPX, 12 = JB2, 13 = SWC, 14 = IFF, 15 = WBMP, 16 = XBM
- mime - returns mimetype of the image (like 'image/gif', 'application/x-shockwave-flash', ...)
|
f_y | Expanded string: expands the string in the parameter.
If you need use aliases in a database field. It can be used e.g. for including photographs from the slice "Photogallery" to the field "full_text......." in the slice "Articles". See an Example. |
|
string to expand |
If specified then this string is expanded, if not specified then expands the contents of the field. |
The slice.php3 is the main script used to display items from database. The alternative for this script is view.php3.
The main ussage of slice.php3 script is to include it into some .shtml file by the SSI include command - like:
<!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6"-->
The following parameters you can add just like url parameters. It is possible to combine more than one parameter. Example:
<!--#includevirtual="/aaa/slice.php3?slice_id=a91256ed53287912d74495d781076bd6&listlen=10&no_scr=1"-->
The slice.php3 is there from the beginning of ActionApps, so some of the parameters are quite old. Such parameters are still implemented, but in many cases it is better to use newer - more powerfull substitution for the parametr. That's why the list is prioritized from the most common parameters (which should be used) to the old parameters (which use is deprecated).
The only way, how to display data from slices, where 'Reading Password' is set. See: http://apc-aa.sourceforge.net/faq/#slice_pwd
Parameter | Required | Description |
slice_id | Yes | id of displayed slice |
conds[] | No | very usefull for complex conditions - see How to setup the searchform? for conds parameter setting (it can be used as url parameter too - not only form Forms, as described in search section) Example:conds[0][category........]=Environment&conds[1][category.......1]=Waste |
defaultCondsOperator | No | replaces LIKE for conds with not specified operator - simplified syntax of conds[] uses LIKE operator as default - you can change it by this operator to RLIKE for example (RLIKE is better in many cases - at least it is much faster from database point of view) Example: defaultCondsOperator=RLIKE&conds[0][category........]=Environment |
neverAllItems | No | if set, don't show anything when everything would be shown (if no conds[] are set) - good for search pages, where on the top (or bottom) is searchform - normaly, for the first time (when you did not send the searchform), all items are shown - if you want to have there only blank page intead, use this parameter |
sort[] | No | see conds[] - very usefull for complex sorting Example:sort[0][pub_date........]=d&sort[1][headline........]=a (a ...ascending order; d ... descending order) |
x | No | the same as sh_itm, but short_id is used instead (implemented for shorter item url (see 1767 alias)) |
iview | No | changes the design of index item listing to the design defined in specified view. The view should be of 'Item listing' type. Example: iview=49 - listing of items generated by slice.php3 will use format-strings as defined in view No. 49 |
fview | No | changes the design of fulltext to the design defined in specified view. The view should be of 'Fulltext view' type. Example: fview=48 - the item displayed by the slice.php3 script will use format-strings as defined in view No. 48 |
dview | No | uses specified view for discussions instead of the one specified on 'Slice Admin' -> 'Design - Fulltext' page. (good for testing new discussion view, ...) Example: dview=18 - view 18 is used as tepmlate for discussion design in this slice |
listlen | No | change number of listed items in compact view Example: listlen=10 |
slice_pwd | No | Example: slice_pwd=VerySecret |
no_scr | No | if true, no page scroller is displayed Example: no_scr=1 |
group_n | No | displayes only the n-th group (in listings where items are grouped by some field (category, for example)) - good for display all the items of last magazine issue Example: ( group_n=1 ) |
slicetext | No | displays just the text instead of any output - can be used for hiding the output of slice.php3 Example: slicetext=%20 |
highlight | No | when true, shows only highlighted items in compact view Example: highlight=1 |
als[alias] | No | user alias definition - you can define your own aliases in url (for both - slice.php3 and view.php3). Aliases names MUST!!! be 8 characters long. Don't forgot, that the alias value have to be urlencoded. Example: als[MY_ALIAS]=Summary%20Page (or maybe better: als%5BMY_ALIAS%5D=Summary%20Page) defines alias _#MY_ALIAS. If used in formatstring ('Admin - Design Index' for example), it prints 'Summary Page' |
inc | No | for dispalying another file instead of slice data (for example some static html file) Example: inc=/contact.html |
items[id] | No | array of items to show one after one as fulltext (ids are the long ones - see sh_itm, but there is special 'x' character before each index). Example: items[x5462876e8ab29ac95462876e8ab29ac9]=1&items[x65ac876e8a555b29543ea76e8ab29a34]=1 (doesn't matter which value is given to element (1 or 'on' or ...) - good for display of the form, where you select which item to show) |
hidefulltext=1 | No | if you add this parameter to url, the fulltext is not shown when you go to page, where the specific item should be displayed. The discussions under the fulltext are not hidden. It is usefull, if you want to show discussions for the item on separate page. On the other hand, probably better results You can get by using fview parameter. |
banner=2-38 | No | by this parameter you are able to display any view (38 in or case) inserted just after the second (2) item in view (number 23). The item shown in inserted view (38) is selected randomly, possibly with weight specified in weight field (number.........1) - just like in random parameter described above. If you do not want use random item (banner), use 'norandom' keyword in place of 'weight field' (good for displaying nested newsbox). See also banner parameter for view.php3. The example of included banner is on http://ecn.cz. Example: banner=2-38 or banner=2-38-number.........1 or banner=2-38-norandom |
nocache=1 | No | URL parameter for page refresh - the items are not taken from cache (- no matter if allready cached or not). Cache is updated. |
searchlog | No | if you add searchlog parameter to the slice.php3 script on some search page, all searches (by conds[]) are logged into database table searchlog. There are logged not only the conds[] parameters, but also the time, which database spent on the query. The access to the log is for superadministrators only, right now. You will find it on 'AA' -> 'Misc - ' page in AA admin interface (or you can look into searchlog table in the database). |
scr_url=script_name | No | scr_url parameter is answer to problem mentioned in apc-aa-general mailinglist (apc-aa-general mailinglist). If you try to include the slice.php3 into your php3 script by calling include("http://www.sitename.org/apc-aa/slice.php3...");, the page scroller do not work, becouse the called script (slice.php3) do not know from which script it was called. But the scroller should know it - scroller should point to the same page - to the calling one. By scr_url parameter you can define the name of calling script. Example:
include("http://www.sitename.org/apc-aa/slice.php3?...&scr_url=%2Fscripts%2Findex.php"); ('%2F' stands for ' / ' character). |
sh_itm | No | id of item to show - if specified, selected item is shown in full text Example: index.shtml?sh_itm=01ac1b10fae13c0a61c5292ba72d70b1 |
restrict | No | field id used with "res_val" and "exact" for restricted output (display only items with "restrict" field = "res_val" Example:restrict=category........&res_val=Environment&exact=1 |
res_val | No | see restrict |
exact | No | if set, restrict field must match res_val exactly (=) otherwise substring is sufficient (LIKE '%res_val%') |
order | No | order field id - if other than publish date add minus sign for descending order Example: order=headline........- |
timeorder | No | if rev - reverse publish date order (less priority than "order") Example: timeorder=rev |
scr_go | No | sets page scroller to specified page Example: scr_go=2 |
encap | Yes for not encapsulated | determines wheather this file is SSI included to .shtml file (<--#include virtual="... ) or called directly as slice.php3 Example:encap=false |
cat_id | No | select only items in category with id cat_id Deprecated - better to use restrict and res_val parameters - or even better conds[] parameter |
cat_name | No | select only items in category with name cat_name as substring Deprecated - better to use restrict and res_val parameters - or even better conds[] parameter |
srch | No | true if this script have to show search results Not supported from AA v1.5 |
If you find no alias function is good enough for you, you can write your own. function. The alias functions are stored in include/item.php3 file and its names begins with f_ (but we can name it as g_* or such, as well) and they are three letters long (just like f_a()).
All you have to do for new function is:
- Write your own function in item.php3 (say f_9()).
- Add description of the function into param wizard definition file
include/constants_param_wizard.php3 (structure described inside
this file)
- Add human readable messages into include/en_param_wizard_lang.php3 language file.
- 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!!!
The example listing of /include/usr_aliasfnc.php3 (the file should not be committed to CVS, because it is very proprietary and the content should not be shared between installations): <?php //usr_aliasfnc.php3
/** Prints czech date (for Ekolist pages)
* @param columns - array of all field values for all ifelds in current item
* @param col - fileld id of field, for which the alias is defined
* @param param - possibly parameters to alias function passed in alias definition parameter (usr_cz_date:parameter)
*/
function usr_cz_date($columns, $col, $param="") {
$dte = $columns[$col][0][value];
$month = array( 1 => "ledna", "unora", "brezna", "dubna", "kvetna", "cervna", "cervence", "srpna", "zari", "rijna", "listopadu", "prosince");
$weekday = array("nedele","pondeli","utery","streda","ctvrtek","patek","sobota");
$m = $month[ date("n", $dte)];
$end = ( !$param ? "" : " (". $weekday[ date("w", $dte) ]. ")");
return date("j", $dte) .". $m ". date("Y", $dte). $end;
}
?>
Such alias function can be called by defining new alias for some field. Just define alias name (as obvious), alias function should be "f_u - user function" and the parameter should be the name of the function ("usr_cz_date" in our example). It is possible to pass parameters to the function. The parameters are separated by colon (usr_cz_date:parameters).
The script cron.php3 -
similar to Unix cron - is able to run PHP scripts on given time.
If you want to send e-mail notifications if some condition is satisfied or if
you want to exchange items between slices regularly, you will find it
useful.
The reason for this script to exist is that it's not easy to run PHP scripts
by the Unix cron. It also allows us to use admin interface (AA -> Misc - Cron)
to add/modify new tasks to run.
If you want to run some task on given time (like running admin/xmlclient.php3
for Cross Server Item Exchange each 15 minutes), you have to do two steps:
- add new task on cron admin page (AA -> Misc - Cron)
- 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)
(it is just an example - the set of task could be changed in next release of ActionApps)
2. Start cron.php3 periodicaly from unix cron
This must be done by a system administrator (i.e. someone with root shell access), but only
has to be done once no matter how many task are sheduled then.
In order we can shedule tasks from ActionApps we
must run periodicaly the script cron.php3 (based in root apc-aa install directory). It is not
so easy to start php scripts directly from unix cron, that's why you should use aa-http-request
shell script (based in misc/ directory), which will start cron.php3 script for you.
The instructions for setup of the aa-http-request script is also inside the script. For setup
follow the nex few steps:
- 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...
Here are some links you may find useful and interesting:
Detailed, fictional, case studies of uses of apc-aa:
* http://www.apc.org/actionapps/english/general/uses.html (in english)
* http://www.apc.org/actionapps/espanol/general/uses.html (in spanish)
If you are an APC member, I _strongly_ recommend you read the
APC ActionApps Product Development Guidebook. Find it on:
* http://intranet.apc.org/ (password protected)
If you use ActionApps regularly, joining the apc-aa-general
mailinglist is a good idea:
* http://sourceforge.net/mail/?group_id=6341
Here is some additional, less focused, background reading:
PLANNING
(article) Overview of planning a database-backed website (long)
http://www.techsoup.org/articlepage.cfm?ArticleId=375&topicid=13
(list of links) Web-site Management
http://www.itrainonline.org/itrainonline/english/management.shtml
Different APC providers offer different services based on ActionApps. So prices vary. For specifics, please ask your APC provider.
The Action Applications were developed by the Association for Progressive Communications, http://www.apc.org/. They are released as open source and there is a project set up at SourceForge. The Action Applications SourceForge page can be found at http://sourceforge.net/projects/apc-aa/.
The applications in v1.5+ can be created quite easy.
- Choose a slice and create the set of fields you want to have in the new application.
- For these fields change the default values, help texts, names, priorities,
aliases, etc. in the admin interface ("Admin" -> "Main settings
- Fields").
- 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")
- Test the new slice, whether it is working O.K.
- Add a new slice based on this one (not a template, but a slice)
- Mark the new slice as a Template ("Admin" -> "Main settings
- Slice") - to do this you must be the superadministrator (four stars).
If you are a developer and are interested in the ActionApps, we want your help. You can either offer to help our team directly or you can work on your own modules and release them under the GPL. Either way, you should check in with us on current developments and plans. Visit the ActionApps developer Website at http://www.sourceforge.net/apc-aa
To edit a file, you should work on a copy of the full APC-AA distribution, make changes and then check back the changed files
To check out the whole of apc-aa into some directory or other, you need to do it differently from the standard installation instructions if you plan on editing files.
The first time you use a particular CVS host you need to do ....
$ ssh yourusername@cvs.apc-aa.sourceforge.net
It should log you in, and straight out again (accept the host key if it asks
you to)
$ export CVS_RSH=ssh #for bash for example
or
setenv CVS_RSH ssh # for tcsh for example
$ cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
yourusername@cvs.apc-aa.sourceforge.net's password:
If it doesn't ask for a password, but you get an error about connection refused its probably because it didn't see the CVS_RSH environment variable.
Edit the file, then
If the file is not already in the CVS repository, for example, because you
have created a new file, then first add it to CVS with
$ cvs add myfile.htm
then upload with for example
$ cvs commit myfile.htm
Make sure to put in a useful comment when prompted by CVS.
Note, Its best NOT to do a plain
$ cvs commit
As this will commit files that you probably don't want to, especially config.php3
If you get the error:
Could not chdir to home directory /home/users/y/yo/yourusername:
No such file or directory
cvs [server aborted]: can't chdir(/home/users/y/yo/yourusernameNo such file
or directory
Then you need the ssh trick.
You can't use pserver: to check the files out, if you are going to commit them
back again.
Yes - this works fine,
You need to setup config.php3 correctly,
Assuming you want the same data to appear on both, then
the key variables seem to be.
AA_INSTAL_URL which can either point to one location, or different locations for each server such as http://www1.yyy.com and http://www2.yyy.com.
DEFAULT_ORG_ID will be the same for both
DB_HOST , DB_USER and DB_PASSWORD will be the same in both cases and point to the database server
DB_NAME will be "aadb" in both cases, i.e. they are using the same set of slices.
AA_ID will be the same in both cases.
Cron feeding to other hosts should be run on one machine only.
If you want totally independent data on each web server, for example if they are serving up totally different slices, then set DB_HOST to different values and AA_ID to different values, and have Cron work on both.
There are two branches, currently (9 Jan 2001) these numbers are
(main) developer 2.1.0
stable 2.0.1
Production systems will probably want to work with 2.0.1, although 2.1.0 is
fairly stable.
In theory, to discover which version you are using, look in "CHANGES",
for example
apc-aa.sourceforge.net/aa/CHANGES
shows that Sourceforge
is still running the stable branch, but note that CHANGES is frequently NOT updated to show
the version number of the developer version, and the current developer version shows the same version 2.0.1 with just a few more dated changes.
If you check out the default method:
cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa -r2_0_1
co apc-aa
OR
cvs -d:pserver:anonymous@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co -rv2_0_1
apc-aa
you will get the developer branch, but
cvs -z3 -d:ext:yourusername@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
OR
cvs -d:pserver:anonymous@cvs.apc-aa.sourceforge.net:/cvsroot/apc-aa co apc-aa
Note that you cannot assume that different branches will run with the same
Database.
In particular to upgrade from 2.0.1 to 2.1.0 you need to run sql_update.php3
to upgrade the database fields.
If you are unable to edit php.ini, then you won't be able to change the include path to point at PHPLIB, in this case edit the APC-AA/include/config.php3 to add the following lines.
# PHPlib directory if not on include path
$_PHPLIB["libdir"] = "/www/mysite/phplib/php/";
Change the site to point at the location where you have installed phplib.
You can also access PHPLIB by putting the following line in your .htaccess
php_value include_path ".:/usr/local/lib/php:/usr/local/lib/php/phplib"
You can create your own usr_validate.php3 with a user validation function in it (sorry at this point there can only be one for an apc-aa installation, we'll fix that later, if you need it to validate multiple fields you can make it switch based on the field name).
Here is a sample validation function. If the file include/usr_validate.php3 is present it will be included automatically.
<?PHP
// ----- Sample code -------
// returns new value for the field.
// or just return $value;
function usr_validate( $varname, $showname, $value, $err, $f, $fields)
// $varname -- name of variable
// $showname - name of variable in the page.
// $value - value of the input field.
// $err - validated or not.
// Standard way:
// $err["$varname"] = MsgErr(L_ERR_IN." $inputName");
// $f - I DON"T KNOW... please read admin/itemedit.php3
// you can get all the info about the field. include name.
// $field - - all the fields
{
if (!$value) // no value set in the input field
return "Hey! It is working."; // set default value of the field
else if ($value == "stupid") { // if value is "stupid"
// set error
$err["$varname"] = MsgErr(L_ERR_IN." $showname".". Do not use the word.");
return "fool"; // return error, and change value to "fool".
}
else
return $value; // same value. no change.
}
?>
There are several recent (Mar 2002) changes to make it easier to call apc-aa modules, especially the item manager, from php code.
Sample code to call admin/index.php3 (item manager) from outside.
file: apc-aa/sample/itemmanager.php3
(this need to stay same level of folder with apc-aa/admin/ )
<?PHP
# parameter
# project_id - slice id for project slice.
#
# Usage:
# http://host.name/apc-aa/sample/itemmanager.php3&project_id=<slice id>
# <slice id> : slice id to be open ....
# optional parameter:
# Tab - this is for admin/index.php3 to select Table.
# ="app" - Active bin (default)
# ="appb" - Pending bin
# ="appc" - Expired
# ="hold" - Hold bin
# ="trash" - Trash
#
# AA_CP_Session - session id
#
require "../include/init_page.php3";
// this check AA_CP_Session and open login prompt and call me again.
// also it sets slice_id, is session is already there.
if( isset( $sess ) )
page_close(); // this will store session variables in database.
// === prepair parameters to call admin/index.php3 ===
// use change_id if we open the slice 1st time.
if ($project_id == $slice_id)
$slice_param = "&slice_id=$project_id"; // we may not need this.
else
$slice_param = "&change_id=$project_id";
// table to open (active,trash,hold,expire,pending...)
$tab_param = $Tab ? ("&Tab=".$Tab) : "";
// filter parameter from apc-aa/admin/index.php3
$filter_param = (!$admin_order)? "" :
"&admin_order=$admin_order".
"&admin_order_dir=$admin_order_dir".
"&admin_search=$admin_search".
"&admin_search_field=$admin_search_field";
// parametere for scroller -- set by admin/index.php3 (at callback)
$scroller_param="";
if ($scr_st3_Mv) $scroller_param .= "&scr_st3_Mv=$scr_st3_Mv";
if ($scr_st3_Go) $scroller_param .= "&scr_st3_Go=$scr_st3_Go";
$debug_param = $debug ? ("&debug=$debug") : "";
// parameter to call myself from admin/index.php3 (admin/index.php3 will call me back)
$my_param=
"AA_CP_Session=$AA_CP_Session".
"&project_id=$project_id".
"&projects_item=$projects_item".
$tab_param.
$debug_param;
$MY_URL=urlencode($PHP_SELF."?".$my_param); // &return_url=.... for itemedit.php3, etc.
// So, all parameter to call admin/index.php3 is prepaired we write the page.
?>
<?PHP // -- showing Project Tasks (a slice made from "Project Tasks (template)" )
// -- now , we are using ItemManager of APC-AA as our ItemManger (not slice.php3 with index view) $pts_item_manager = "http://localhost/apc-aa/admin/index.php3". "?AA_CP_Session=$AA_CP_Session". $slice_param. $tab_param. $scroller_param. "&bodyonly=1".
"&action_selected=1".
"&sort_filter=1".
"&return_url=$MY_URL".
$debug_param. ""; include $pts_item_manager; ?>
# action_select=1 turns off "Feed selected" and "View selected"
# sort_filter=1 turns off the sort line
# scr_st3_Mv and scr_st3_Go can be set to work with the scroller
The action apps software uses the mysql database engine to store its data. The mysql database system is very very reliable.
If the server is interrupted in the middle of a transaction, it can corrupt the database. For example, the servers at SangoNet had a power
failure, and one of the mysql tables got corrupted. This shows itself in
the actionapps by one of the pages not working and reporting a mysql error
about a corrupted database.
It is usually easy to fix a mysql database that has been corrupted. In this case, I just went to /var/mysql (where databases are stored)
and checked to see if there were any errors. Mysql uses a program called
isamchk to detect and fix errors. This command checks to see if any of
the table in any of the databases is corrupted:
/var/mysql > isamchk -s */*.ISM
In this case, the aadb/pagecache.ISM file had two errors.
So I ran isamchk in recover mode to fix pagecache.ISM:
/var/mysql > isamchk -r aadb/pagecache.ISM
There was changed behavior of string removing in AA v2.6. Now we use much easier steps:
- unalias (expand) whole text (replace aliases and any other AA expressions)
- remove all specified remove strings
Following worked in AA v2.4 and less, so now is OBSOLETE
Removing of stings works before alias substitution - it never replaces the text filled by user in the field. If you have
=> _#HEADLINE (_#AUTHOR##)
and remove string "()", than it first looks for empty alias content and then removes such aliases.
Let _#HEADLINE = "Hi Ann"
and _#AUTHOR## = "" (empty)
In first step the emtpty aliases are removed:
=> _#HEADLINE ()
Then the "remove strings" are removed:
=> _#HEADLINE
and then the remaining aliases are substituted.
IIS is not a supported platform for APC-AA or at least it is not tested on this platform. There were some limitations in IIS v4.0 (I'm not sure, how it is in v5.0), which makes AA half-usable. There was a problem of not passing url parameters
to a script, which is included by SSI include into an shtml page.
The requirements are on:
<a href="http://apc-aa.sourceforge.net/apc-aa/doc/install-2.html">apc-aa.sourceforge.net/apc-aa/doc/install-2.html</a>
APC-AA is tested at least on Linux/Apache+MySQL+PHP and on Win98/Apache+MySQL+PHP (as a home developer installation).
The easiest way how to run AA on home Windows machine is to install PHPTriad (Apache, MySQL, PHP), which is really easy, see <a href=http://www.phpgeek.com>www.phpgeek.com</a>
The ? only shows if their is a URL in the morehelp field. This is setup automatically to be http://aa.ecn.cz/aa/doc/help.html.
You can remove it on fields individually via Admin->Fields->anyfield -> More help and deleting the text which is there.
If you are too lazy to do this on every field, then ask your system administrator to run:
UPDATE field SET input_morehlp='' WHERE input_morehlp = 'http://aa.ecn.cz/aa/doc/help.html'
For future refence, the function that creates this link to help is in include/formutil.php3 : function PrintMoreHelp
Sure - here is a little example that shows how to write a little Perl program to execute and return a SQL string.
#!/usr/bin/perl -w
# this script demonstrates how to use perl to look at the
# mysql database for a slice.
# This particular script looks some of the attributes of a slice's fields
# EDIT NEEDED: set these variables!
# $slice_id $user $password $database $host
# create connection to mysql, using perl DBI module
use DBI;
$dsn = "DBI:mysql:$database:$host";
$dbh = DBI->connect($dsn, $user, $password);
# convert a Hexadecimal input into a packed string
$p_slice_id = pack 'H*', $slice_id;
# create a SQL statement handle, and prepare a template.
# Templates make quoting easier.
my $sth_p = $dbh->prepare(
q{ SELECT id, name, feed, input_show_func from field where slice_id = ? }
) or die $dbh->errstr;
# run the statement, using the packed sliceid, and print the results
$sth_p->execute($p_slice_id) or die $dbh->errstr;
DBI::dump_results($sth_p);
The Rich Text Editor is a powerful editor allowing to copy content from web pages by copy-and-paste.
Most of the icons used to format your text are self-explained. On the first row in the right half there are icons for table creation and manipulation.
The rightmost icon on the first font switches between Wysiwyg and HTML view, allowing to see and modify your HTML code.
The sweep icon near the font size selectbox is a "<font> eraser". It clears all <FONT ...> and </FONT> tags in your HTML code which is useful when cleaning code copied from some web page.
Create a directory under which a sub-directory will be created for each slice,
either create that under one of your sites, or create it somewhere else and
create an alias in httpd.conf to point at it. Make sure this directory is
"rwxrwxr-- nobody.nobody"
Edit apc-aa/include/config.php3, edit the defines IMG_UPLOAD_PATH and
IMG_UPLOAD_URL to point to this directory. Note the trailing "/".
IMG_UPLOAD_TYPE needs configuring, but its not clear what exactly this means.
All configuration options are in config.php3:
define("IMG_UPLOAD_MAX_SIZE", "400000"); # max size of file in picture uploading
define("IMG_UPLOAD_URL", "http://work.ecn.cz/img_upload/");
define("IMG_UPLOAD_PATH", "/data/www/htdocs/work.ecn.cz/img_upload/");
define("IMG_UPLOAD_TYPE", "image/*");
define("IMG_UPLOAD_DIR_MODE", 508); # mkdir perms (508 = 0774 in octal, but
# octal value in constant don't work)
When you submit first item with image in the slice, AA will create new subdirectory under the IMG_UPLOAD_PATH directory. The name of this directory is the slice id. In this example we can expect the directories like:
/data/www/htdocs/work.ecn.cz/img_upload/f4c90ee8ef46cd6fa0a4521c61a28f4f
/data/www/htdocs/work.ecn.cz/img_upload/5d2b4ed6778fe3ac6db6ec74ceee650d
The directories are created with IMG_UPLOAD_DIR_MODE mask.
The image upload function is quite easy and you can find it in include/itemfunc.php3 file - function insert_fnc_fil().
(c) Jakub Adámek, Econnect, January 2003
Since January 17 2003 AA is using the mini-gettext language environment. The
language files are in the directory include/lang/
.
Each file is connected with one language and a series of PHP scripts. At run-time,
you can only use one file for translations at a time, but you can change freely
between files by using the bind_mgettext_domain()
function in
include/mgettext.php3
.
The files are maintained by people — translators and by the PHP function
xmgettext()
in misc/mgettext/xmgettext.php3
. Translators
add new translations and xmgettext() adds new strings to be translated which
it finds in the source files.
Notes for Translators
To add new translations, you only need to find empty strings ""
in your language files, e.g. $_m["not yet translated"] = ""
.
Please mind some following notes.
The language files are regular PHP files, you must not break the syntax. You
must not change the ID string in _m["..."]. Even if it contains bad English,
it may be changed only in the source code, not in the language file. There
is also an English translations file, thus small changes may take place there.
You must follow the PHP syntax for strings, using \"
and
\$
instead of "
and $
. You must quote the
translation with ""
. (You might quote it with single quotes as
well, but next time xmgettext()
will be run, it will reformat
all strings to double quotes.)
Each language string is preceded by links to source code where it is used.
If you are not sure how to translate a string, go to the source code and have
a look. Some language strings contain parameters %1,%2
etc. which
will be replaced by some variable content at run-time. Place the parameters
appropriately in the translation.
The file begins with a list of "Unused messages" which are there
only for your convenience so that you may use the text for the new translations
if necessary. You can freely delete any unused messages.
Notes for Developers
Have a look at Notes for Translators. The explanation of using mini-gettext
in code follows.
The simple syntax: A string becomes language string by enclosing into _m("
")
, e.g.
_m("any string")
.
It is better to create long strings than to concatenate short ones, because
translators may easier understand the meaning.
The parametrized syntax: You must not use variables in language strings. But
you can use parameters %1,%2,...
with the syntax of
_m("... %1 ... %3 ... %2", array ($param1,$param2,$param3))
,
e.g.
_m("Click on %1 to get more help.", array ($url))
or
_m("Error %1 in file %2 on line %3", array ($err,$file,$line))
.
Always use the array()
even when using only one parameter %1
.
To update language files, use xmgettext()
. Call it by the misc/mgettext/index.php3
script. Have a look on particular settings in the script. You need to provide
read-write access for PHP to language files in order to update them. Copy
them into another directory (I used ../php_rw/lang
, i.e. not
a subdir of the AA installation), set permissions, run xmgettext
and copy the updated files back. A side remark: If you don't like this
overhead, just remember which overhead it took to create and copy all the
L_ language constants to new_news_lang.php3 ...
One more thing to take care of is the run-time switching between languages.
If you fill in some include file a global variable with translated strings
and than change language, it will remain in the old language. You must create
a function returning the variable to avoid this.
Hope you will like my mgettext solution,
Jakub
Michael wrote a perl script called 'remote',( in apc-aa/misc/remote/remote)
'remote' could be useful to groups running action-application
servers, by expanding the number of groups that will want to have slices. Imagine a nonprofit wants to start using the apps for their news page, but does not want to move their site to a webhost that has action applications installed.
Using 'remote', the organization's webmaster could:
1. Ask a server with the action applications to setup a slice for them
2. Include the news items from their slice with 'remote', pulling these items into news.html, on their local webhost.
I think this could be especially true of larger organizations.
Note: If this script is not fast enough, consider using 'apc-aa/misc/remote/remotec', a version of 'remote' with caching, or misc/remote/remotec.php which is in php and should be even faster.
What is a module?
-----------------
You probably know slices - a part of database with its admin interface
which is able to manipulate with items/articles. The slices are very
configurable, so it can hold news or events as well as database of
links, organizations or members. Slices are great for presenting tabular
data of any type. On the oher hand, there are many cases, where we need
comletely different data structure, behavior of admin interface or
presentation layer. As example we could mention polls, petitions, ...
Because users of AA (including us) wants to manage such data in the same
(ActionApps) environment, we have to find the way, how to incorporate
such data administration into AA. The answer is modules.
It's hard to explain what modules are and how you can create it, because
the is no good example of working module, rihgt now. In fact, there are
two modules - module 'jump' and module 'site'. The Jump module is too
easy (it allows you just to jump to specified page of specified slice in
admin interface) and the site module is too complex and it is not fully
integrated into AA. That's why it is not commited into CVS at this moment.
What the module allows
----------------------
- allows you to create different admin interface for the module data
(You can replace Item Manager and Slice Admin by your own admin pages,
including left menu bar, ...
- allows you to use your own database tables
- allows you to use your own permissions in new module (there is general
permission system with standardized perm API defined, which provides
abstract layer for functions like AddPermObject, AddPermUser,... -
such functions then operates in backroud with LDAP, SQL, ...)
How modules apears to user in AA admin interface
------------------------------------------------
All modules which belogns to logged user are listed in 'Module
selectbox' which you uses for selection of slices, right now (well known
'Switch to' selectbox). The idea is, that in this selectbox then user
switch to administration of news of site XY, to administration of events
of site XY, and to administration of polls for this site. In fact the
slices now became just one of the modules incorporated into AA environment.
When user selects another module type in Module selectbox, then upper
navigation bar will be changed just slightly. User will see probably no
'Item Manager' as well as 'Slice Admin' menu options. (S)he will see
'Poll Manager' and 'Poll Admin', or maybe just Poll Manager (if we speak
about poll module as example).
How to create new module in APC Action Apps
-------------------------------------------
Basic steps, which is needed for module creation are:
1) copy the modules/module_TEMPLATE to the new directory and name it by
the name of module (just for clarity) (modules/poll for example).
2) open /include/constants.php3 and add new module in the $MODULES
array.
3) create database tables for the module and add the definition to
doc/aadb.sql and sql_update.php3
4) modify modedit.php3 script in your module directory - this script is
called after 'Add xy module' is pressed so there should be basic
module settings/creation options (as we already know from 'Slice
Admin' - slicedit.php3).
5) modify index.php3 script, which is the script, which apears after
user selects the module from 'Module selectbox' (for 'slice' module
such page is Item Manager.
6) insert new language file for the module to include/ directory (just
like en_poll_lang.php3), if you want to use module specific texts
(you probably will) (Note: all language files must be in include/
directory)
Done - module is created.
Before we go to detailed description of the steps, we have to mention
some facts, which maight be confusing.
I say, that slices are just on of the modules. That's true, but from
historical reasons there are some differences:
- the code for slice is not placed in module/ directory - it is placed
in admin/ and include/ directory instead
- name of slice configuration file is not modedit.php3, but it is
called slicedit.php3
- the id of the slice is hold in $slice_id variable. Better name for
this variable is module_id (as we use it in other modules). For now
just note, that the module_id is exactly the same as slice_id.
Let's describe the module creation steps in more detail (I will use (non
existant) 'poll' module as an example. Substitute all 'poll' words with
the name of your module, of course):
ad 1) copy module_TEMPLATE
--------------------------
In module_TEMPLATE directory are templates for all interesting scripts,
which we need for new module. So, create new directory (modules/poll/)
and copy there all files from modules/module_TEMPLATE. As steted abobe,
name of the new directory sholud be the same as the name of module.
ad 2) add module to constants.php3
----------------------------------
The only cyhange, which is need in constants.php3 script is to add new
record into $MODULES array. The array looks like:
$MODULES=array('S'=>array('name' => 'slice',
'directory' => AA_INSTAL_URL ."admin/",
'table' => 'slice',
'hide_create_module' => 1),
'W'=>array('name' => 'Site',
'directory' => AA_INSTAL_URL ."modules/site/",
'table' => 'site'),
'A'=>array('name' => 'MySQL Auth',
'directory'=>AA_INSTAL_URL ."modules/mysql_auth/"),
'table' => 'module',
'hide_create_module' => 1),
'J'=>array('name' => 'Jump inside AA control panel',
'directory' => AA_INSTAL_URL ."modules/jump/",
'table' => 'jump'));
There we see listed four modules in the example above. Each module is
identified by a letter. Let's choice any unused letter for new module -
we choose letter 'P' for poll module for example.
There are four values for each module:
- name - just a name of module as will be listed on 'Add module' page,
for example.
- directory - the name of directory, where index.php3 for this module is
stored (index.php3 script is the one, which will be
executed after user selects the module instance from
'Module selectbox' in admin interface). It is good idea to
specify the directory using AA_INSTAL_URL constant
- table - table parameter is just optional. You can specify main
database table of the module, so then you can call
GetModuleInfo() function in order to fill an info_array by
the values specific for selected module:
$poll_info = GetModuleInfo($module_id,'P');
Now you can access $poll_info['number_of_options'],
$poll_info['title'], ... when 'number_of_options' and 'title'
are fields of poll table.
- hide_create_module - set this optional option to true, if you want to
not show the module on 'Add module' page. This
option will be false for most modules.
The record to the $MODULES array for poll module could looks like:
'P' => array( 'name' => 'Poll',
'directory' => AA_INSTAL_URL ."modules/poll/",
'table' => 'poll'),
ad 3) create tables
-------------------
You will probably need the database table(s) for your module. Create it
in database and the table definition add to both:
a) doc/aadb.sql (used for new creation of new databases)
b) sql_updata.php3 script (used for database upgrades)
For clarity, prefix the new table names by the name of module (just like
table poll, poll_options or poll_votes)
ad 4) modify modedit.php3
-------------------------
modedit.php3 is the script, which is called when user on 'Add module'
page click on 'Add' for your module.
This script is used to create and modify module instance. There user
should set all main configuration options. To create such instance you
need to:
a) add a record into 'module' table (and maybe to module specific
table, just like 'poll', ...)
b) assign permissions for the module
ad a) add record into 'module' table
Module table is generalized version of slice table any module
instance (including slices) must have its recocord in module table.
The table have the following fields:
id char(16) NOT NULL,
# world wide unique module instance id. There we store packed
version of 32-digit hexadecimal number (you probably already
know
it from slices and its displaying
(<!--#include
virtual="/apc-aa/slice.php3?slice_id=763511f38a9b960c8e7a99f765e89ff9"
-->)).
The id is there stored packed to 16 characters long string by the
q_pack_id($module_id) function. If you are creating new module
instance, the new module_id should be generated by new_id() (both
functions in /include/util.php3 file). This id is foreign key for
module specific tables (such as poll table), where more
information in the instance is stored.
name char(100) NOT NULL,
# name to be displayed in 'Module selectbox' in admin interface
(Switch to:). From historical reasons it duplicates slice.name
for modules of 'slice' ('S') type
deleted smallint(5),
# boolean value to mark deleted modules. For new module you will
set it to '0'. From historical reasons it duplicates
slice.deleted for modules of 'slice' ('S') type
type char(16),
# module type - 'S' for slice, 'P' for polls (see already described
$MODULES variable in /include/constants.php3)
slice_url varchar(255),
# URL where user could view the module instance, if it is possible
for your module type. This is the url where user jumps after
(s)he click on 'View' in upper navigation bar in admin interface.
lang_file varchar(50),
# used language file for this module instance. Language files are
located in include directory (en_poll_lang.php3,
cz_poll_lang.php3) and they are described in paragraph 6)
created_at bigint(20),
# timestemp of module instance creation. We use unix timestamps -
use include/util.php3 funtion now(). This field should not be
user editable.
created_by varchar(255),
# user id of logged user. The id could be number (if you are using
SQL based permissons) or string like 'uid=honza,ou=People,ou=AA'
(if you are using LDAP permission system. In both cases you will
get such number in $auth->auth["uid"] object variable.
owner varchar(16),
# owner is the link (foreign key) to 'owner' database table
flag int(11) default '0'
# just a module flag. Not used yet. Fill it by '0'.
ad b) assign permissions for the module
The permission to the new instance will use the same functions as the
slice
- it will use AddPermObject($module_id, "slice"). The "slice" is
there from historical reasons and in fact much better name would
be "module", but we MUST use the "slice". Do NOT use any other
string then 'slice'!!!
- Note: you can (and in fact you should) redefine the meaning of
permission letters in permission string for the module (see
/include/perm_core.php3)
- If you want to assign some permissions to specified user, use
AddPerm($user_id, $module_id, 'slice', $perm), where $user_id is
the id described in section a) by the created_by field (see
above) and $perm is the permission letter(s) we mentioned in
'Note' above.
- If you do not assign any permission to any user, only superadmins
of AA will see the module instance in his 'Module selectbox' and
will be able to change it.
The admin interface of modedit.php3 should be inspired by the interface
of 'Slice Admin' (slicedit.php3). There should be upper navigation bar
(which could be slightly modified to better fit your module - see
navbar.php3) and possibly left navigation menu, if you need to split the
module configuration to more than one page.
ad 5) modify index.php3
-----------------------
index.php3 is the script, which apears after user selects the module
from 'Module selectbox'. The admin interface should be inspired by 'Item
Manager' for slice module. This is the main administration page for the
module - most users will probably have the permission to access this
page and only a few administrators will have the permission to access
configuration page - modedit.php3.
ad 6) create language file
--------------------------
Create the language file, where you will store all texts you use in
module. The language file should be named like en_poll_lang.php3,
cz_poll_lang.php3, ... (<language>_<module>_lang.php3). The language
file MUST be stored in include/ directory (just like all other language
files). The name of this file is filled in module.lang_file table field
as described in section 4).
In the language you can define as many language constants as you want,
but you MUST there define the LANG_FILE constant, where you fill the
name of language file:
define("LANG_FILE", "en_poll_lang.php3");
All others language constants are up to you.
Notes:
------
- You can create any file in your module directory, of course. If you
will use functions, prefix its name by Mod<module letter>_, so use
ModP_GetName(), ModP_Display(), ... functions, for example.
- It is good Idea to consult the features of new module on
apc-aa-general mailinglist, before you will start the
programming.
- Please, commit all created modules to CVS (ask us for write
permissions) or send the code to AA administrator.
- Write documentation for the module in order others would be able to
use it.
You can find a description of each Field Type and of each Alias Function in the Admin Interface (Slice Admin / Fields / Edit) by clicking on the Param Wizard link at the left of the select box.
A complete list of all
Field Types and Alias Functions is now available as well.
Using mod_auth_mysql and .htaccess, http authentication can be configured to make use of the ActionApps user database.
This involves:
1. Installing mod_auth_mysql
2. Configuring .htaccess to use ActionApps user database for authentication.
Installing mod_auth_mysql
~~~~~~~~~~~~~~~~~~
(The following method works only for apache with mod_so installed)
1) Download mod_auth_mysql module from http://telia.dl.sourceforge.net/sourceforge/mod-auth-mysql/mod_auth_mysql-3.2.tar.gz ( say in /usr/local/src)
(URL for the project site: http://sourceforge.net/projects/mod-auth-mysql)
2) untar the module ( tar -zxvf mod_auth_mysql-3.2.tar.gz)
3) cd /usr/local/src/mod_auth_mysql-3.2
4) Edit the Makefile to suit your requirement. Edit the APXS and OPTS values. Sample Makefile is provided here:
------------------ Sample Makefile -----------------------------
APXS = /usr/local/apache/bin/apxs # Location of apxs binary
APXSFLAGS =
DSO = mod_auth_mysql.so
SRCS = mod_auth_mysql.c
HDRS = mod_auth_mysql.h
OPTS = -I/usr/include/mysql -L/usr/lib/mysql -lmysqlclient
all: $(DSO)
$(DSO): $(SRCS) $(HDRS)
$(APXS) $(APXSFLAGS) -o $(DSO) $(OPTS) -c $(SRCS)
install: $(DSO)
$(APXS) $(APXSFLAGS) $(NAME) -i -A $(DSO)
clean:
-rm -f *.o $(DSO)
---------------------------------------------------------------
5) run make;make install
6) mod_auth_mysql has been installed now. If successfully installed, httpd.conf will now contain the following line:
LoadModule auth_mysql_module libexec/mod_auth_mysql.so
Configuring mod_auth_mysql to work with APC-AA authentication system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Let the APC-AA DB be aadb
aadb has the table, users with the fields uid, password
now, in your httpd.conf , and in your virtualhost configuration, add the following:
Auth_MySQL_Info myhostname aadbuser aadbpassword
where: myhostname is the host where your aadb database is running
aadbuser is the valid username to access the database
aadbpassword is the valid password to access to access the db.
now, create the .htaccess file, with the following:
Auth_MYSQL on
Auth_MySQL_DB aadb
AuthName "APC-AA Secret Area"
AuthType Basic
Auth_MySQL_Password_Table users
Auth_MySQL_Username_Field uid
Auth_MySQL_Password_Field password
Auth_MySQL_Encryption_Types Plaintext Crypt_DES MySQL
order deny,allow
allow from all
require valid-user
Now, when you try visiting this location in your browser, it should prompt you for the uid/password. Provide you apc-aa uid/password to log in.
Note: Currently, this configuration does not take the group into consideration when authentication. This will be done in the next phase.
The coding standards are documented in doc/coding.html
We are moving to use phpDoc, the manual for this is at
http://phpdoc.org/docs/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html, its pretty comprehensive, and there is a need for a brief version that shows how we use it - any volunteers!
Here are some hints on debugging APC-AA,
<ol>
<li>Run the same query appending: ?errcheck=1&nocache=1<br>errcheck=1 will activate checks in a few places to make sure assumptions the code is making are valid. Sometimes this helps. It also occasional generates false warnings, especially about trying to pack invalid ids.
<br>nocache=1 will make sure that fresh data is generated rather than old stuff from the cache.
<li>Add: &debug=1
<br>This will cause lots of debugging info to be reported, if the problem is with {...} expansion look for lines starting Unaliasing, Expanding, Expanded and Continuing
<li>If the problem is timeouts, add: &debugtimes=1&time_limit=1000
<br>time-limit will extend the time in view.php3, (but not elsewhere yet)
<br>debugtimes will make every debug line report at what timestamp it was run, this will help narrow the problem down.
<br>(Note: There *have* been problems with regular expressions and long strings - suspect "ereg" and replace with preg_match.)
<li>If none of this helps, Post the url to apc-aa-coders@sourceforge.net (or apc-aa-general@sourceforge.net if you aren't on apc-aa-coders)
</ol>
Unfortunately , I haven't been able to track down any kind of symbolic debugger for PHP, so it doesn't appear to be possible to do the usual ways of debugging code ....
A work-around allowing to use the POST method for sending form data to a .shtml page is in the post2shtml.php3 file. See the comments in this file.
With the concept of Reader management slices introduced it is important that
some data are not accessible for reading. This is achieved by setting a reading
password for slices containing sensitive data. If you fill the field "Reading
Password" in Slice Settings, you must always sent this password as a
parameter slice_pwd
. This may be done by adding this parameter
to SSI includes like
<!--#include virtual="/aa/slice.php3?slice_pwd=the_password&slice_id=xy...."-->
If somebody tries to fetch read-protected data without the correct password, all fields are filled with an error message.
If you are interested, the password is prooved in the GetItemContent() function. For AA control panel pages (Item Manager and Item Edit), the function FetchSliceReadingPassword() is used.
In AA v2.6 or current CVS is introduced Reader Management slice and Auth Module. Users for Auth are stored in slice and each user is in fact slice item. So, you can create standard anonymous posting form into the "Reader manager" slice to allow user subscribtions.
You can set the form to put new users (=items) to holding bin, so they have to wait for your approval - just like in normal slice.
There is no possibility (at this moment), how to add common Authors or Editors to AA permission system from public webform.
This is a common request, and unneccessarily complicated, (suggestion to developers - create a function like f_b might be created at some point to do this more easily, or just add an "Else" field to f_b)
- 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 concept of Tagged IDS is simple - when we store an id in a field, we sometimes want to say something about it. the idea came from the directional/bidirectional links which in fact are not stored like that, but are used internally to store one or two uni-directional links.
A tagged id consists of some string followed by 24-32 hex digits. (It should be 32, but there are some buggy shorter ids due to old bugs in apc-aa). Typically the string will be a single letter g-zA-Z or a punctuation character.
Tagged id's may not be supported everywhere yet. They are supported ....
In zids.php3, which means that most other places in the code can trivially support them transparently.
In the Slice Admin -> Fields you can set a field to Relational Window, and then use hte parameter wizzard to set which buttons to use (a set of letters matching the values of the tag), then add an extra parameter (not yet supported by the wizzard) that refers to a table.
The table is in the $tps array, defined in itemfunc.php3, if you want to use anything other than the two standard ones "AMB" (Add, Mutual, Backwards) and GYR (Good, OK, Bad) then you need to somewhere in your code do something lke
$GLOBALS[tps][MyTable] => array (
G => array ( prefix => 'Good:', tag => 'x', str => _m("Good") ),
Y => array ( prefix => 'OK :', tag => 'y', str => _m("OK") ),
R => array ( prefix => 'Bad :', tag => 'z', str => _m("Bad") ));
In the Relational window, if you have specified a table, then it will be shown as buttons - just the ones picked in the second parameter.
THIS USED TO WORK, BUT SOME CHANGE TO THE CODE BY SOMEONE ELSE HAS BROKEN IT,, AND I DON'T HAVE TIME TO FIX IT.
Note that the "tag" from this field is what is stored.
You can then use this tagged field in many ways, for example it can form part of a search string, to look for only "Good" links, or you could use a switch statement to figure out how to use it.
You should NEVER have to write code in your site to strip the tag away from the value, for example if you pass a tagged id to e.g.
view.php3?vid=123&cmd[123]=x-123-z1234567890abcdef1234567890abcdef
then view.php3 SHOULD understand this correctly as refering to item 1234567890abcdef1234567890abcdef
A new pseudo-field is created idtag........... contains the tag anywhere that GetItemContent is used to get the fields (i.e. should be everywhere). So you can put {switch({idtag...........})x:GOOD} into your code.
The File Manager enables Slice Administrators to modify their web pages on-line
in the AA Control Panel. It appears only when an superadmin sets so in Slice
Settings. The File Manager settings are hidden to anybody except superadmins.
See File Manager Administration for more details.
Most of the features of the File Manager are very common:
- 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
It is relatively straightforward to modify RSS import as the standards mutate
- 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
f_v takes a parameter on which certain substitution is done.
- _#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 |