User:Milhaus/Webmasters Guide/Designing ActionApps Output

From ActionApps Documentation
Jump to: navigation, search

As described above, ActionApps let you control how your content appears on your organization's Web site. This involves two steps: First, you create a 'blank' .shtml file, then you customize the output from the Action Apps database. You can customize the output in the Design - Index View, Design - Fulltext View, Design - Views, and Design - Item Manager control panels.

Creating a Template File

ActionApps can be delivered one of two ways: directly from the database or via a Server Side Include (SSI) that calls your content into a customized .shtml file. Although it is simpler if you deliver content directly from the database, it does not provide much flexibility with formatting. Using the SSI gives you much more control over how your page looks because you use straightforward HTML to code everything except the dynamic content from ActionApps, so that the web page displaying the information from the database looks just like the rest of your site.

Most users will choose the SSI / .shtml approach. If you plan to use this approach, you must complete the following steps.

To create a template file:

  • Create an HTML template page with all of the normal elements from your Web site: your toolbar, logos, background colors, etc. Leave the area you want to fill with content from the database blank.
  • Find the SSI code that will be used to call your ActionApps content. You will find this at the bottom of the Item Manager page. It will look something like this: <!--#include virtual="/aa/slice.php3?slice_id=41415f436f72655f4669656c64732e2e"-->
  • Cut and paste this SSI code into the blank area of your HTML template page. The inclusion of this code will make the ActionApps content appear in the page.
  • Save the file with an .shtml extension and name it. For example, you might call you news page template news.shtml.
  • Upload your file to the server where the ActionApps software and your Website are located.

After you upload this file, an index of your content will be viewable. The URL for your ActionApps will be server name + directory path + .shtml file name. For example, APC's news slice is at <http://www.apc.org/english/news/index.shtml>.

Working with Aliases and Views

Once you have created a template file, you will then design the 'views' that will dynamically generated from the ActionApps. These views are simply the different formats that are used to present your content. For example, the 'Index View' is a list of the articles in your ActionApps slice. The Fulltext View is the format that is used to show an individual article from the ActionApps database.

Views combine HTML tags with ActionApps aliases in order to format your content. Aliases are simply text strings which represent a field in the database. For example, the headline field might have the following alias: _#HEADLINE.

To control the formatting used when your headline is output from the ActionApps database, you would simply need to put the appropriate HTML text around the alias. For example, the code 
<b>_#HEADLINE</b>
would make your headline Bold.

The sections listed under Admin - Design on the left-hand navigation panel allow you to design four types of view:

  • Index: this allows you to design the way ActionApps-generated content will appear in your index page. If you need greater control and flexibility over the display use "Views"
  • Fulltext controls the appearance of single full text items
  • Views: "Views" offer additional functionality over the basic Index and Fulltext views, such as controlling the order in which items are displayed within categories, or displaying only those items which meet certain criteria
  • Item manager allows you to make changes to the design of the Item Manager page

Specific instructions on setting up each view are contained in the following sections. Information on how aliases work can also be found below.

Index View

After you have uploaded your template file, you should apply the design parameters that you want to use for the Index View of your Action Apps. This is the view that provides a list of the items in your slice. In the Design - Index control panel, you design the Index page. There are several parts to the control panel.


The Admin - Design Index View page File:Image


Top HTML

Top HTML is the HTML at the top of the slice. If you embed your slice in an .shtml page, you will probably not need to use this section of the design page.

If you display your slice by referencing the raw URL for the slice (ie not using a server side include), you will want to add at least a title in HTML to the slice e.g. “News from the APC Networks".

Odd and Even Rows

Each row in your index page will show the index listing of one item. You can have different designs for even and odd rows. Typically, people do this so that they can have alternating color schemes, making it easier to read the rows.

Odd Rows is where you combine HTML and aliases to display to produce the look you want. Aliases are placeholders for items' fields.

Here is a sample value for Odd Rows:

_#PUB_DATE - <a href=_#HDLN_URL>_#HEADLIN2</a>
_#PLACE###(<a href="_#SRC_URL#">_#SOURCE##</a>) - _#ABSTRACT

