PortalApp Documentation
Version 4.0

PortalApp is a fast, flexible, configurable, Web application framework that supports user authentication, content mangement, e-commerce, community and collaboration. PortalApp is versatile and can be used to rapidly deploy any "type" of Web site. PortalApp Websites may be corporate websites, portals, intranets, extranets and virtually any other Web application that requires the type of functionality provided in PortalApp.

This document is a reference and guide to all PortalApp features, components, data model, application and security settings, administration and UI (user interface). This document is intended for site integrators, administrators and Webmasters.

• Administration (ACP)
  • Access & Login
  • Sitewide Options & Settings
  • Languages and Labels
• Styles, Layout & Homepage
  • Layouts
  • Sections & Include Pages
• Categories & Site Navigation
• Content Management
  • Content "Types"
  • Content Display
  • Content Authoring/Submission
  • SEO (Search Enging Optimization) and Permalinks
  • Content Restriction/Subscription
    • Downloadable Items
    • RSS / ATOM Reading and Publishing
  • Usage Scenarios
• User and Groups Management
• E-Commerce
  • Product Catalog
    • Services & Soft Goods
    • Subscription/Pay-for Membership
  • Shipping & Taxes
  • Payment Gateways
  • Order Management
• Forums
• Surveys
• Auctions
• Ad Management
• Newsletter Management
• Calendar & Events
• Affiliates
• File Management
• Chat/Conference & Paging
• Database Model
• Default Security Settings
• Page List (.asp scripts)

Administration (ACP)

All aspects of the site can be managed via the Web-based Administration Control Panel. Using the ACP, you can configure the design, structure, content and layout of the site. 

To login and access the ACP, use the 'sa' (Super Admin) account and password that has been provided. Once you login to the ACP, select the icon for the feature you wish to manage. A minimum Access Level of 4 is required to access the ACP.

Sitewide Settings & Labels

Sitewide settings such as date/time formats, site title and URL paths can be set in the Options menu of the ACP at: ACP > Options > General Settings

• Server date time settings
• Server email component
• Site label, title
• Site root path and secure (SSL) root path
• Server time difference (in hours) - adjusts time sensitive information accordingly
• Auto Content Expire (in days) - sets the date expire field when content is added

Email Confirmation/Notification Messages

Various "notification" emails are sent in different site areas. These messages are sent for features like password lookup, new forum topics, order confirmation and new user registration.

All of these messages can be viewed and edited via the ACP > Newsletters menu. This is the same Newsletter facility that can be used to compose and send any e-Newsletters.

Each email "notification" function is assigned a corresponding Newsletter message via the Global Options menu at  ACP > Options.  To assign a message for email "notification", select from the drop-down lists in the Email & Messages section. By default, several messages are defined and set for each notification function.

Notification emails:

• password/user lookup
• forums post/reply
• new content
• approved content 
• order confirmation

For more information on Newsletter message compostion, see the Newsletter Management section.

Enabling & Disabling Features

Certain features such as ad banner, forums, surveys, etc.. can be toggled via the Options menu of the ACP at: ACP > Options > Enable / Disable Settings.

Labels & Language

Most of the labels used throughout the user interface can be modified in under the ACP > General Options > Edit Labels link. All of the language definitions are stored in the "common/language.xml" file. This XML file contains a section for each defined language, and all of the potential labels (text or HTML) that are defined throughout the user interface. The Locale, LCID and Charset settings for each language can also be defined in the Languages and Labels editor.

In this way, the "Forums" could be re-labeled "Bulletin Boards" or "Discussion Area". The Form Labels section defines labels for each of the standard content fields. In this way, form labels like "Title", "Category", or "Author" can be re-labeled.  Translated versions of the site can also be created by modifying these user interface labels.

To define a new language, a new language definition must be created in the "common/language.xml" file.

 

Top ^ 

Styles, Wrapper and Homepage Layout 

Design flexibility is a key element. Easy-to-manage include files and style sheets (A.K.A. "skins") separate the portal's design layer.  This means virtually any look-and-feel can be integrated with the portal's functional layer. Any Flash, DHTML, and client side scripting can be added to the portal's design wrapper. The design portions are changed via standard HTML includes that are used to create a wrapper around the dynamic content areas. Style sheets are used to manage design elements thoughout the site. Several design layouts are provided so that you can use the existing layouts or create your own by following the guidelines outlines in the Design & Style Guide.

The fonts, colors and styles used throughout the site are defined on the 'default.css' *(see footnote) style sheet.  This style sheet can be viewed and edited via the ACP > Styles menu.

Additional style sheets are provided and can be enabled via the ACP > Styles menu. To use another style sheet, select it from the "Pre-defined styles" drop-down list and click the "Set as Current Style" button.  Use caution as this action will overwrite the existing 'default.css' so any previous style customizations would be lost.

Each component of a page has a related style property. The source code for the default.css page can be directly edited by clicking the "View / Edit Source Code" link.

For a detailed look at all style properties, or to create custom themes (skins), refer to the Design Guide.

Wrapper = Header and Footer Templates

All site pages share a common "Wrapper" that surrounds the functional and content portion of the page. The "Wrapper" is made up of 2 pages -- Everything before the functional and content portion is in the Header (i_header.asp) and everything that follows is in the Footer (i-footer.asp).

To view or modify the Header & Footer, use the ACP > Wrapper menu. When viewing the Header and Footer you'll see that other include pages are referred to in the HTML code.  These other include pages construct the navigation (App and Content Menus) that are used throughout the site.

If you wished to create an entirely custom navigation that used Flash, DHTML or any other HTML interpreted code it could be added here by editing the HTML content of the Header & Footer. In this scenario you would also want to remove include references to the other navigation include in the code (ie: <!--#include file='i_app_menu_v.asp'-->).

* -  The 'default.css' style sheet is referenced via a LINK HTML tag in the site's Header (ACP > Wrapper). Since it is possible to edit the Header (i_header.asp) HTML code the LINK tag can be changed to use an alternate style sheet or completely removed.

 

Homepage Layouts

The Homepage (default.asp) is the entry way to the site and the first page that most visitors will encounter.  Homepage content is frequently updated and the desired layout will vary dependant on site reqirements.  For this reason, several layouts have been made available to easily modify the layout and content of this page.

To modify the homepage layout: ACP > Homepage

If requirements extend beyond the included layouts, The ACP > Homepage area also provides a means to directly edit the source code of the default.asp page. Click the 'View / Edit Source Code' link to edit the source code. Click the 'Save to Default.asp' button to save any changes. Note that any changes made here will overwrite the default.asp page.

Any of the include pages can be referenced in the default.asp source code to enhance the functionality and content of this page.

 

Use Include Pages for Extended Functionality

Several include pages are provided that can be used to extend functionality.

To reference an include, use this code where needed on the homepage (default.asp):

<!--#include file='i_anyincludepage.asp'-->

A very powerful feature is that includes are also available when editing content in the WYSIWYG editor. Select an include page from the "Includes" drop down list and the appropriate code {|common/i_includepage.asp|} will be inserted into the content. When the page is viewed, the included page will act as an independent panel within the content.

Content Related Includes

Use these files to select and display various content items....

i_generalcontent.asp

Displays any "general" Content (ContentTypeId=1) that is featured. Use the 'HomeContentHeadTD' and 'HomeContentHeadFont' style properties to format the display of the 1st featured item. Subsequent featured items use the 'HomeContentTD' and 'HomeContentFont' style properties. To change the order of items displayed, use the ACP > Content > (select an item to edit) > Priority field.

i_featuredcontent_col.asp - (single column)
i_featuredcontent_2col.asp - (2 columns)
i_featuredcontent_row.asp - (horizontal row)
i_featuredtitles_row.asp - (horizontal row - titles only)

Displays any featured content from any of the other Content Types (ContentTypeId<>1). Use the 'FeatureTable', 'FeatureHeadTD' and 'FeatureTitleTD' and 'FeatureTD' style properties to format the display of items in these include pages. The label that displays at the top of each section feature is set in the ACP > Content > Content Types > (select a type to edit) > "Featured" label field. When left blank the 'FeatureHeadTD' row is eliminated.

i_newcontent_col.asp
i_newcontent_2col.asp
i_newcontent_row.asp

Displays the newest content from any of the other Content Types (ContentTypeId<>1). Use the 'SectionTable', 'SectionHeadTD' and 'SectionTitleTD' and 'SectionTD' style properties to format the display of items in these include pages. The 'newest' label that displays at the top of these includes is set in the ACP > Options > 'Newest Label' setting.

i_contentlist_top10.asp (selects Top 10 records)
i_contentlist_top5.asp (selects Top 5 records)

Displays a top (5 or 10) list of featured content ordered by Priority, Date Added(newest first). These includes are the best choice for creating a blog-style list of content that displays the Title and Short Description of each item. If no Short Description is defined the Full Content is displayed instead. The "More" link is also displayed, so that users can drill-down to see the Content Detail Page.

i_content_bymonth.asp (displays most recent 24 months with links to content for each month)
i_toprated.asp
i_popular.asp
i_popcontent_row.asp (horizontal row of content types where popular is enabled)
i_newest.asp

Displays a linked list of content titles ordered by correspondingly by rating(i_toprated.asp), views(i_popular.asp) or most recent first(i_newest.asp).

i_popular5_cat.asp (top 5 most popular item titles (most impressions) filtered by current category)
i_newest5_cat.asp (top 5 newest item titles filtered by current category)
i_popular_cats.asp (the most popular categories according to content impressions)

i_myfavorites.asp

Displays a link list of content titles that the user has added to their favorites list.

i_tabs_1.asp (general content, newest content, categories)
i_tabs_2.asp (general content, who's online, categories)

These tabular panels display tabbed sections on the home page. Use the .TabTable, .TabTD, .TabFont and .PanelTable style classes to format the tabs and panels

 

Special Function Includes

Use these files to select and display other functional sections...

i_forums.asp
i_featuredsurvey.asp
i_affiliates.asp
i_whosonline.asp
i_calendar.asp
i_cats.asp (list of all top level categories)
i_upcomingevents.asp
i_inbox.asp
i_subscribe.asp
i_search.asp
i_login.asp
i_feed.asp (RSS / ATOM feed parser - reads and displays RSS feeds)
i_language.asp (language selector dropdown list - when more than 1 language is enabled)
i_language_menu_h.asp (language selector links - when more than 1 language is enabled)

  Top ^ 

User Management

All user related data can be managed via the ACP > Users menu. By default, an Access Level of 5 is required to access this page.

Adding Users

There are 3 ways that new users can be added to the site's database. Once added with a username, email address and password the user can login and access restricted areas (for more information see "Access Levels & Security") of the site. The only required field in the Users database table is the email address so that Users can subscribe to the Newsletter without a Username and Password. In order to login, a Username and Password are required.

1) Users can "sign-up" on the registration page (register.asp)

2) Users can be added via the ACP > Users menu 

