Input Forms
Contents
Introduction
The APC ActionApps enable your organization to publish information easily and quickly online. The type of information is up to you. You can create for example:
- short news releases
- bibliography of books related to human rights abuses
- directory of environmental lawyers
To give you the flexibility you need to deal with many different types of information, the ActionApps let you define the fields that an item will have within your slice. For example, to gather and publish news releases, the fields you need are the title of the news release, the author, and the full text of the story. For a bibliography, the set of required fields is different and would certainly include the date of publication and the publisher.
What is input form
Input form is an online form which ActionApps users use to manually add data into a slice. You, as a developer of ActionApps based website, are responsible for making the form user friendly and intuitive. Any input forms a collection (or sequence) of input elements, which correspond to slice Fields. You know HTML, so you know what online forms are (the ones you do using the <form> tag). You also know what input elements are (the ones you do using the <input> tag). And, you also know that there are various types of input elements, like textarea, select box, simple text box. ActionApps can generate any of those, plus many more.
How to Set Up Fields
In Slice Admin control panel, you control the fields that appear in the Add Item form for your news slice. For example, your slice might have only a minimal set of fields, like:
- Title: The name of the content item
- Fulltext: The complete text of the content item
- Status: The status of the item in your organization's publishing process, e.g. Active, Approved, Published
- Author: The name of the person who wrote the content item
Not all fields must be visible as input field in Add item form. You can have for example "Post date" field, which is populated automatically by ActionApps. The control panel will initially show a default list of fields according to slice, which was used as template for new slice.
Field properties
The fields control panel is set up as a table. Each field appears in a separate row, and you can set attributes for five properties of each field. The column headings that control these properties are:
To the far right, you will also see Edit and Delete in each row.
Field Attribute
Field specifies the field name. The Authors and Editors adding content to your slice will see this field name in the input form. You can use any text here, including spaces, numbers, letters, and punctuation. This field has a maximum character length of 255, but the best practice is to use 30 or fewer characters.
Type Attribute
Type specifies what type of information that field will contain. If you add a new field, a drop-down list displays the available, predefined types. Choosing a field Type sets the basic properties of your field, and then you can edit those field properties.
When you add a new field, you set its properties, which specifies almost everything about the field. For example, you determine how an author will enter data for the field: by typing into a text-input field, or by clicking the yes or no checkbox. Some fields will check to make sure input is a correctly formed email address or from a pre-defined list. There are properties to set how a field can be displayed in the Index or Fulltext view.
There are many available field types, each based on a commonly used function. When you are adding a field, simply pick a field Type that seems similar to the field you want to create. Most field types are the same: the field input is into a one-line regular text input box, it accepts any text, and it will output by printing the value of the field. If you create a new field and it should be like this standard field types, simply choose the 'headline' Type.
Special types
These are some of the non-standard Types available include:
- Abstract. The form displays an 8-row text area; accepts any text (including numbers, symbols, etc).
- Fulltext. Acts like “Abstract"
- External Item. Displays a yes/no checkbox.
- Headline URL. Displays a regular text input box; output is formatted as a link. Displayed only if External Item field is set to Yes.
- Source URL. Displays a regular text input box. Output is formatted as a link. If left blank, ActionApps will default to generate a JavaScript popup box in the Web browser that says “No source URL specified".
- Language Code. Displays a drop-down select box, choosing from a pre-defined list of languages.
- Code Page. Displays a drop-down select box, choosing from a pre-defined list of language code-pages. Code pages define which language character set the articles are using.
- Category. Displays a drop-down select box, choosing from a pre-defined list of categories.
- Image URL. Displays a regular text input box; output is part of an <img> tag. If left blank, it removes the <img> tag, to avoid broken HTML.
Priority Attribute
Priority sets the order in which the fields are displayed in the Add Item page. The lower the priority number, the closer the item will be to the top of the page. If you want your new field to be at the top of the page, make its priority smaller than all other fields' priorities. If you want your new field to be at the bottom of the page, make its priority greater than all the other fields' priorities. If you want you new field to go between two fields, choose a number greater than one and smaller than the other. Fields can have the same priority; these will be displayed in the order they were added.
Tip! Set priority number in increments of 100. E.g. your first field has a priority of 100, your second field, 200, and so on. In this way, if you need to insert additional rows later, you will have a lot of flexibility in your structure.
Required Attribute
Required is a checkbox. If this is checked, then the user must complete this field on the Add Item page. If they leave the field blank, they will be told to complete it when they click the form's “OK" button.
Show Attribute
Show is a checkbox. If this is checked, the field will be visible in the form on the Add Item page. Some fields have defaults, so that you can make them required, but not display them. For example, post_date can be a required field for ActionApps, but it is not displayed. ActionApps logs when an item is posted, so it fills in this field automatically, and you do not need to show it on the Add Item page.
Edit and Delete actions
Edit and Delete. On the right side of each row of field attributes, there are two links: Edit and Delete.
The Edit link will bring up another page. This page lets you set almost everything about the field. See [#How to Edit a Field|How to Edit a Field] for more information.
The Delete link will delete the field, if possible. There are some fields that you cannot delete. If it is not possible to delete an item, then the “Delete" will not appear as a link. When it is possible to delete a field, you can click on the link and it will disappear.
Tip! Generally you should not delete unused fields. If you do not want to use a field, you can simply unselect Show and Required, which will effectively hide the field from your users. This will allow you the flexibility to change your mind later and use the field.
How to add a field
- Click Main Settings - Fields from the Administration page.
- Scroll to the bottom row of fields, where you will find a blank row.
- Type in the your custom Field Name.
- Select a Field Type.
- Set the Field Priority.
- Specify whether to make Required and whether to Show the field.
- Click Update. Your new field is now in the list of fields.
Note: Fields in this control panel are listed in their priority order. If you create a field and set a priority, it will no longer be at the bottom of the list; instead it will appear in its proper order according to its priority.
How to Edit a Field
Generally, when you add a new field, you need only to choose the correct field type for it to appear properly in the input form and be available in the templates of your full text view and the index view. If you need to customize a field, ActionApps has many advanced features that will display a field in special ways. You customize a field with the Edit Field function.
The Edit link will bring up a page that lets you set almost every aspect of the field.
Note: Only advanced administrators should edit field attributes. It is easy for non-programmers to be confused by all the options allowed in Edit Field Attributes.
The main sections to the Edit Field Attributes page are:
- Input type
- Default Value
- Other Attributes
- Aliases
Input Type
In this section, you set how this input field will look in the Add Item page.
The top select box lets you choose the input type, from a list of options. These include:
- Text Fields. The most common type of field. This is a long box, one row high, into which users can type a value.
- Text Area. Similar to Text Field, but it is longer than one column high. Used for inputting the paragraphs of information. Use the Parameters input to specify the number of rows.
- Date. Appears as a series of text boxes.
- Check boxes. On and Off clickable fields.
- File Upload. Allows the user to choose a file on their computer to upload (inserts a “browse…" button)
- Select Box. Displays a pre-defined list of values from which users can choose.
- Radio Buttons. Displays a pre-defined list of values from which users can choose.
If you use Select Box or Radio Button, you must input the list of possible values in the Constants section, which appears just below the Input Type select box. After you add these values, click Update. To return to the field you were editing, you must go back to Admin - Main Settings - Fields, click the Edit link for the field you were editing, and choose the new constant group.
Default
You can set the your slice to supply a default value for a field. This default value will display in the input form in the Add Item page. In this section, you set both the type of default value and the value itself.
Most default values are of type Text. For example, if the default value is of type the Text and the Parameter is “Middle East," then this field will have the default value of Middle East.
You can set other types of default values, including Now or Date. For example, you could have an Event Start Date field, and set the default value to Now, which will insert the current date. The Date field is similar to Now, but the Parameters allow you to set the value to a number of days from now.
Another default type is User Id. This looks up the User Id of the user logged into the administrative interface and sets the value accordingly.
Validate
You can specify that only certain data is valid for a particular field. If Validation is on, then the Add Item page will check the content, looking for data that fails the validate function. The criteria used to validate the data depends on the validate function.
If the validate function is Text, then anything typed in will be accepted. If the validate function is URL, then only correctly formatted URLs like “http://www.igc.org/" will be accepted, and text like “Website:www.igc.org" will be flagged as an error. E-mail accepts common e-mail format, such as “joe@gn.apc.org", and rejects inappropriate text. The Number validate function requires a number like 15 or 3333. Id is a system-validation function used to make sure the entered value is a user id within the ActionApps, and you can safely ignore it. Date will ensure the value is a valid date. Boolean will make sure the value is either “yes" or “no" (1 or 0), if a field requires one of these options, e.g. if a field requires a true or false response.
Insert
Insert defines how the value is stored in the database. Generally, you will use Text. Other options include: File will store an uploaded file; Now will insert the current time, no matter what the user sets, which can be used to track changes; Uid will insert the identity of the Current user, no matter what the user sets; and Boolean will store either 1 or 0, which can be for yes/no or true/false values.
Show 'HTML' / 'plain text' option
You can allow users to add data to your field in either plain text or as HTML. If you click the Show 'HTML' / 'plain text' option, then your users will see a checkbox that will let them choose whether their input should be considered HTML or plain text.
HTML coded as default
This sets the Show HTML/plain text checkbox default to HTML or defaults to plain text.
Help for this field
In Add Item, below each field is a little blurb of text that explains the field. You set the text that appears here. e.g., under the input box for a date, the help could say: “Please write your date in this way, dd-mm-yy eg 23-01-01".
More Help
In Add Item, there is an optional clickable '?' next to each field. If the user clicks on that '?', they will be taken to a page with more help on that item. In this setting, you define the URL of that page where the user can get more help on this field.
Note: Only activate this feature if you have help pages to link to.
Before HTML code
You can preface an Add Item field with some HTML. This section appears in its own table cell. Use this to add e.g. a title to a section in your form.
Feeding mode
~ToDo: Describe feeding mode settings
Setting Aliases
In this section of the Edit Field page, you define aliases that you can use when customizing the Design pages. You use aliases when customizing the Design - Index and Design - Fulltext pages. Where you place an alias, ActionApps will display the value of the field for that item.
Each alias, for technical reasons, must start with a _#. Each alias must be 10 characters long, uppercase letters. Examples of valid aliases are _#HEADLINE _#AUTHOR##.
Note: Keep your aliases intuitive. Make up the number of characters to 10 by adding # to the end of a shorter word eg . _#AUTHOR##
Function and Parameters
Functions are simply different ways of displaying the value of a field. For example, if the value of the field is “http://www.apc.org/", this can be displayed either directly as text on the screen, or as a clickable link. Some functions are flexible and require additional information in the Parameter section. For example, the Abstract function prints only a certain number of characters. The parameter sets the number of characters this function will print.
There are several Alias Functions you should understand.
- Print. The default function. This prints the value to the screen. There are no parameters to this function.
- Abstract: Prints the field. If there is a parameter, it sets how many characters to print.
- Edit Item:Shows a URL that will let youedit the item. Parameters not used here.
- Fulltext Link: Shows a URL that displays the full text of the item.There are no parameters to this function.
- Fulltext: Prints the field. If the field is marked as HTML, it will print it directly. If the field is text, it will convert it into simple HTML. There are no parameters to this function.
- Linked field: A function used with links. A typical link will have two parts: the URL and the label that the user sees. In ActionApps, you may want to have two fields used together to generate such HTML, one field contains the URL, and one field that contains the label eg where the label is descriptive, “News from APC" and the URL is the actual URL of the news section <http://www.apc.org/english/news/>.
- URL: Prints the field. If the field is empty, it will print the text of the parameter. A common parameter is javascript: window.alert('Please include a source URL')
- Date:Displays a date value. Dates can be displayed many different ways, however, such as DD/MM/YY or MM/DD/YYYY. The parameter defines how a date value is displayed. The date is formatted with the php date function, so programmers should refer to <http://www.php.net/manual/en/function.date.php>. The characters in Table 1 have special meaning in the Date parameter:
Table 1: Symbols and meanings for the Data parameter
| Symbol | Meaning | ||
| A | "am" or "pm" | ||
| A | "AM" or "PM" | ||
| D | day of the month, 2 digits with leading zeros; i.e. "01" to "31" | ||
| D | day of the week, textual, 3 letters; i.e. "Fri" | ||
| F | month, textual, long; i.e. "January" | ||
| J | day of the month without leading zeros; i.e. "1" to "31" | ||
| l (lowercase 'L') | day of the week, textual, long; i.e. "Friday" | ||
| M | month; i.e. "01" to "12" | ||
| M | month, textual, 3 letters; i.e. "Jan" | ||
| N | month without leading zeros; i.e. "1" to "12" | ||
| R | RFC 822 formatted date; i.e. "Thu, 21 Dec 2000 16:01:07 +0200" | ||
| S | English ordinal suffix, textual, 2 characters; i.e. "th", "nd" | ||
| T | Timezone setting of this machine; i.e. "MDT" | ||
| W | day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday) | ||
| Y | year, 4 digits; i.e. "1999" | ||
| Y | year, 2 digits; i.e. "99" | ||
| Z | day of the year; i.e. "0" to "365" |
- Image Height: Used to set the height of an image. When an Alias has the function, ActionApps makes sure that an empty value in this field does not lead to broken HTML. No parameters are used with this field.
- Image Src: An alias similar to image height. If the field is empty, the whole <img> tag will not be shown. No parameters are used with this field.
- ImageWidth: An alias similar to image_height. No parameters are used with this field.
- Id: An alias the system uses to print a database-id. No parameters are used with this field.
- None: This function will not print anything for this alias. No parameters are used with this field.
- Help Text: The help that appears to your slice's users in the list of aliases.
Types of input elements
~ToDo: List types of input elements
Using RichText Area
~ToDo: Write about RichText area
Using File/Image Uploads
How do I upload files into a slice
First, your System Administrator has to setup the apc-aa, see <a href="http://actionapps.org/aa/doc/install.html">below</a> 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 */* or image/jpeg (image/jpg doesn't works). 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.
FAQ: How to use images in a slice ?
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...
- Change input type to "File Upload"
- Edit the parameter to "image/*"
- Set Validate to "URL"
- Set Insert to "File"
4) Now, you can use the alias _#IMAGESRC like : <IMG SRC="_#IMAGESRC">
How can I manipulate images (e.g. create thumbnails)
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</li>
- filling of secondary image fields is not recursive (secondary image fields can not be defined in a chain)</li>
- there is no error reporting
FAQ: How does file upload work
All configuration options are in config.php3:
/** File uploads settings * The directory for file uploads should be webserver writeable and it * shouldn't be inside AA directory (for security reasons - PHP script upload) */
/** max size of file in file/picture uploading */ define("IMG_UPLOAD_MAX_SIZE", "400000");
/** url to image/file directory */ define("IMG_UPLOAD_URL", $AA_HTTP_DOMAIN."img_upload/");
/** path from server root to image/file directory */ define("IMG_UPLOAD_PATH", $AA_SITE_PATH."img_upload/");
/** mkdir perms - AA creates new directory for each slice in image/file upload * directory specified above. Each slice then have its own subdirectory. * Default is 774 */ define("IMG_UPLOAD_DIR_MODE", octdec('0774'));
/** perms for uploaded file. If not specified, the permissions are left, as * is after the upload (based on configuration of your server * Default is: commented out */ // define('IMG_UPLOAD_FILE_MODE', octdec('0664'));
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 in include/files.class.php3 file, called from include/itemfunc.php3 - function insert_fnc_fil().
FAQ: How to use images in a slice ?
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">
Making input forms more interactive using Java Script
Field Triggers
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 javascript/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 javascript/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><br>
</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.
Wonders of Live Checkboxes & co.
How to use Live checkbox (Auto Update Checkbox)?
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
