APC Actionapps Administrator Training Workshop

APC ActionApps Administrator Training Workshop

Developed by

Anna Feldman, GreenNet

On behalf of the Association for Progressive Communications

March 2002

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Workshop Trainers’ Notes

Database Driven Web sites - The Planning Session...... 3 What is a database Driven Web Publishing System?...... 3 Understanding Databases...... 3 What is ActionApps (not) Relevant for? Taking Automation Seriously...... 4 Re-crafting content for the web...... 5 Understanding Access Issues...... 5 Dividing the Pie into Slices...... 7 Action Apps - The Hands on Session...... 7 Configuring your slice of the database...... 7 Creating a New field...... 9 Editing a Field...... 9 Creating the web page for content to appear on - The shtml page...... 12 Customising the way that content will appear on the web page...... 13 Designing the Index View...... 13 Designing the Fulltext View...... 16 Managing the content in the database...... 17 Assigning permissions...... 17 Adding Content to the Database...... 18 Editing Content in the Database...... 18 Glossary...... 20

This duration of this workshop is estimated at 6 hours, broken down as follows: Section 1 (120 minutes): 30 minutes narrative, 90 minutes group exercises Section 2 (240 minutes): 30 minutes narrative, 210 minutes group exercises Each exercise has been individually annotated with its estimated duration.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Database Driven Web sites - The Planning Session 120 minutes

When we think about the design priorities in web site development projects, we need to consider ways that make content:  As accessible as possible for users  As readable as possible for readers  As up-datable as possible for content authors and editors

This workshop will look at using a database driven publishing tool called APC ActionApps to meet these demands. Taking the decision to use a tool like this is not an automatic one. We need to understand how databases work and what automatic publishing really means. We can then look at our site content to determine whether it can benefit from being powered by a database driven tool such as ActionApps. This takes us onto looking at how to use the tool most effectively not only to help us to publish content, but also to craft it at the point of authoring.

What is a database Driven Web Publishing System? ActionApps provide a structured space for information/web content storage – a database. ActionApps then work with the information stored in the database to automatically generate web pages according to a set of rules that the Administrator provides. These rules determine issues such as: how the content is formatted which pages the content appears on when the content gets retired to an archive how the content gets sorted on site indices

Understanding Databases A database is a storage space for content (data). When we build a database, we have in mind the types of data we will be working with, and so try to customise the database for the neatest organisation of our content. The principal storage units are fields. These will house the basic components of data that your content can be broken down into. Deciding which fields to create means thinking generically about your content, i.e. drawing out the common components of the documents that make up a section of the web site, and avoiding the specifics that distinguish one document from another.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Just as the content of any one document or item needs to be broken down into its constituent bits of data for storage in the fields, the link between them also needs to be available so that they can be re-constituted into their whole document form. Records allow us to do this. A simple table gives us the clearest picture of how records and fields work together in the database storage project.

Field a (date) Field b Field c (Headline) Field d (author) (body text) Record 1 1/3/2000 M. Lopez Rights and wrongs online Blah blah blah Record 2 3/5/2000 I. Odabayo Networking for change Rhubarb rhubarb Record 3 17/6/2000 J. Konko The myth of cyber crimes on and on and on

And this forms the basis of all databases

What is ActionApps (not) Relevant for? Taking Automation Seriously In deciding whether the content you are working with, can be successfully driven by a tool such as ActionApps, you need to consider what we now know about:  the ways that Action Apps works with content - automatically applying given publishing rules to the different fields of data  the ways that Databases rely on content being broken down into common data types for storage in the relevant fields The main theme here is rigid automation – we are looking at how effectively a machine can handle your content. Unlike a person, it cannot exercise judgement, so it needs you to be able to tell it exactly what publishing action to take with the data in each field. It will then apply those rules rigidly. This is: GREAT IF your documents are all made up of the same common data components that neatly slot into your pre-labelled fields NOT GREAT (A PROBLEM) IF your documents need to be handled on a case-by- case basis, with each one being composed of different types of data that must be formatted according to the judgement of a person who can understand the subtleties of that data.

Exercise with the group – 30 minutes Fill in the table below to determine which documents are likely to appear in web site sections that can be powered by a database-driven web publishing tool:

Which Is this likely to Can it be Can the data be Suitable for site be one in a broken down formatted by ActionApps? section? series of into generic pre-defined many? fields? rules? News story News Yes Yes Yes Yes Leading ‘About No Us’ piece Announcement to No users about change of address Job vacancy Yes Latest annual report Action Alert

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Re-crafting content for the web As an ActionApps Administrator, you are developing a system, which carries content from the person who has created it, automatically through the process, which leaves it as a perfectly formatted web page in the appropriate section of your site. This is primarily a technical task that will keep your site up to date and looking streamlined. However, if you can broaden your understanding of the job to include editorial as well as technical needs, you can go a long way towards improving the quality and readability of the documents processed by ActionApps as well. Research has shown us that users read online content differently from printed content. As a result documents which are simply copied and pasted from paper to web, fail to get read properly. But there are ways of structuring documents online that make them much easier to read and digest. Documents on the web benefit from components such as: - Chunking sections - A lead paragraph - A summary - Teasers - Kickers See Marion Walton’s research and findings on http://www.writing.uct.ac.za for an excellent explanation of these techniques. Whilst many web content gurus advocate dedicated web content editors as the only solution for a well written web site, this is not a viable option for small-scale, small budget, campaign centred organisations. Bu editorially intelligent use of ActionApps can go quite a long way to performing that role. By creating fields for document components such as lead paragraphs and chunked excerpts, you can powerfully guide and assist your content authors (those who write the content/paste it into the database) to re-shape it into a more web-appropriate form.

Understanding Access Issues Publishing content online involves a team of different skills: editorial, layout and design, technical – often performed by different people. The relationship between these people and the web site plays a large part in the success of the site itself. A site can seriously stumble over lack of clarity of roles and access to the site by its developers. ActionApps provides a structure for determining a clear division of labour amongst the development team. There are 4 distinct roles: Author – able to add content to the database Editor - Author + able to choose which content items can be published on the live web site, which should be removed, and which should be held back. Administrator - Author + Editor + able to configure given slices of the database, create publishing rules, and assign access permissions to existing users Superadmin – Author + Editor + Administrator + able to create new slices, and create new users Any given member of the team has their level of access determined by their password. Once they have gained access to the ActionApps control panels, they will only be able to do those tasks that they have permission to perform. It is important to think carefully about the process of who is going to be doing what to site content in getting it from its creator to the web page. A logical assignment of access permissions should leave you in no doubt about WHY each actor has a given role.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Exercise with the group – 40 minutes Discuss and fill in the table below to determine who should and should not have which sort of access to get the content online:

Content Possible players Author(s) Editor(s) Administrator(s) Weekly round-up -All office staff All office staff Director, Webmaster of staff activities -Director incl. Director possibly all WHY? on an office -Webmaster WHY? staff This slice’s settings intranet This content WHY? are unlikely to need needs to get In a small changing regularly. published organisatio Tinkering with the fast and n, staff are configuration of the accurately. probably slice can be Staff best placed restricted to the themselves to publish minimum players. are the best their people to content write what when it’s they are up ready. In a to bigger organisatio n, there may be a need to restrict who has access to publishing and editing this type of content. Action Alerts for -workers in network international offices world-wide monitoring -Int’l Action Alerts co- network ordinator WHY? WHY? WHY? -Network Director -Webmaster -General Public National events -Webmaster being staged -Campaigns worker around a -Campaigns worker’s campaign target assistant WHY? WHY? WHY? -General Public

‘Latest -Webmaster Publications’ -Publications worker index -Writers of Publications -all office staff WHY? WHY? WHY?

Weekly News -News team workers headlines -News team Director -Organisation Director -General Public WHY? WHY? WHY? -news workers in sister organisation offices

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Dividing the Pie into Slices The ActionApps database of content is conceived as a large pie of information, which is sub-divided into slices. Each section of a web site powered by ActionApps forms a ‘slice’ of this pie. Each slice is configured and customised to store information and generate pages according to the unique requirements of its web site section. And because each slice inhabits a larger ‘pie’ of content, it can assist in ‘content pooling’ – where a given web site section draws on the information being stored in several different slices. This feature has obvious benefits for any organisation wanting to generate an index of stories, which includes items distributed by other relevant organisations.

Action Apps - The Hands on Session 240 minutes

The planning that you have worked through in the first half of this training is a crucial starting point for any web development work using ActionApps. If your work is based on a logical continuous thread that runs through: - the types of content you will be publishing with ActionApps - the organisation of fields in the database - the assigning of permissions - the labelling of the slice you will find ActionApps Administration pain-free and satisfying! Developing ActionApps slices on a foundation of a well thought-through content strategy radically alters what your web projects can achieve. Goals such as up to date, readable content, which may once have seemed beyond your reach, become realisable. We are now ready to embark on the hands-on Administration. This will involve 4 distinct parts:  Configuring your slice of the database  Creating the web page for content to appear on  Customising the way that content will appear on the web page  Managing the content in the database