3) Users can subscribe (email only) via the Newsletter subscription pages (i_subscribe.asp & subscribe.asp)

By default, when a user registers via register.asp they will be assigned an access level of 1. The new user will receive a "Welcome New User" email notification. The text of this new user message is defined via the ACP > Newsletters menu. The "default" Newsletter message can be changed by marking the "send to new users?" checkbox. Only 1 Newsletter should be set as the new users "default". Information on other email notification functions can be found in the "Administration & Options" section.

When a user is added via the ACP > User Management page, the access level can be set accordingly by the administrator. For more information on the access levels required for specfic areas review the "Default Security Settings" in the Documentation.

User Groups

User groups (roles) can be managed using the ACP > User Management > ' Manage Groups' link. Users can belong to one or more groups. To create a group, specify a label (name) for the group and click the 'CREATE GROUP' button. The access level field is only used for compatibility with previous versions. You can add a user to a group, by select the user via ACP > User Management, or using the 'Add user to group' link on the ACP > Users > Group Management page.

Permissions (granting or denying access to specific content, sections or categories)

When the application settings (ACP > Options) 'Enable group security' option is enabled, group security is used. Permissions can be set (granted) on a per content, category or section (Content Type) basis. An individual user or an entire group can be assigned permissions. The permissions that are available (view,add,edit,approve and delete) depend on the granularity (or "level") of the item.

When no permissions are set for a given content, category or section -- the default security settings (based on user access level) are enforced. When permissions are set for any user or group, all excluded groups or users will have the default permissions to 'view' items, 'add' new items or 'edit/delete' items when there access level is appropriate.

For content items - based on current 'ContentId'

• 'View' - specified user or group can view the content item
• 'Edit' - specified user or group can modify the content item
• 'Approve' - specified user or group can approve (display) the content item
• 'Delete' - specified user or group can delete the content item
  
For sections (content types) - based on current 'ContentTypeId'

• 'View' - specified user or group can view items in the specified section
• 'Add' - specified user or group can add items to the specified section
• 'Edit' - specified user or group can modify items in the specified section
• 'Approve' - specified user or group can approve items in the specified section
• 'Delete' - specified user or group can delete items in the specified section
  
For categories - based on current 'CatId'

• 'View' - specified user or group can view items in the specified category
  


To set permission on a content item, section or category, the value of a ContentId, ContentTypeId or CatId is specified in the 'Item #' field of the permissions manager, and the Item level option is used to specify whether the given Item number represents a content item, section (content type) or category.

Setting permissions on content items
To grant (or deny) permissions for a user or group on a specific content item, navigate to ACP > Content > and click on the title of content item in the list. Once in content editing mode, scroll to and click the 'Set custom permissions..' link. In the permissions manager, you should now see the ContentId (#) of the content in the Item # field. Next, find and select the appropriate user or group in the 'User' OR 'Groups' drop-down lists. Finally, check the permissions to grant, and click the 'SET PERMISSIONS' button.


Setting permissions on a section (Content Type)
To grant (or deny) permissions for a user or group on an entire site section, navigate to ACP > Sections > and click on the title of content type (section) in the list. Once on the content type setting page, scroll to and click the 'Set custom permissions..' link. In the permissions manager, you should now see the ContentTypeId (#) of the content type in the Item # field. Next, find and select the appropriate user or group in the 'User' OR 'Groups' drop-down lists. Finally, check the permissions to grant, and click the 'SET PERMISSIONS' button.


Setting permissions on a category
To grant (or deny) view permissions for a user or group on an entire category, navigate to ACP > Categories > and click on the category in the list. Once on the category edit page, scroll to and click the 'Set permissions on this category..' link. In the permissions manager, you should now see the CatId (#) of the category in the Item # field. Next, find and select the appropriate user or group in the 'User' OR 'Groups' drop-down lists. Finally, check the permissions to grant, and click the 'SET PERMISSIONS' button.

For more information on access levels and security settings see, Default Security Settings.

Top ^

Site Navigation & Categories

The site's Content Menu is dynamically created by the Categories and Content Types defined in the ACP.

The application was designed to meet two critical navigation requirements: 1) The user should always understand where they are, and 2) The path to major (top-level) content should always be obvious.

Application information architecture:

Site > Sections (content types) > Categories > Content

Sections known as Content Types have settings to control the layout and fields of each site section. Think of these sections as page layouts.

Categories are used to create a topical structure for your site and it's content.

When determining categories for the site, consider what topical (subject) labels apply to your site's content. Think of the categories as a primary means to organize the content. Create an outline and create a multi-level heirarchy if needed.

Categories can be added and updated via the ACP > Categories Menu.

Next determine all of the "types" or forms of content that will be on the site. For example, 'article', 'photo', 'press release' or 'business listing' are types of content.  Think of each Content Type in it's entierty.  For example, the 'article' content type may contain various sections of text, images and data, where as the 'photo' content type may only be a single image.

Sections (Content Types) can be added and updated via the ACP > Content > Content Types Menu.

For more information, see Content Management and Content Types

 Top ^

Content Management System (CMS)

All CMS functions and content can be managed via the ACP > Content Manager.

Sitewide Content Settings & Labels

Various labels that identify items on the Content UI (content.asp) can be managed via the ACP > Options menu. The default Content List Page fields and labels on the Content Submission Form can also be defined here. 

Content "Types"

Websites contain various "types" of content that can take many forms. Think of a content type as a section within the site. Examples of content types are: product or service descriptions, articles, news stories, frequently asked questions, photo galleries, downloadable files, case studies, white papers, company information and virtually any other format. Content types are often used to distinguish page layouts and create "sections". Each Content Type may consist of text, images, hyperlinks and other information. This information (or data) may have identifiable fields such as "title", "description" or "date added".

Several Content Types are pre-defined. To modify these types or create new ones, use the ACP > Content > Content Types menu. In essence, then Content "Types" become the content driven sections of the site. For more information on setting up Content Types and Categories, see Usage Scenarios.

 

The "General" Content Type

The "General" Content Type (which always has Content Type Id value of 1) can be used to create generalized content and informational articles for the site. Content items such as "About this Site", "Contact Information", "Mission Statement", "Terms of use" or "Privacy Policy" are usually a good fit for the "General" content type.  General news and annoucements are also good items for the "General" content type. Using the "General" content type, a Blog style news list can be created on the home page -- where items can be featured and/or latest items listed first. For the home page, any "General" Content Type items that are marked as featured will display first as part of the main featured content section.

Top ^ 

Content Type and Category Relationships

To optimize display of content within the heirarchy of categories, any or all Content Types can be set to use all or a dedicated group of categories (Category Group). To "filter" the available categories for any given Content Type, there are several options...

1) Dedicating Categories to a Content Type

Any given content type can have it's own dedicated group of categories (Category Group). In this way the display of content can be filtered into categories and only these categories will be displayed when content is authored for the given type.