Notice that there are HTML elements (such as setting the color to 808080), and there are aliases, (such as displaying the publish date of the item _#PUB_DATE).

Even Rows functions just like Odd rows. To use Even Rows, be sure to select the Use another HTML for Even Rows checkbox.

Bottom HTML

Bottom HTML is just like Top HTML, except that this HTML code is placed after the very last item in the index. This row is often used to add a footer to the page.

The Admin - Design Index View page continued File:Image


Sort Items by Category

You can group the rows of items by category. To do this, select the Sort items by category checkbox.

If this is checked, then the items will be grouped by category. Each group of items will have Category Top HTML and Category Headline above it. Whatever you want to appear after the last item in a category should appear Category Bottom HTML, for example a footer for the category.

Remove Strings

In Remove Strings, you specify strings of characters that you want to hide from your users.

When mixing HTML and aliases, sometimes you see HTML code that you don't want shown to users. For example, say you have code like this (_#AUTHOR##). Normally, this will display as: 

 (Michael Jackson)

But when an item has a blank value for 'author', it will display as 

 ()

To avoid confusing users with empty parentheses in your list of items, type () in the Remove Strings field, and ActionApps will take away all empty parentheses.

Fulltext View

When people click on a link to an item, they will see the fulltext page for that item. This page generally shows all the information about that item. In the Design - Fulltext control panel, you design the Fulltext page.

The Admin - Design Fulltext View page File:Image


Top HTML

Top HTML is the HTML that appears at the top of the slice. If you embed your slice in a .shtml page, you will only have a little bit of HTML set in part of the control panel.

If you display your slice by referencing the raw URL for the slice, you will want to add more HTML. Typically people put their logo or site navigation bar in the Top HTML.

Fulltext HTML Code

The Fulltext HTML code area is where you describe how the Fulltext view of your item should appear. You can mix Aliases and HTML in this field. Scroll to the bottom of the page to see the list of available Aliases. When a user views this page, the aliases will be substituted for the real values from the database.

Bottom HTML

Bottom HTML functions just like Top HTML, except that this HTML code appears after the last items, e.g. a footer for the page.

Remove Strings

Use this section for any text patterns that you do not want to appear in the Fulltext HTML code.

Item Manager View

The Item Manager is the page that your authors use to edit the items in your slice. This is the center of your administrative interface. Your slice editors will scan the list of items, moving items from one folder or bin to another as needed. Each item is a row in the Item Manager interface.

In this control panel, you customize how the Item Manager will look. You specify what is above the row of items, what is below the row of items, and what fields appear.


The Admin - Design Item Manager View page File:Image


Top HTML

Top HTML is the HTML at the top of the item manager, above the list of items. This could be, for example, your organization's logo. This function is not normally necessary when embedding an ActionApps slice into an .shtml file using SSI.

Item Format

Item Format is the main part of the control panel. Here you mix HTML and Aliases to set how each row of the item manager is displayed. The list of available Aliases appears at the bottom of the page.


Bottom HTML

Bottom HTML functions like Top HTML, except that this HTML code is placed after the last items.

Remove Strings

Use this section for text patterns that you want removed from the Fulltext HTML code.

After you have editing these attributes, click Update to save your changes.

Views

"Views" enable greater control over the display of ActionApps-generated content than can be achieved using the standard Index view. For example, you can control the order in which items display on your web page, or display only items meeting criteria which you specify.

Views also allow you to base many different web pages on a single ActionApps slice. For example, you could set up a single slice to capture news items on Human Rights, Environmental Justice, and Sustainable Development, and set up three different views so that Human Rights items display on one web page, Sustainable Development items on another, and so on.

Setting up views

Select the type of view you would like to create from the drop-down list on the Admin - design View page, and click on the New button. [Note: this section describes only Item Listing Views - for information on other types of View see the ActionApps FAQ <http://apc-aa.sourceforge.net/faq/>

The Admin - design view page File:Image


The Item Listing View design page File:Image


The Item Listing Admin - design View page uses the same basic parameters as the Index view design, such as Top HTML, Odd Rows, Bottom HTML etc. In addition, it includes parameters which allow you to order the display of items, group items according to specific criteria, display only those items which meet specified criteria, and set the number of item which will display on a page.

Using Views to Control the Order in which Items Display (sorting)

If you want to control the order in which ActionApps-generated items display on the web page, you can specify primary and secondary criteria for sorting items (ascending or descending) using the Sort Primary and Sort Secondary drop-down lists. Sort Primary determines the main order in which items display; Sort Secondary sorts within this. For example, you might choose to sort first by category, then by publication date within each category.

Using Views to Group Items

Group by allows you to group items on the web page according to whatever field you choose from the drop-down list.

Use Group title format to specify the heading which will appear above the grouped items on the web page. For example,

#Category

specifies that each group of items should appear under the relevant category heading.

Conditions

You can specify up to three conditions which will restrict the items displayed to those meeting particular criteria. In the example in the screenshot above, Condition 1 defines the parameter as follows:

  • The condition relates to the category group trainer/general
  • Only items which do not contain the specified string should be displayed
  • The specified string in this example is "General"

For more detailed guidelines on using conditions and URL parameters see the ActionApps FAQ section on selecting a sub-set of items: <http://apc-aa.sourceforge.net/faq/>

How to Set Up Search and Search Output

Most search engines will treat ActionApps-generated web pages as normal web pages, and index them accordingly. This means that if you are already using a search engine on your site, you will be able to use it to search the content of your ActionApps slices.

It is also possible to add Search functionality directly to your ActionApps slices.

Search Form

A search form lets users enter their search criteria. The search form could be a simple keyword search form that lets users search through all the full texts of items for a certain word or phrase (e.g. see “Fast News Search" in the left side bar of http://www.apc.org/english/news/index.shtml), or it could be more complicated and let the user search for all items published after a certain date (e.g. see: http://www.apc.org/english/news/index.shtml?bigsrch=1).

Search Results

The search results page displays the results of the user's search, or all content items that meet his search criteria. The search results page is very similar to the Index template page. It defines the format of the index of items that match the search results.

To create a simple search form, include HTML like this on the page:

<form action="index.shtml" method="get" name="sf" id="sf"> Search for items whose summaries contain this word: <input type="text" name="conds[0][summary.........]">
<input type="submit" value="Search" > </form>

Note: This is that the 'action' of the form and you also need a template file for the search results page. For more information on how to create a template file, see manual section 3.4.1: Creating a Template File.

You can also reuse your standard index template file as the search results template. To do this, just point the search form 'action' to your standard index template file, for example, index.shtml.

The main part of the search form is this HTML fragment: <input type="text" name="conds[0][summary.........]"> This creates a input form textbox where users can type in the word for which they want to search.

Note: The 'name' of the input needs to be 'conds[0][fieldname]', where 'fieldname' is replaced by the ActionApps id for the field you are searching. The [0] after 'conds' is a numeric zero, and not the capital letter 'O'. To find the list of fields and their ids, login to the administrative interface, and go to Admin - Main Settings - Fields. The field ids are the second column in each row. Typical field ids are 'headline........', 'created_by......', and'full_text.......'.

'For more information, including special options and multi-field searching, please look at: <'>'.'.'.'.

Retrieved from "http://documentation.actionapps.org/documentation/index.php?title=User:Milhaus/Webmasters_Guide/Designing_ActionApps_Output&oldid=3206"