Configuring your slice of the database You enter the ActionApps control panels through a front door that looks like this

Your password behaves like a key that will unlock not just this front door, but also a selection of doors beyond. They will give you access to all the control panels

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ necessary for configuring a slice, previously created by someone with Superadmin permissions. These include: The Item Manager control panels The Add Item control panels The Admin control panels

We begin our work in the Admin Control Panel, with the slice settings. We will return to note some of these settings later on, but for now we are going to start work on creating and configuring the fields of this slice of the database. Access to the fields is given under the Main Settings heading in the left-hand menu-bar

Access to configure fields is given here

The fields screen lists pre-defined fields that come as part of the basic slice template. We will use this screen to edit or delete existing fields, and create new ones.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Option to edit or delete the field

This row gives the option to create a new field

An existing field comes complete with an id and priority number. The id is in part derived from the type of data that will be stored in the field. The priority number determines how the list of fields gets ordered.

Creating a New field The steps to creating a new field are as follows:  Enter the name of the new field in the empty box at the bottom of the screen.  Create an id by choosing from the pretty exhaustive list of data types in the drop- down menu.  Assign a priority number that reflects where the new field should be positioned in the list.  Click on the update button.

Editing a Field Having named your new field, it now needs to be configured for future use in the web publishing process. This process begins by editing the field in the Configure Fields control panel. Much of what you see on this very long screen can be ignored, but it does give you the opportunity to adjust settings which will affect the way that data can be entered into the field, and the way that data appears when outputted on a web page

In the first section:

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Use this drop-down menu to choose the input box type, for entering data into the field

Use this space if data in this field is selected from a list of constants. Choose from an existing list of constants or create a new one.

In the second section: Use this drop-down menu, to choose which data type should be treated as default in this field.

Use this space if you want some text to appear by default in the field

In the third section:

Use this section if you want the data to be validated as a particular type

Use this section to provide any text that will appear as a guide to the data author

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ In the fourth Section: Alias 1: We use aliases to represent the data in this field, when doing work such as customising the appearance of data on the outputted webpage. Aliases must always: -begin with _# -be in upper case -be 10 characters long

Any pre-defined fields, which come as part of the basic slice template, that we decide to keep, are configured with ready-useable settings, including an alias. It is unlikely that we will want to adjust them. However we will need to go through this ‘Configure Fields’ control panel very carefully for any new fields you create. Having configured each of our fields, we need to return to the full list of fields, to adjust the priority numbers so that the list is ordered correctly. Any changes will only be registered once we have clicked on the update button at the bottom of the screen. We can now go through the list to adjust the settings in the Required and Show columns. For each field there is the option to make it: Required: If this box is ticked the field must be filled with data or the database will not accept the record. If it is not ticked, the field can be left empty. Shown: If this box is ticked the data-entry screen (used by authors to add records to the database) will show a space for this data to be added. If it is not ticked, the author will not be aware of adding data to this field. The data may get automatically generated - e.g. with today’s date.

Exercise – 60 minutes 1. Go through the list of existing fields that come as part of the basic slice template, and remove the ones that you do not want (using the delete link). 2. Create new fields for all the data types that were not previously accommodated. 3. Ensure that the new fields have appropriate settings and aliases. 4. Change the priority numbers in the list of fields to reflect the order that you would like the fields to appear in, on the data-entry screen (confirming with the update button). 5. Check the tick boxes for each field in the Required and Show columns (confirming with the update button).

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Creating the web page for content to appear on - The shtml page For data to appear as useful, readable content on a web page, it doesn’t just need to be reconstituted into the document it was drawn from. It also needs to appear on a page, which is well laid out, clearly formatted, and graphically harmonised with the rest of the content on the web site. This process begins with the creation of a template page. This is rather like a picture frame – a page with static elements around the edge of a space that the data can be published into. Those static elements may include items such as: A menu bar A logo Contact details Border designs Designing a template page involves thinking about how these different elements relate to each other and what the most effective way of positioning them is. The space allocated for content published by the database also needs very careful consideration, to ensure that a workable balance is struck between all the elements.

Exercise - 60 minutes Make a list of all the different elements you want to include on your template page, including space for the content. On a blank web page, create a grid (table) with enough boxes for each of the elements. Assign each element to a box in the grid and adjust the sizes of the boxes appropriately.