For example, consider the "FAQ" Content Type. We want to create an "FAQ" content section whereby the user first selects a topical category and then reads the FAQ's in the selected category.

First, we create a list of categories via ACP > Categories and put them into a Category Group named 'FAQ Topics'...

Here are our categories that are 'FAQ Topics' :

• Sales Questions
• Technical Questions
  • Installation & Set-up
  • How do I...?

Next, a content type named 'FAQ' is created via ACP > Content > Content Types. Each 'FAQ' consist of several fields. These fields are set for the add/edit, list and detail of the FAQ content type ...

• Title
• Category
• Question
• Answer

Finally, set the 'Limit categories' drop-down list to 'FAQ Topics', so that this becomes the cateory type that is dedicated to the 'FAQ' content type.  When the 'FAQ' content section is accessed from the site, the list of FAQ Topics is displayed to the use for selection.

2) Cross-type Categories

In this scenario, one group of categories is used by several (1 or more) content types. In this example, consider the 'Article' and 'Link' content types.

For this cross-type scenario, both "Links" and "Articles" will share the same group of topics (categories).  A category group named "Article and Resources" is created. The topical categories are added to this type via the ACP > Categories menu. Any "Link" or "Article" that is added to the site will fall into one of these categories:

• Sports
  • Football
  • Soccer
  • Baseball
• Cooking
  • Grilling
  • Asian style
  • Gourmet

Secondly, a content type named "Link" is created via ACP > Content > Content Types. The 'Limit categories' drop-down list is set to the "Article and Resources" category group. The 'Link' content type uses these fields.

• Category
• Title
• Short Description
• Related URL

Next, a content type named "Article" is created ACP > Content > Content Types. The 'Limit categories' drop-down list is also set to the "Article and Resources" category group. The 'Article' content type uses these fields: 

• Category
• Title
• Author
• Short Description
• Body / Long Description
• Date Added

Finally, when a user selects the Links or Articles section the list of "Article and Resources" categories is displayed. Similiarly when content if the "Link" or "Article" type is submitted, the category selection list will only display the "Article and Resources" categories.

When the sitemap (content.asp) page is accessed, the heirarchy of category groups and categories is displayed. If the user were to select the "Article and Resources" category group that we've created, content of both "Link" and "Article" type would be listed.

3) Using All Categories for a Content Type

Often, content items may apply to any category that has been created. For example, the content of a "Press Release" may relate to a product, person or just be "generic" in nature. To categorize this type of content, the "Limit Categories" drop-down list is not used. When content is submitted for this type, the entire list of site-wide categories is displayed. Similiarly, the user is not forced to first selected a category when browsing this content section.

For more information on setting up Content Types and Categories, see Usage Scenarios.

Top ^ 

Basic Content Management

All content can be maintained via the ACP > Content Manager. From this area administrators can...

• List all content items
• Add new content
• Edit/delete existing content
• Update multiple items at once
• Define & manage content types

Content Display

From the site's Content page (content.asp), all content is displayed in List and Detail format. While defining a Content Type, various options allow you to change the format and functionality of each Type.  Under the List Page and Detail Page sections you can select the fields that should be enabled for the Content Type.

If no fields are selected for detail view, the "Title" link created for the list view will link to the click thru page (instead of the content detail page). In this way you can directly link to related or download url's without displaying the content detail view.

At the foundation of the CMS are 20 base fields that accomodate 90% of the data for any given content model such as articles, downloads, links, photos, news and company information. 

Standard Content Fields:

• Title
• Author/Credit
• Username (The user that posts the content)
• Short Description
• Full Description (Enables WYSIWYG editing) 
• Date Added
• Category
• Impressions
• Average Rating
• Priority
• Status (new(0), open(1), closed(2))
• Image (Upload or select)
• Thumbnail (Upload or select)
• Filename (Upload or select)
• Related URL
• Download URL
• Prev/Next Link (Enables content series)
  

Custom Content Fields

When a Content Type requires more specification, custom fields can be defined via the ACP > Content Manager > Content Types. 

For example, consider a "Real Estate Listing" as a Content Type. Each listing would use some standard content fields like "Title", "Description" and "Date Added".  A real estate listing would also require several industry specific fields like "Bedrooms", "Baths", "Lot Size", etc..

Various options are set for each custom field:

• Attribute Label: The name & label of the custom field
• Input Type: The form input for the Content Submission page
  • Select
  • Text
  • Textarea
  • Radio
  • Checkbox
  • Label (none)
  • Hyperlink
• Size, Rows, Max (applies only to Text, Textarea)
• Tag Attributes: Add HTML attributes to the form input (ie; OnClick="javascript:..")
• Option SQL (Radio, Select, Checkbox): SQL Query to use to generate the options
• Option List (Radio, Select, Checkbox): Comma sepated list of options
• Default Value: Set on Content Submission form when new content is added
• Pre HTML, Post HTML: Any HTML code that should display before or after the custom field on the Content Submission form.

For more information see, Content Authoring & Submission

"Paging" and "Wrapping" Content Lists 

The ACP > Content Manager > Content Types menu also has settings that define how many records are shown per page and per row in the Content List View. To set these values, specify a number in the "Start new row every" and "Start new page every" form inouts. When no values are specified, the defaults are used:

• 10 records per page
• 1 records per row

Creating Multi-part Content (Series) 

Of then there is a need to create a sequence of content items that are separated into "pages". The Previous Item and Next Item content selection lists can be used to define successive or preceding content items. This feature is handy if you have content items that are in sections, chapters or that relate to each other.

Featuring Content

To feature a content item, click on the item's Title in the ACP Content Manager list.  Once in edit mode, a populated form will display with all of the fields for the content item. The "Display" and "Featured" checkboxes can be marked as needed, and then use the UPDATE button to commit the change(s).

Content items marked "Featured" are flagged for display on the Homepage. However, there are other settings that will affect the display of items on the Homepage. Remember that "General" content (Id# 1) will display in the main feature of the Homepage.

"Featured" content items will display when:

1. The "Feature" checkbox is set via the ACP > Content Manager
2. The item's Content Type is enabled and ready for display on the Homepage
3. The Homepage layout includes a featured content section 

Custom Content Templates

In the ACP > Sections menu the settings for each Content Type are defined. Using the 'List template' and 'Detail template' fields, administrators can define custom HTML layouts for any Content Type.

List Template
Since the list view shows 1 or more content records, the 'List Template' can be used to define the layout and fields for each row (1 record) of the Content Type's list view. Using special {|b|} and {|e|} code tags, the start and end of the repeating section can be defined. HTML code not surrounded by the {|b|} and {|e|} tags will not be repeated for each row (record).

Detail Template
The detail template can be used to define the layout and fields for the Content Type's detail view.

Merging field values into the templates
The value of any content field can be plugged into the list or detail templates by surrounding the field name with special "{|" and "|}" tags. Here is the list of available field values that can be merged into the templates.

Value fields

• {|Title|} - Title of the item
• {|DateAdded|} - Date the item was added
• {|DateModified|} - Date the item was last updated
• {|Author|} - Author or credit for the item
• {|User_Name|} - The username (owner) of the item
• {|ShortDesc|} - Short description / abstract
• {|LongDesc|} - Full content / body
• {|DateAlert|} - Date for next review or due date
• {|Status|} - Current status
• {|Cat|} - Category
• {|ContentType|} - Section / content type
• {|RelatedURL|} - Related URL
• {|DownloadURL|} - Download URL
• {|Filename|} - File name / path on local server
• {|Image1|} - Primary image
• {|Thumbnail|} - Thumbnail image
• {|Impressions|} - Number of times the item detail has been viewed
• {|ClickThrus|} - Number of times the related or download url has been clicked
• {|AvgRating|} - Current average rating of the item
• {|CatTechnorati|} - Technorati.com Tag for the item
• {|CatDigg} - Digg.com category for the item
• {|CatAlias|} - Additional category/tag for the item
• {|PermaLink|} - Non-parameterized link (URL) for the page (custom404.asp error page must be enabled)

Identifier fields

• {|ContentId|} - Id of the item
• {|User_Id|} - Id of user associated with the item (owner)
• {|CreatedBy|} - Id of user that submitted the item
• {|CatId|} - Id of associated category
• {|ContentTypeId|} - Id of associated section
• {|PrevContentId|} - Id of previous item
• {|NextContentId|} - Id of next item

Example Templates

Here is an example template for a List view that will list the Title and Short Description of each record in the left column. The title is hyperlinked to the content detail page by passing the value of the ContentId in the link. The right column will display the Date Added (right justified) after the "Created:" label.

<!-- start row --> <TR> <TD> <TABLE> <tr> <td style="{padding:5px;}"> <b><A href='content.asp?ContentId={|ContentId|}'>{|Title|}</A></b> <p>{|ShortDesc|}</p> </td> <td style="{padding:5px;text-align:right;width:20%;}"> <strong>Created:</strong> {|DateAdded|} </td> </tr> </TABLE> </TD> </TR> <!-- end row -->

Here is an example template for a Detail view that will show the Title, Long Description and Impressions for the selected content record in a wide left-side column. The right column will display the Date Added (right justified) after the "Created:" label.

<tr> <td style="{padding:5px;}"> <h1>{|Title|}</h1> <p>{|LongDesc|}</p> <p>This page has been viewed: {|Impressions|} times</p> </td> <td style="{padding:5px;text-align:right;width:180;}"> <strong>Created:</strong> {|DateAdded|} </td> </tr>

Here is an example template for a List view that will list the Title, Author and Short Description of each record in the left column. The Title is hyperlinked to the content detail page by passing the value of the ContentId in the link. 1 banner (125 x 125) will be displayed right-side column. Notice the {|b|} and {|e|} tags surround the portion that is to be repeated for each record.

<!-- display for first record --> <TR> <TD> <table> <tr> <td style="{padding:8px;}"> <!-- end display first record --> {|b|} <!-- repeat this section for every record --> <b><A href='content.asp?ContentId={|ContentId|}'>{|Title|}</A></b> ({|Author|}) <p>{|ShortDesc|}</p> <!-- end repeat this --> {|e|} <!-- display when last record is reached --> </td> <td style="{padding:3px;width:135;}"> {%=get_banner(125,125,null)%} </td> </tr> </table> </TD> </TR> <!-- end display last record -->

 

SEO (Search Enging Optimization) and Permalinks

To optimize placement of your site in search engines such as MSN, Yahoo! and Google, SEO techniques can be enabled.

Page titles and meta tags (keywords and description) are generated directly from content which means improved search engine indexing and placement. Although dynamically generated, each page can have it's own unique title.

By using the included 'custom404.asp' file as an error page (404), each content page is accessible from a non-parameterized URL (permalink) that is based on the content title. Additionally, an "alias" can be defined for any page that enables the page to be accessed from an alternate descriptive URL (ie; http://mysite.com/My-Content-Title.html), resulting in improved search engine placement for desired keywords.

To enable permalinks, you must set the custom errors setting on the Web server to URL = /custom404.asp. This can be done using the IIS Management Console > select your Website > Custom Errors tab. If you do not have direct access to the Web server, most hosting companies allow modification of custom errors using the hosting control panel. If the site is installed in a sub-folder you may need to set the custom 404 error accordingly (ie; URL = /mysubfolder/custom404.asp).

If you or your site administrator has direct access the IIS server, open up Internet Service Manager and right click on the website. Click on Properties and then choose the Custom Errors tab. Scroll down until you get to the 404 HTTP Error. Set this error properties to URL = /custom404.asp.

Once the custom404.asp page is enabled for 404 error handling, all content item will become accessible via the content title. For example:

Use this URL to access the content title "Some content title":
http://www.myportalappsite.com/Some-content-title.html

In the content administraton area, you can additionally define an alias for the page, so that other URL's can be directed to the same content. For example:

http://www.myportalappsite.com/My-content-alias.html

Note: If the content title or alias contains special characters that are used to construct URL's such as ":", "/", or "?", the title must be properly encoded in the URL (Google: URL Escape Codes). For example, if my page title is "What-did-you-say?", the proper permalink URL would be http://www.myportalappsite.com/What-did-you-say%3F.html.

Additionally, Content Types and Category pages can be referenced via non-parameterized URL's. For example,

Use this URL to access a Content Type named "blog":
http://www.myportalappsite.com/blog.html

Use this URL to access a Category named "media coverage":
http://www.myportalappsite.com/media-coverage.html

When a Content Type and Category with the same name exist, the Category page will take precedence over the Content Type page. For example,

You have both a Category and Content Type named "News", the URL http://www.myportalappsite.com/news.html will display the "News" category page(content.asp?CatId=newscatid) :

For further information on displaying content see, Restricting Access to Content and Special Content Features

 Top ^

Content Authoring & Submission

While in the ACP > Content Manager you will also see that each Content Type has various User Submission Settings.  Select the standard and custom fields that made available for data entry on the Content Submission Page (submit_content.asp). Here you can also define which users (based on Access Level) can submit content, and which users can approve the display of content. When a Content Type utilizes the file related fields (Filename, Image or Thumbnail) you can also define which users can upload content related files to the Web server.

There are often cases where content will be submitted, but will be displayed at a later time or pending review. At any time, a content item can be removed or set using the "Display" checkbox via the ACP Content Manager. If the item is not marked for "Display", but is marked "Featured" it will remain on the Homepage, but not display elsewhere in the site.

When content is added via the Content Submission Page (submit_content.asp), the display of the item depends on it's Content Type.  In the ACP > Content > Content Types > User Submission Settings the "Required access level" for submitting content and approving content are indicated. When the submitting user's Access Level is greater than or equaly to the indicated "to approve content" level, the content item will automatically be set to display when it is submitted. A higher approval level should be used for Content Types that first require review before going live on the site.

Creating simple HTML Forms Within Content

In the Full Description field, (WYSIWYG Editing) the 'form.asp' page can be referenced to capture form results via email. To create an HTML form within the content, reference the 'form.asp' page within the <FORM> tag (action=form.asp). In order to edit the HTML source code within the WYSIWYG Editor, the "<>" icon must be clicked.

When the content (and the form contained within) is displayed to the user, any submitted form data will be passed to the ACP > Options > From Address. 

For example, here is the HTML code for a simple form that posts a name and message...

<FORM action=form.asp method=post>
<TABLE>
<TBODY>
<TR>
<TD>Name</TD>
<TD><INPUT maxLength=50 size=30 name=name> </TD></TR>
<TR>
<TD>Title</TD>
<TD><INPUT maxLength=50 size=30 name=title> </TD></TR>
<TR>
<TD>Email</TD>
<TD><INPUT maxLength=50 size=30 name=email> </TD></TR>
<TR>
<TD>Message</TD>
<TD><TEXTAREA name=message rows=10 cols=90></TEXTAREA> </TD></TR>
<TR>
<TD></TD>
<TD><INPUT type=submit value=SEND></TD></TR></TBODY>

</TABLE>

</FORM>

 

 Top ^ 

Creating parent/child content relationships

There are many scenarios where the creation of "sub" or "child" content items is used for business logic. Consider items where there may be a "parent" item and then a subset set of content items under the "parent". For example, consider a "project" that has one or more "tasks". In this case, a "project" would be the parent, and "tasks" would be the sub (child) items:
My project

• - task 1
• - task 2
• - task 3

The parent and child items may each have their own unique data fields:

Project: title, description, status, deadline, client

Tasks: title, type, description, status, attachments

Displaying sub (child) content

The fields displayed in the Sub Content grid are a subset of those selected for the Content Type's list view fields. The field that will display in the columns of the Sub Content grid are:

Title,Author/user,DateAdded,Impressions,(Custom Fields)

When no detail fields are selected, the Title link for the item in list view will link directly to the related url, download url or filename. In this way, the user does not have to first access the detail page can be directed to an external site or downloadable file.

Multiple Content Item Management

When populating the site with content, a useful facility is provided in the CMS that updates multiple content items at once. To access this facility, go to ACP > Content > Multiple Item Management.

From the Multiple Item Management page, all content items are listed and several standard content fields (Content Type, Title, Category, Description, etc..) can be updated. This page also lets the administrator quickly "Display" (Show) or Delete content items.

To create content items based on files that exist on the Web server (Download files or Images), you can specify the relative path on the Web folder (ie; images/content/feb04) in the 'Specify a Web folder on server' field.  Next, click the "Load Content" button.  A content record will be created for each file in the specified folder.  This feature is convienent for FTP'ing files and then quickly creating related content records. The created records can then be updated accordingly.

For more information on managing files on the Web server see, File Management.

 Top ^

 

Restricting Access to Content

Access to specific Content Items can be restricted used the Required Access Level field. When using ACP > Content Manager to add/edit the content record, specify the minimum Required Access Level that the user must have in order to view the Content Detail page. When a user attempts to amplify from the list view to the detail view, their Access Level is validated against the Access Level specified for the Content Item. When their Access Level is not adequate, they're redirected to login. Otherwise, the Content Detail page is displayed.

For more information, see Selling Subscriptions & Paid Memberships

Downloadable Files (Download URL and Primary Filename)

Your site may sell soft goods, or items that must be purchased before they can accessed and downloaded. In this case, you need to create a both an E-commerce Item and a related Content Item for the downloadable file itself. When the download item(s) do not require purchase, they can simply by created as a content item with related Filename and/or Download URL.

The Content Manager is used to create the Content item and upload the related download file. By default, the files will be uploaded to the '/library' folder, but this folder path can be changed during the upload process to use a different target folder. If the download files already exist on the server, or you want to FTP several files at once, see the Multiple Content Item Management section.  Either the Download URL can be used to specify a complete URL for the download file, or the Filename field can be used to specify a local path on the Web server (or the Web server's network)

When a Download URL is specified:

A link is created on the Content Detail Page (content.asp) that displays the URL. The link references 'click_download.asp'. When the link is clicked by a user, the Required Access Level is checked. Next, the 'click_download.asp' script increments the Content downloads counter and then initiates the download by redirecting to the specified URL.

When a Primary Filename is specified:

A link is created on the Content Detail Page (content.asp) that displays the file path. Any local folders above the site root folder will be truncated from the file path. If the entire path is above the site root, only the filename itself will display. For more information on managing files on the Web server see, File Management.

When using the Filename field to reference the download file, access to the download file can be controlled in 3 ways:

1. open access: any visitor can download any file.
2. level-based access: users of a specified access level can download the file.
3. purchase-based access: users that purchase specified SKUs can download the file.

Open download access

No special settings are required to enable this. By default, any content with a related Download URL or Filename will be made accessible to all users provided that the Download URL and/or Filename fields are set to display on the Detail Page of the Content Type. In this case, also make sure that users have READ permission on the folders where the download file(s) are located.

Level-based download access
To enable this when using 'ACP > Content Manager' to add/edit the content record, specify the minimum Required Access Level that the user must have in order to download the file. When a user attempts to download the file via 'click_download.asp', their Access Level is validated against the access level specified for the content record.

Purchase-based download access

To enable this when using 'ACP > Content Manager' to add/edit the content, ;specify a comma separated list of product SKUs (SKU Reference List) that the user must have purchased in order to download the file. When a user attempts to download the file, the OrderItems database table is queried to assure that the user has purchased 1 of the SKUs specified in the list of SKUs specified for the content record. The related order record must have a 'complete' status.

For added security, enable random file copying
Eventhough level-based and purchase-based access provide some security to the downloads area, it is still possible for users to guess file locations and names. To further prevent unauthorized file downloads, you can enable a random file copying. In this scenario, the source file is located in a folder that is not accessible to the Web browser. When the download is requested, the source file is renamed and copied to a Web accessible folder for the user to download. To enable this, a full local file path must be specified for the 'Filename' field in the Content table. When adding or editing the downloadable content using the Content Manager, specify a full local path for the download filename ie; "c:\downloads\sourcefile.zip". The local folder where the file is located should be inaccessible from the Web. The Web server's anonymous user account will need READ permissions to this folder, but since the anonymous user account is a system account, the actual download file(s) will not be accessible from the Web browser. When an authorized user attempts to access the download file via 'click_download.asp', the file will be randomly renamed and copied to a temporary download folder that is accessible from the Web. This temporary download folder is specified by the 'temp_downloads' application variable defined in ACP > Options. The user is then able to download the renamed file from the temporary folder. Files in the temporary folder should be removed at regular intervals manually or via a scheduled task on the Web server. By renaming the file, it makes it difficult for unauthorized users to guess the temporary filename.

When the download file is renamed the following format is used:
randomnumber_sessionid_originalfilename

Initiating the Download

When a user clicks on the Filename or Download URL to initiate the download the 'click_download.asp' page is used. The 'click_download.asp' page queries the Content database table to obtain the Filename and Download URL values for the given ContentId record. If a value exists in the Filename field, the user is redirected to the specified filename (which may include a filename, relative, or full file path). If no value is specified for Filename, the user will be redirected to the specified Web Download URL. 

Displaying a Legal Acceptance Notice

Often when downloading any file on-line the user will be prompted to accept terms defined in a license and/or legal agreement.  For this reason the click_download script will check the accept_download_id application variable can be used to set the Content Id of existing content that should be displayed prior to the user accepting (or declining) a file download. The actual verbage and contents of this agreement are the sole responsibility of the site producers and/or owner.

Related File Deletion

When the Content Manager is used to delete a content record, the related file (specified in the Primary Filename field) will be deleted from the Web server.  Files referenced by the Image or Thumbnail fields are not deleted. For more information on managing files on the Web server see, File Management.

 Top ^

Special Content Features

User Ratings

To enable user content ratings, ;use the Content Types Manager (ACP > Content > Content Types) menu. Select the Content Type you wish to enable ratings for, and check the "Enable User ratings" checkbox.  When content of this type is displayed, a link that allows that user to submit a rating will be displayed below the content detail. The label for this link can be modified via the ACP > Options > Language & Labels > content submit rating label.

When the "Submit rating" link is clicked, a pop-up is displayed for the user to select a 1 to 10 scale rating. Subsqently, the average rating can be displayed by selecting the "Avg. Rating" fields in the List and/or Datile Page options of the Content Type Settings. Users can only submit one rating per content item.

"Add to Favorites"

When the Inbox facility is enabled, the "Add to Favorites" link wil also display below the content detail.  The "Enable Inbox" setting and "Add to Favorites" label can be updated via the ACP > Options menu.

"Send to a Friend"

Within the content you can link to the "sendtofriend.asp" page to enable a basic send-to-a-friend script. Pass the URL value in the 'linktosend' parameter. For example: href='sendtofriend.asp?linktosend=content.asp?ContentId=100'

Using RSS and ATOM (XML)

Functionality is provided to parse and display standard RSS 1.0, RSS 2.0 and ATOM feeds. This will enable the content of the feeds to be displayed as a content list (full page), or as an include panel within content.

Reading / Displaying RSS and ATOM

feed_read.asp (displays feed in full page)
i_feed.asp (include panel for within content)

Parameters

fetch - full url to be parsed and displayed
ftype - values: rss | atom
max_chars - limits the number of characters per item - value: n
no_html - removes any html code from feed - values: 1 (true) | 0 (false)
max_items - limits the number of items retreived - value: n (no_html must = 1)

For "feed_read.asp" the parameters should be passed in the URL:

Examples:

feed_read.asp?fetch=http://www.somesite.com/rss.xml
feed_read.asp?max_items=10&fetch=http://www.somesite.com/rss.xml
feed_read.asp?fetch=http://www.somesite.com/rss.xml&no_html=1&max_chars=200

For "i_feed.asp" the parameters should be made available in the ASP request.cookies object. Set the cookies using before referencing the "i_feed.asp" include.

Example:

<%
':: set feed params
response.cookies("fetch")="http://www.aspapp.com/library/contenttypeproduct.xml"
response.cookies("max_items")=5
response.cookies("max_chars")=40
response.cookies("no_html")=1
%>
<!--#include file="i_feed.asp"-->

Writing / Publishing RSS

feed_write.asp (publishes a content list in RSS format)

Any of the site's content can be publishing in RSS 2.0 format using the feed_write.asp script. Either the "CatId" or "ContentType" parameter must be passed in the querystring so that the desired content and filtered and published to the RSS file.

Examples:

feed_write.asp?CatId=102
feed_write.asp?ContentType=News

Once the RSS feed is generated, it is written to the /library/ folder and named according to the related ContentType and Category. For example, feed_write.asp?CatId=102 would be published to an XML (RSS) file named: "library/rss2contenttypecatid102.xml"

Displaying Ads in Content

The location of ads within each Content Type can be also be set via the Content Types Manager (ACP > Content > Content Types). Select the Content Type you where the ads should be displayed, and then selecl the location for the List and Detail pages. For more information, see the Ad Management section

 Top ^

 

CMS Usage Scenarios

Classifieds Section

1. Create a Category Group named "Classified Categories"
2. Add categories to this new "Classified Categories" type
   • ie; For Sale, For Rent, Help Wanted, Etc..
3. Create a new Content Type named "Classified Ad"
   • Limit categories to the "Classified Categories"
   • Enable user posts and file uploads
   • Select the appropriate fields for the "Classified Ad"
   • Add custom fields as needed

Downloads Library

1. Create a Category Group named "Download Categories"
2. Add categories to this new "Download Categories" Group
   • Applications, Screensavers, Utilities, Etc..
3. Create a new Content Type named "Download"
   • Limit categories to the "Download Categories" type
   • Enable user posts and file uploads for admin level users
   • Select the appropriate fields for the "Download"
   • To display an acceptance agreement see,
   • To enable secure access to downloads see,

Business Listing Directory

1. Create a Category Group named "Directory"
2. Add categories to this new "Directory" Category Group
   • Services, Restaurants, Shopping, Etc..
3. Create a new Content Type named "Listing"
   • Limit categories to the "Directory" Type
   • Enable user posts
   • Select the appropriate fields

Job Postings

1. Create a Category Group named "Job Listing Categories"
2. Add categories to this new "Job Listing Categories" Category Group
   • Administrative, Technical, Management, Etc..
3. Create a new Content Type named "Job Listing"
   • Limit categories to the "Job Listing Categories" Group
   • Enable user posts for the user level that will post listings
   • Add additional custom fields as needed
   • Select the appropriate fields for add/edit, list and display

Knowledge Base System

1. Create a Category Group named "KB Categories"
2. Add categories to this new "KB Categories" Category Group
   • Installation, Configuration, Software, Etc..
3. Create a new Content Type named "KB Article"
   • Limit categories to the "KB Categories" Group 
   • Enable user posts for the user level that will post articles
   • Add additional custom fields as needed
   • Select the appropriate fields for add/edit, list and display 

 Top ^

E-commerce

To enable e-commerce, see ACP > Options > Enable/Disable > Enable E-commerce. All e-commerce features are managed via the ACP > E-commerce menu.

 

Creating a Product Catalog

Create E-commerce Categories

To define categories for the product catalog, use the 'IsCommerce' field of the 'CatTypes' database table. This field can be set or removed via the ACP > Categories > Edit Category Types menu. When a Category Type is marked as "Use for E-commerce", these are the categories of items will be made available. 

Defining Items

To add a product, select a category from the ACP > E-commerce Manager > E-commerce Categories list. Next, click the "New Item.." link to display the E-commerce Item form.

The following fields are defined for each item (required fields are in BOLD):

• Category: Option list based on the "Use for E-commerce" Category Type
• Item# : A one word (no spaces) unique identifier for the item
• Name: A short title/label for the item or service 
• Short Description: The brief (up to 255 characters) description of the product.
• Full Description: A full detail (HTML code) of item, specifications, etc..
• Thumbnail: Path to a small product image
• Primary Image: Path to a full size product image
• Attributes (1,2,3): Define item variants (multiple SKUs)
• Collapse SKUs: When checked, SKUs will display in drop-down list
• Display: When checked the item is available (commerce.asp)
• Start Date: The (optional) date the item will start displaying
• End Date: The (optional) date the item will stop displaying
• Taxable: Tax the item when applicable to the Tax tables

Once an item is added, by clicking the "Insert" button, SKU(s) for the item will be defined. SKU's are individual item units that define price and item variants.  SKU's are used to detail attribute, price and inventory information about that product.  Every product must have at least 1 SKU, but for most products several SKU's will be defined.

Defining Item SKUs

Each SKU has several associated fields...

• SKU - A unique one word(no spaces) identifier, up to 20 chars in length.
• Price - The dollar amount associated with this SKU.
• Description - Up to 60 chars, optional string to be displayed in lui of attributes list.
• Avail. Qty - Current inventory amount.

Attributes are used to define specific traits that differentiate a product. For example: 

• Size (Small, Medium, Large)
• Color (Black, White)
• Flavor (Vanilla, Chocolate)
• Diameter (6",8",10")
• Type (Gold, Silver)
• Gender (Men's, Women's)

Simple Items (1 SKU, no Attributes)

A "simple" product is one that has a no varying attributes. Simple products have 1 product identifier(Item#) and a matching item variant(SKU).

Complex Items (multiple SKUs, up to 3 Attributes)

A "complex" product is one that has varying product attributes such as size, color, or flavor. For complex products, you can provide up to 3 varying product attributes. Complex products have 1 item identifier (Item#), and several item variants (SKU)

After you have defined the item attributes, you can opt to display these attributes as either "Radio buttons" or "Select" (drop-down) lists.

If all Item SKU's will be the same price drop-down lists can be used, but if each SKU will vary in price it is recommended to uncheck the Collapse SKU's checkbox. The next step is defining a unique SKU to identify each combination of the attributes.

 

Selling Services & Soft Goods

A side from physical hard goods, the E-commerce facility provides a means to sell less tangible items such as services, software or tickets. In this scenario, the Items and SKUs are defined in the same manner as described above.

For More Information, see Downloadable Items

Selling Subscriptions & Paid Memberships

Publishing "subscriber only" content is a common scenario for portal Websites. The E-commerce facility ties to the CMS (Content Management) portion to support this type of scenario.

To create subscription based content, first decide on the required subscription levels. You may have only 2 levels -- subscriber & non-subscriber, OR you may have several subscription/membership levels and content for each level (ie; "Basic", "Preferred" & "Premium").

Once you have determined the membership (subscription) levels, each level must be added as a SKU via the E-commerce Manager.  Do not add levels that do not require payment (ie: non-subscribers that will access free content).  Each membership SKU must follow this naming convention..

• mem_01 (for the lowest level)
• mem_02 (..)
• mem_03 (for the highest level)

Since each E-commerce Item, can have 1 more SKU's, there are 2 ways the membership "products" can be added. If there is only 1 subscription level, simply create an Item named "mem". Also, name the SKU for this Item "mem_01"...

1. ACP > E-Commerce > Select the "Membership/Subscription" Category
2. Click the "New Item".. link and define fields..
   • Item# = "mem"
   • Name = "Basic Membership"
   • Description = "Join our site to access all content.."
   • Check the Display checkbox
   • Click the "Insert" button
3. Define the SKU fields..
   • SKU = "mem_01"
   • Price = "20.00"
   • Unit Label = "lifetime membership"
   • Click the "Add SKU" button

Now the "Basic Membership" subscription is available. When a visitor attempts to access content that requires an Access level of 1, there membership status will be checked. If they have purchased the "Basic Membership", there Access level will be set to 1 and they will be able to access the content. If they have not purchased the "Basic Membership", they will be prompted to "login" or "upgrade".

An alternate option for adding membership "products" for multiple subscriber levels is to add each level as a separate Item SKU...

1. ACP > E-Commerce > Select the "Membership/Subscription" Category
2. Click the "New Item".. link and define fields..
   • Item# = "mem"
   • Name = "Membership Options"
   • Description = "Join our site to access all content.."
   • Attribute 1 Label = "Membership Levels"
   • Attribute 1 Values = "Silver, Gold, Platinum"
   • Check the Display checkbox
   • Click the "Insert" button
3. Define the each SKUs' fields..
   • SKU = "mem_01"
   • Price = "10.00"
   • Unit Label = "lifetime"
   • SKU Description = "Silver - Access level 1 content"
     
   • SKU = "mem_02"
   • Price = "20.00"
   • Unit Label = "lifetimep"
   • SKU Description = "Gold - Access level 1 & 2 content"
     
   • SKU = "mem_03"
   • Price = "30.00"
   • Unit Label = "lifetime"
   • SKU Description = "Platinum - Access all content"
   • Click the "Add SKUs" button

For more information on restricting access to specific content, see the Restricting Access to Content section.

 Top ^

Defining Shipping and Tax Settings

Shipping Methods and Cost
Shipping cost can be calculated and added automatically to orders. If you'd like the site to calculate the shipping cost for each order, there are 2 ways that the cost can be determined. First consider the different methods that are used for shipment of your products. Many retailers only provide one, standard shipping method. Once you entered all the different shipping methods, you can now set-up shipping costs related to each of those shipping methods. The Back-office > Shipping and handling page lets define and edit order-based shipping cost (flat rate), and/or per item shipping cost.

Sales Tax
Depending on the state(s) in which your business collects sales tax, you can define tax to be charged on a state or postal code basis. Users who select these state(s) or postal code(s) for billing, will be taxed at the corresponding rates you define in the Tax administration page (admin_ectax.asp). For more information on Retail Sales Tax Rated, go to http://www.taxadmin.org.

 

 Top ^

The Checkout Process & Payment Gateways

Authorize.net

Scripts are provided to interface the product catalog and shopping cart with the Authorize.net Payment Gateway. The Authorize.net related pages (checkout.asp, confirm_AUTHNET.asp) use AIM (Advanced Integration Method) to interact with Authorize.net's gateway server. The 'confirm_AUTHNET.asp' page initiates a transaction by silenting posting (via XMLHTTP) the required transaction information to Authorize.net. The gateway server at Authorize.net processes the transaction, and then transmits the results of the transaction to the 'confirm_AUTHNET.asp' page. The 'confirm_AUTHNET.asp' page then responds based on the results of the transaction. If successful, the order is marked 'confirmed' in the application database and is ready for processing by the merchant.

Requirements:

1) SSL encryption (Thawte, GeoTrust, etc..) must be installed on the Web server to enable https.
2) An existing merchant account for credit card acceptance and Authorize.net account. The merchant and site developer/integrator should understand and verify any Authorize.net settings such as security, test vs. live mode, AVS settings and referrer url's prior to enabling the included scripts.

To enable and configure Authorize.net transactions:

1) Specify a valid Authorize.Net login in ACP > Options > E-Commerce
2) Verify the Secure site root and Secure page list (must include 'confirm_AUTHNET.asp') 

How it works: 

A customer navigates or searches product catalog (commerce.asp) and from a product detail clicks the "Add to cart" button.

The 'addtocart.asp' page checks for the existance of a shopping cart, or the session(cartid) variable. If none is available a shopping cart is created for the user. Once there is an existing shopping cart, the item is added to the shopping cart, and the user is redirected to the 'viewcart.asp' page.

Next, from the 'viewcart.asp' page the user can view their active shopping cart, remove or change item quantities, or start the checkout process by clicking the "Proceed to checkout" button.

The 'checkout.asp' page first verifies that the customer is logged in and that a session(user_id) is available. If the user is not logged in they are redirected to the 'login.asp' page. Next, the 'checkout.asp' page first verifies that a valid, non-empty shopping cart (cartid) is available. The cartid variable can be passed to the checkout.asp page by url, form post, or in the session object.

The customer specifies there billing and shipping address information for the order. The billing address is pre-populated with any user data that exists for the customer. The customer can also examine their current item total (based on the items in the shopping cart) and select a shipping method.

When the customer clicks the "Next" button, the 'confirm.asp' page is requested, and an order number is generated (OrderNo) and a record is created in the 'ecOrderInfo' and 'ecOrderItems' database tables. At this point the order status is incomplete (IsConfirmed=0) and requires the user to specify payment information.

Finally the 'confirm_AUTHNET.asp' page confirms order items, billing, shipping and order totals. Specifies credit card information. When the Complete Order button is clicked, the order information is submitted to Authorize.net.

The order data is submitted via a hidden form on the 'confirm_AUTHNET.asp' page. This form contains the following payment fields that are recognized by the Authorize.net gateway server. The values of these fields are mapped to local fields in the 'ecOrderInfo' database table so that order data can also be stored in the application database. The following data is sent to the Authorize.Net gateway using the Microsoft XMLHTTP Object.

Authnet Fields

x_version -- "3.1"
x_login -- application("authnet_login")
x_adc_relay_response -- true
x_adc_url -- application("secure_site_root") + response.asp
x_invoice_num -- the order number generated by confirm.asp
x_tax -- salestax
x_freight - shippingcost
x_amount -- ordertotal
x_description --
x_type -- "AUTH_ONLY" (for authorization only transactions)
x_card_num -- ccnumber
x_exp_date -- ccexpmonth + ccexpyear
x_card_code -- cardcode (input only, this field is not mapped to the application database)
x_first_name -- billfname
x_last_name -- billlname
x_company -- billcompany
x_address -- billaddr1
x_city -- billcity
x_state -- billstate
x_country -- billcountry
x_zip -- billzip
x_email -- billemail
x_phone -- billphone
x_ship_to_first_name -- shipfname
x_ship_to_last_name -- shiplname
x_ship_to_address -- shipaddr1
x_ship_to_city -- shipcity
x_ship_to_state -- shipstate
x_ship_to_country -- shipcountry
x_ship_to_zip -- shipzip
x_ship_to_company -- shipcompany
x_ship_to_email -- shipemail
x_ship_to_phone -- shipphone

When the Authorize.net system receives the data, it attempts to authorize the credit card information and returns the resulting response to the server (silently using the XMLHTTP object) The response collects the following Authorize.net result fields.

x_response_code
x_response_reason_code
x_response_reason_text
x_auth_code
x_avs_code
x_trans_id
x_invoice_num
x_description
x_amount

Once the XMLHTTP Object receives the Authorize.net results, the values are posted via hidden form back to the 'confirm.asp' page. The "complete_order" action of the 'confirm_AUTHNET.asp' page evaluates the results of the payment transaction.

If the payment was not successfully authorized (response_code=2 or 3), a description of the reason for failure is displayed to the user so that they can correct their address or payment information and attempt to resubmit their order.

If a successful payment is verified (response_code=1), the 'ecOrderInfo' database table is updated so that the order is marked complete (IsConfirmed field is set to 1) with a status of new (Status field set to 0). If available the auth_code, ccnumber (masked with *'s), ccexpmonth and ccexpyear are also updated. The 'confirm.asp' page also delete's the users shopping cart ('ecCartInfo' and 'ecCartItems'). A "thank you" confirmation message is displayed to the user and provides a link to their order receipt (receipt.asp). All orders can be viewed and managed via the Order Management area.

Other Authorize.net specific options such as test/live mode, referrer url's, email notification and custom order fields can be referenced by logging into the merchant's account management area on Authorize.net. The portal application developer or integrator should also test and verify that any required security and fraud detection features are in place before using the site to accept live transactions.

 Top ^

PayPal Integration

Scripts for use with PayPal IPN system are also included. This script integrates the application's product catalog features with PayPal's Shopping Cart system. All shopping cart and order management functions are managed at the PayPal end, so the portal's shopping cart, shipping options, tax options and order management functions are not applicable when PayPal is used. For more information on the PayPal Shopping Cart including custom shipping and tax options can be found on the PayPal Web site.

PayPal Requirements:

1) An existing PayPal Premier or Business account for payment acceptance. Any PayPal settings should be configured prior to integrating the portal application.

To enable PayPal:

1) Specify a valid PayPal Email (Selling) Account in ACP > Options > E-Commerce
2) Verify the Secure site root and Secure page list (must include 'confirm_IPN.asp') 