The finished template page is made ready for use for ActionApps, by adding the crucial slice code. This appears on the Admin – Slice Settings control Panel

This is the crucial coding that MUST be included in your template page for Action Apps to publish content there. It must be copied in its entirety (including the <--!-->s) into the appropriate space on the page

Enter the Complete URL (beginning with http:// and ending with your file and shtml file extension) into this box.

The template page can now be saved for use with ActionApps by giving it a name with a .shtml file extension. It must then be ftp-ed to an appropriate place on the web server. The local systems operator/superadmin person must supply these details. With this information you can now enter the full URL of your shtml page in the box on the Admin – Slice Settings control Panel.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Customising the way that content will appear on the web page Once the template shtml page is in place on the server and ready for content from the database, you can begin setting the rules for formatting the data on the shtml page. Data can be outputted on the shtml page as An Index view: a list of content items (documents) A Fulltext View: a single complete item (document) You will need to set formatting rules for both views. Each item listed in the Index View acts as a link to its fulltext version The Index View Control Panel provides the space for you to compose the html coding which will format the data that appears in the list of content items.

Designing the Index View Access to the Index View is given under the Design heading in the left-hand menu-bar of the Admin Control Panels

Access to customise the Index View is given here

The Index View screen is a control panel for you to set the html coding for the space/section of the table on the template (shtml) page, which is allocated for database content to appear in. The coding you enter will be used to publish data in a list format. The control panel requires you to divide your coding into the following sections: Top HTML Even Rows Odd Rows Bottom HTML

Each content item published in the list on the shtml page will be wrapped in the coding you stipulate for the odd rows. In addition the list itself will be wrapped in the coding you stipulate for the top and bottom html. It is only necessary to give coding for even 13

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ rows, if you wish even and odd rows to alternate with different formatting such as colour.

The first section of the Design Index view control panel:

The html coding used in this example shows how the data in the headline field should be formatted in each row. The headline itself is represented by the field’s alias: _#HEADLINE.

This headline will be published as a link to the fulltext, by wrapping it in coding that has the alias for Headline URL (_#HEADURL1) as the a href.

The second section of the Design Index view control panel:

Tick this box if you want to apply different formatting to alternate rows of your list of content items

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ The third section of the Design Index view control panel: If you have configured any of your fields as a list of category constants, then you can use them to subdivide your list of content items.

Tick this box to sort the items by category and the remaining boxes to code the formatting of the headings.

In the final section of the Design Index view control panel there is a list of all the fields contained within the slice you are working on. It appears in 3 columns: The first is the alias for each field. You can copy and paste any alias from this column, for use in the html coding boxes above.

The second is a description of the field taken from the help text entered in the Configure Fields control panel.

The third is a link to edit that field in the Configure Fields control panel.

Any work done in any area of the Index view screen must be confirmed by clicking on the Update button before leaving the control panel.

Exercise – 30 minutes Using the list at the bottom of the Index view control panel, copy and paste aliases of all those fields that you want to include in your list of content items, into the ODD ROWS box at the top of the control panel Add html coding to those aliases, so that the data will be formatted appropriately Complete the formatting by entering code into the TOP and BOTTOM HTML boxes

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Designing the Fulltext View The Fulltext View control panel allows you to code the formatting of content published as a complete document. Users of the web site will see content in this format when they click on an item listed in the Index of content items. Work on this view proceeds in a very similar pattern to the Index View.

Access is given under the design heading in the left-hand menu-bar of the Admin Control Panels

Once again it is necessary to make reference to the list of aliases at the bottom of the screen to incorporate all the different fields into the fulltext view.

Exercise – 30 minutes 1. Using the list at the bottom of the Fulltext view control panel, copy and paste aliases of all those fields that you would like to include in the presentation of whole documents, in the Fulltext code box at the top of the control panel 2. Add the coding which will format the data in those fields appropriately. 3. Complete the formatting by entering code into the TOP and BOTTOM HTML boxes. 4. Save and confirm your work, by clicking on the update button at the bottom of the screen.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Managing the content in the database The stage is now set for ActionApps to drive content from the database to the web site. All we need is the data content to get to work with, and an understanding of how to handle it once it is in the database.

Assigning permissions Given that this data may well exist beyond your reach, it is necessary to look at assigning permissions to other users to take on tasks such as data entry and data editing. Access to the Assign Permissions control Panel is under the Permissions heading in the left-hand menu-bar of the Admin control panels.

Access is given under the permissions heading

Enter the login name of any user you wish to assign permissions to in the Users box in The Permissions Control panel.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Click on search to see how their permission status currently stands:

Click on the level of permissions you wish to assign to the user. On entering ActionApps, their login and password will then grant them the appropriate levels of access. If, on conducting a User search, you fail to find the user listed that you wish to assign permissions to, you need to approach a Superadmin user to create a new user profile.

Adding Content to the Database All users with Author, Editor, and Administrator levels of access have permission to add content to the database. This is done using the Add Item Control Panel, accessible from the links at the top of the screen.

This will take you to the input form for entering the new item's data. The Add Item screen reflects the way that fields have been configured: - which fields exist for that slice - what entry format (text box, radio buttons, select box etc…) have been configured for each field - how the fields are ordered using the priority numbering Once a complete record has been entered, it is submitted by clicking on the Post button at the bottom of the screen.

Editing Content in the Database Editors and Administrators also have access to the Item Manager control Panel.

It displays a list of items (records) that are active – currently published on the web site. In the left-hand menu-bar there is a list of totals of items in folders whose status is: - Active: Items currently live on the web site - Pending: Items not yet published (embargoed until a given future date) - Expired: Items passed their expiry date – may be published in an archive

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ - In the Hold Bin: Items awaiting approval by an editor before publication - In the Trash Bin: Items deleted (but retrievable) from the database

Items can be moved between these folders by ticking the item you wish to move and then choosing its new folder from the drop down menu beneath the list. The content of the items themselves can always be edited by clicking on the item in the list on the Item Manager control panel. This gives you access to the record in the Edit Item screen. Any changes made in this way must always be confirmed by clicking on the post button at the bottom of the screen.

To view the items as they look in the site, choose the 'view site' link at the top of the screen.

Exercise – 30 minutes 1. Using the Add Item control panel, add some data to your slice of the database 2. If the input boxes are inadequately formatted or wrongly ordered, return to the configure fields control panel and make the necessary adjustments 3. After adding a number of records, choose view site and check your work for errors. 4. Return to the Item manager control panel and make any necessary adjustments.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Glossary The glossary below is made up of the terms, which are specific to ActionApps administration, printed in red throughout this manual. The definitions refer only to the way these terms are used in the ActionApps environment.

Active Content items that are currently published (live) on the web site. Add item Putting content into the web site, also known as data entry. Admin The set of ActionApps control panels which allow Administrators to configure a given slice of the database Administrator User who has permission to access the Admin control panels and configure a given slice of the database Alias Represents the data in a field, for use in customising the appearance of data on the outputted web page. Author User who has permission to access the Add Item control panel and enter data into the database Configure fields The control panel which enables Administrators to adjust the settings for fields in the database – what data will be stored, what data-entry box to use, how the data should be handled etc… Control panels The interactive screens that users work with when configuring slices of the database and managing the data that is stored. Create new user The process of adding a new user who can be assigned permissions for varying levels of access to the database. Only Supreadmin users can create new users. Database A space for storing content that is based on breaking content down into components that will fit into a tabular format of fields and records Design The control panels used for stipulating the html coding that will format the data when it is published on the web site. Edit Adjusting settings or content items that are already created. Editor User who has permission to access the Add Item and Item Manager control panels, i.e. can enter data into the database and choose which content items can be published on the live web site, which should be removed, and which should be held back. Fields The principal storage units of the database, used to store the basic components of data that your content can be broken down into. Fulltext view The way that a content item is displayed on the web site when it appears as a single, full, document (as opposed to an item in a list). Index view The way that content is displayed on the web site when it is given as several items in a list. Item A record in the database, usually a document e.g. a news story, a publication, an action alert Item manager The control panel which gives Editors and Administrators access to Items for editing, publishing, expiring, deleting etc… Main settings The group of Admin control panels that allow Administrators to configure a given slice of the database 20

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/ Records An item (usually a document), forming a line in the database, composed of the data that has been entered into each of the fields for a given slice. Shtml The file extension used for any template page that Action Apps will publish data into. Slice code The line of code given in the Slice Settings control panel, which must be entered into the appropriate part of a template page as the signal for which content gets published on which part of the page. Slice Section of the database configured for a section of a web site. Superadmin User who has access to all control panels including those for creating new slices, and creating new users.

APC Strategic Use and Capacity Building Projects APC.org - The International Internet Community for Environment, Human Rights, Development and Peace http://www.itrainonline.org/