For the focus of this section is and the confirm_IPN script, we'll show integrating a "shopping cart" with PayPal, eventhough your site may involve intregration with donations or subscriptions.  As of this writing, the application does not provide support for recurring subscription on PayPal.

Product Catalog and Shopping Cart
The user browses products in the catalog and opts to "Add to Cart". The product is added to the shopping cart by the form on the products.asp page. Although PayPal offers a shopping cart, the focus of this article will describe using the shopping cart and then passing the order information (without item details) to PayPal.

Checkout
From the shopping cart (viewcart.asp), the customer opts to "Proceed to Checkout".  This button passes the current shopping cart information to 'checkout.asp' for order creation and commences the checkout process. Before passing the order to PayPal, the customer will complete their address information and if applicable select a shipping method. To proceed the "Next" button is clicked.

Payment and Confirmation
Next the complete order information including item detail(s), address information and order cost is add to the local database and displayed to the customer on the 'confirm.asp' page. Eventhough the order information exists in the local database, the status field in set to 0 indicating that the order is not complete. From this page, the user can return to the previous step (checkout.asp) or complete their order by clicking the "Complete Order" button. This button will submit the form contents to PayPal (https://www.paypal.com/cgi-bin/webscr) for processing.

The following hidden fields exist in the form:

 

<input type=hidden name=cmd value='_xclick'>
<input type=hidden name=business value='<% =application("paypal_acct") %>'>
<input type=hidden name=notify_url value='<% =application("secure_site_root") %>confirm.asp?action=complete_order'>
<input type=hidden name=return value='<% =application("secure_site_root") %>confirm.asp?action=thank_you'>
<input type=hidden name=amount value='<% =ordertotal %>'>
<input type=hidden name=invoice value='<% =orderno %>'>
<input type=hidden name=item_name value='Order #<% =orderno %>'>
<input type=hidden name=custom value='<% =cartid %>'>

You'll see that only order total information, not item details are passed to PayPal.

Handling the PayPal Response
Once the customer makes the payment, PayPal will request our site via the url specfied in return_url field. The request is invisible to the customer and happens "behind the scenes". When PayPal requests the return_url (confirm.asp?action=complete_order) on the site, it will be posting a form with various fields and data. Request.form is used so that your site can capture this data and then return it back to PayPal for validation. To send the data back to PayPal, we'll be using Microsoft's XMLHTTP object which is automatically installed on Windows servers. It is important that the 'confirm.asp' page is not restricted by permissions or session variables since PayPal is requesting this page "silently" via HTTP.

Here is the .asp code that handles the response from PayPal..

' store what PayPal is sending in a string and append the cmd variable
str = request.form & "&cmd=_notify-validate"

' post back to PayPal system for validation
set objHttp = Server.CreateObject("Microsoft.XMLHTTP")
objHttp.open "POST", "https://www.paypal.com/cgi-bin/webscr", false
objHttp.setRequestHeader "Content-type", "application/x-www-form-urlencoded"
objHttp.send str

Next the form variables that are sent from PayPal are captured and mapped to local variables ...

response_text = objHttp.responseText
payment_status = lcase(request.form("payment_status"))
pending_reason = request.form("pending_reason")
receiver_email = request.form("receiver_email")
cartid = request.form("custom")
orderno = request.form("invoice")
ordertotal = request.form("payment_gross")
authnum = request.form("txn_id")
bill_email = request.form("payer_email")

Now, the confirm.asp page will wait for an HTTP 200 status coming back from PayPal. The 200 status along with the response text will captured from PayPal via the XML object. The 'confirm.asp' (case action=complete_order) page then calls the "handle_ipn_response" subroutine that is located in the source code at the top of the confirm.asp page.

if (objHttp.status <> 200 ) then
   b_error = true
   error_list.add "no200", "A 200 Status was not returned from PayPal"
else
   ':: call sub at top of page
   handle_IPN_response
end if
set objHttp = nothing

Activating IPN on PayPal
To active IPN for your PayPal merchant (seller) account, you must login and select "Profile" > "Instant Payment Notification Preferences". Then you need to click the "Edit" button in the PayPal site to enable "Instant Payment Notification" and set the "Instant Payment Notification URL" to the 'confirm.asp?action=complete_order' script on the site:

http://www.mysite.com/portal/confirm.asp?action=complete_order

Testing
PayPal doesn't provide a test mode or login, so the only way to test the purchase of items on your site is to use a separate PayPal buyer's account.

References:
PayPal IPN Guide (http://www.paypal.com/)

 Top ^

Order Management

The 'ACP > E-commerce > Orders' section is used to display and track existing order records in the 'ecOrderItems' database table. This page will display all orders wether or not the order has been completed. An incomplete order is indicated by the value of the 'ecOrderItems.IsConfirmed' database field. An IsConfirmed value of 0 (or NULL) would indicate that the customer (user) began the checkout process, but did not confirm the order. An IsConfirmed value of 1 would indicate that the user successfully confirmed their order ('confirm.asp').

The merchant may opt to track orders by updating the status of the each order as it is processed. Otherwise all completed order will remain marked with a status of new (the value of the 'ecOrderItems.Status' database field = 1), and all incomplete orders (not confirmed) will be marked with a status of incomplete (-1).

 Top ^

Forums

To enable the discussion forums, see ACP > Options > Enable/Disable > Enable Forums.

Creating Forums

Forums can be created via the Forums UI (forums.asp) or via the Forums Manager (ACP > Forums) and click the 'create a new forum' link. Only other users that have Access level of 3 or greater can be selected as Forum moderators. 

Users can view the forums, read and post topics, and reply to topics. Users can also later edit there own topics and replies. To enable some of the message editing features the 'i_formatting.asp' include page contains several Javascript functions used in the forums.

 Top ^

The Calendar page (calendar.asp) displays the Calendar's current month's view, and events contained within.

Monthly, weekly and daily views

The Calendar provides various views to access the event information that is stored in the 'Events' and 'EventOccurs' database tables. Users can select (click) any given date for a detailed daily view. Users can also navigate to then "previous" and "next" time periods (month, day), and filter the events by type. The event types are defined by the "Event Types" category in the ACP > Category Manager. The Category Type must be named "Event Types" for the event type selected list to be created.

Add and update events

Ad-hoc event data (Event name, location, description and date/time occurence) can be added by clicking the 'Add Event' link in the Calendar's daily view. The Calendar supports event recurrence by allowing the user to define the length and interval of any given event. Any given event can be set as:

1) "Private" -The event will only display on the Calendar of the user that added the event.

2) "Public" -The event will display on the calendar to all users (that are not logged in).

3) "Busy" - The title and event details will not display on the Calendar, but 'username busy' displays.

There is no means via the ACP to edit the Calendar and Events. This can only be done from the stanard UI via 'calendar.asp'. Users can only update (modify) events that they have added.

Event Registration

The Event Registration is a basic facility that allow users to "sign-up" for a particular event. To make events "registerable" the "Enable user registration" checkbox must be checked when the event is added or updated.  Once registration is enabled, users can click the "Register.."  button on the Event Detail view (calendar.asp).  The Event Registration page (upd_userevents.asp) is then shown with form fields for the user to complete. The 'Registration code' field is an open text field where users can refer to pertinant data (ie; ad #, account #, reference code, etc..).

Once a user has registered for an Event, the registered user list is accessible from the ACP > Registrations menu.

 Top ^

To enable this feature, see ACP > Options > Enable/Disable > Enable Affiliates. 

The Affiliate Management facility provides a way to track affiliate "partners" that agree to link to the site.  Each time a hit is received from an affiliates' site, the associated click through (hit) is recorded in the site database. As a performance incentive, the top referring sites can be displayed on the Homepage using the 'i_affiliates.asp' page. (For more information see the Homepage Layouts section)

Affiliates can be added using the 'submit_affiliates.asp' page. To approve an affiliate, the 'admin_affiliates.asp' page is used (ACP > Affiliates). When an affiliate has joined and been approved they can link to the 'refer.asp' page with their 'aff_id' in the URL. This page will increment their "hits" to the site, and then redirect to the home page.  Once an affiliate is approved they should be notified of the correct link to use on their site.

For example, this is the link that the affiliate with aff_id of 1 would use:
http://www.mysite.com/portal/refer.asp?aff_id=1

 Top ^

Database Model

List of Database Tables

Affilites
This table is used to manage the affliates/referrer program.

AuctionBids, Auctions
These tables are used to manage the auction/marketplace system.

Banners
This table is used to manage the tracking and display of ads throughout the site.

Cats, CatTypes
These tables establish the hierarchy of Categories and Category Types (groups of categories).

Content, ContentTypes, ContentAttributes, ContentAttributeValues
These table are used to manage the content area. ContentTypes can be used to define different types of content. Content can also be related to a category (CatID). The submitter of the content is identified by user_id.  The ContentTypes.CatTypeId field is the basis of category filtering on a ContentType.

Disc_Forums, Disc_Replies, Disc_Topics
These tables are used to manage the forums / bulletin boards. The top level table is 'Disc_Forums', that has one or more related records in 'Disc_Topics', that may have one or more related records in 'Disc_Replies'. The submitter of the forum, topic or reply is identified by user_id.

ecProduct, ecSKU, ecShipCostSKU, ecShipMethod, ecTax, ecCart, ecCartItem, ecOrderInfo, ecOrderItem
These tables are used to enable the E-Commerce features including product/item catalog, shopping cart, checkout, shipping, taxes and orders.
MessageRecipients, Messages
These tables are used to manage the internal messaging features. The submitter of the message is identified by Messages.user_id and the intended recipients are defined by 1 or more user_id's in MessageRecipients.

Newsletters
This table is used to manager the newsletter features. The submitter of the newsletter is identified by user_id.

Events, EventOccurs
This table is used to manager the calendar features. The submitter of any given event is identified by user_id.

Surveys, SurveyQuestions, SurveysAnswers
These tables are used to manage the survey/polling features. The "topmost" table is 'Surveys'. A 'Survey' can have 1 or more 'SurveyQuestions', and 'SurveyQuestions' have 1 or more 'SurveyAnswers'

SurveyResults
This is where the results of survey submission are stored. The survey responder is identified by user_id.

Users
This table is used to manage all "registered" users and for login validation. The "user_id" field also relates the user to data stored in the 'Links', 'Content', 'Classifieds', 'Disc_Forums', 'Disc_Topics', 'Disc_Replies', 'MessageRecipients', 'Messages', 'Surveys', 'Events' and 'Auctions'. Using the "user_id" any data that is posted by or intended for any given user can be tracked.

UserContent
This table is used to track and manage a user's favorite links.

 Top ^

Security Settings

User Interface

Section	Page	Description	Access Level
Home page	default.asp	Global application settings, labels and variables	(none)
Content	content.asp	Sitemap, categories list, content list and detail	(none) *
	submit_content.asp	Submit/author content, file uploading	1 **
Forums	forums.asp	View forums, topics and replies	(none)
		Post/edit topics and replies	1
		Create/moderate forums	3
Surveys	surveys.asp	Submit vote and view results	1
Chat	chat.asp	Join chat room	1
Inbox	user_profile.asp	View, add, edit own user data	1
User	user_public.asp	View another user's public profile	1
E-commerce	commerce.asp	View products and add to cart	(none)
	checkout.asp	Checkout and complete order	1

 

* Access level can be set on a per content item basis

** User authoring settings are based on content types defined in the ACP

 

Administration Interface (ACP) Security Settings

Section	Page	Description	Access Level
ACP	admin.asp	Access admin area	4
Global Options	admin_app.asp	Global application settings, labels and variables	5
Style	admin_style.asp	Default style sheet properties and attributes	4
Wrapper	admin_headfoot.asp	Header and footer include pages, site layout and menus	4
Home Page	admin_layout.asp	Home page (default.asp) layouts and content	4
File Manager	pu_fileman.asp	View, upload, delete files/folders at root	5
File Manager	pu_fileman.asp	View, upload, delete files/folders below root	4
Users	admin_users.asp	View, add, edit user data	5
Categories	admin_cats.asp	View, add, edit site categories and types	4
Content	admin_content.asp	View, add, edit site content items	4
Content Types	admin_contenttypes.asp	View, add, edit site content types	5
Newsletter & Messages	admin_newsletters.asp	View, edit, send newsletters and application messages	4
Surveys	adm_surveys.asp	View, add, edit surveys	4
Forums	admin_forums.asp	View, add, edit forums, topics and replies	4
Ad Management	admin_banners.asp	View, add, edit ad placements	4
Event Registration	admin_userevents.asp	View, add, edit calendar event registrations	4
Auctions	admin_auctions.asp	View, add, edit auctions and bids	4
E-commerce	admin_commerce.asp	View, add, edit commerce items, settings and orders	4
Affiliates	admin_affiliates.asp	View, add, approve affiliates	4

For more information on Users and security see: User Management