Portals and Hosted Files

12 Portals and Hosted Files This chapter introduces Progress Rollbase Portals, portal pages, portal visitors setup and management, portal access control and login/authentication and recommended guidelines for planning and building Portals including configuring links to other portal pages within portals, assigning destination pages and working with page properties. It also covers the concept and usage of Hosted Files. For details, see the following topics:

•

Rollbase Portals

•

Hosted Files

Rollbase Portals Portals are essentially external-facing web applications that are built using the same tools and components as standard Rollbase applications. Portals typically run as a part of a corporate website or intranet. They can be used to display dynamic lists of records and view record data, allow creation of records through custom forms and invoke triggers and custom business logic without requiring website visitors to have named Rollbase user accounts. You can include any number of Portals with an Application and publish them as a part of an Application's XML (see Chapter 16. Publishing and Distributing Applications for more details). Portals are different from normal Rollbase applications in three significant ways:

• Portals can be accessed by anyone with internet access, though they can be password protected with named accounts

Rollbase: Progress® Rollbase® in Action: Version 2.2

345

Chapter 12: Portals and Hosted Files

• Portals do not run within the normal Rollbase user interface. Rather, they consist of a set of pages that are linked together to form a cohesive website

• Portals can adopt the look and feel of any existing website where they can be embedded (in some cases portals can be used to power a domain's entire website; for an example of this see http://www.geo30.com) The following diagram illustrates the differences between Rollbase application and portal usage:

Planning and Building Portals In addition to Portal-level settings, a Portal consists of a set of Portal Pages interconnected by links in any order you desire. This gives a developer greater flexibility than is available with normal Rollbase application Pages. However, it also carries a greater responsibility, so planning your Portal strategy in advance is important. Warning: Building a sophisticated and easy to use Portal often requires significant knowledge of web design, HTML, CSS and JavaScript. It is often a good idea to start with a diagram that shows how visitors can navigate through the Portal Pages you intend to create.

Creating a Portal Because each portal visitor cannot select their own language, date format and time zone the way regular users do, portal-level settings will be applied for all portal visitors. Create a portal using the following steps: 1. Navigate to the portal setup page (Setup > Application Setup > Portals)

346

Rollbase: Progress® Rollbase® in Action: Version 2.2

Rollbase Portals

2. Click New Portal. The New Portal page displays:

3. Enter the following information:

• Portal Name: Give the portal a memorable name. • Is Deployed: Exposes the portal to external access; keep this box unchecked until the portal is ready for use. Rollbase: Progress® Rollbase® in Action: Version 2.2

347

Chapter 12: Portals and Hosted Files

• Field-Level Help: If checked, a "?" icon displays next to fields and contains any field-level help that you have defined.

• "Powered by" Logo: Check this box to include a Powered by Rollbase logo at the bottom of portal pages.

• Ajax Calls: If this box is checked, AJAX calls will be allowed to this portal without authentication. Depending on where and how the portal is deployed, this can be a security risk. Please use this option carefully.

• Language: Select the language for the portal pages. • Date format: Select the date format to use in this portal in display and input fields. • Time zone: Select the time zone for this portal. All Date/Time field values will be adjusted to this time zone.

• Description: Provide a description for this portal. • Main Page: Select the default Home page for this portal. Rollbase creates a Main Page automatically for new portals.

• Login URL: Use this setting only for portals embedded into other web sites that require authentication. This is the URL for logging in and the URL that will display when a user logs out.

• Add to Applications: Select the applications to which this portal will be added. 4. Click Save. If you are planning to use a portal as part of your website--rather than embedding it in one of your website's pages using an HTML iframe--you will need to configure the header and footer to adopt the look and feel of your site. See Creating a Custom Header and Footer on page 348 for more information.

Creating a Custom Header and Footer If you do not already have HTML code to use for your Header and Footer, the best way to get started is by picking a Page on your site to use as a template. View the HTML source of this Page and remove any central content where you would like your Portal content to appear. All HTML code above this content should be used as your Header and all HTML code below should be used as your Footer. Tip: You can choose to include the default Stylesheet named Portaltheme.css above the Header in each Portal Page. Follow these general steps to build the Header and Footer of your Portal: 1. If any code in your Portal Header or Footer HTML contains references to external files such as images, JavaScript files, CSS files, or links to other Pages using relative URLs (such as "../images/myimage.gif", "../index.html", etc.), you will need to do one of the following:

• Switch to fully qualified URLs. In other words, always include the full path in your URLs such as "http://www.mycompany.com/index.html."

348

Rollbase: Progress® Rollbase® in Action: Version 2.2

Rollbase Portals

• Include the following tag in the element of your header: …where mycompany.com is your website's URL (i.e., the full path to the directory where your content can be found if the relative URLs were added to the end of it). This base tag tells any relative URLs to use the specified path as the root and is the only way relative URLs will resolve to the right domain. 2. You can use JavaScript code and CSS styles in the Header and Footer, but make sure any URLs to externally referenced files are fully qualified as specified above. In addition, each JavaScript file and CSS file included must itself use fully qualified URLs if you are not using a base tag in your header. 3. If you have enabled the HTTPS setting for this Portal, you either need to be using a base URL with HTTPS support, or you need to make sure that all of the images and files referenced in your Header and Footer have fully qualified HTTPS URLs. 4. You can change the main page by editing your portal's settings. When you are ready to go live with your portal make sure it is marked as deployed and simply provide access to this URL from appropriate places on your website or intranet. 5. You can use merge fields in the Portal's header and footer, such as {!#CURR_USER.firstName}. See Chapter 6. Server-side Code: Templates, Formulas and the Rollbase Query API for more details. When you finish creating settings for your Portal, you'll find a URL to the Main Portal Page on the Portal View Page which looks something like this: http://www.rollbase.com/router/servlet/Portal?c=391197&p=469206&h=false&g=469208

Creating Portal Pages When you create a new Portal, Rollbase creates a new empty Page and assigns it as the Portal's Main Page. To add more Portal Pages, click the New Page link. For each new Page, complete the following info:

• Display name: Provide a unique name identifying this page • "Only logged in portal visitors can access this page": Check this box if you are creating a page that only authenticated portal visitors should be able to access (we will discuss how to set up portal authentication below)

• Page Type: Select the type of page to create from the following options: o • Generic Page: An empty page in which you can embed list views (list of records of a specific object type) and arbitrary web content (HTML, JavaScript, etc)

• Search Results Page: A page used to display the results of a search within a portal • Object View Page: A page to view a single record of a specific object type • Object Create Page: A page to create a single record of a specific object type • Object Edit Page: A page to edit a single record of a specific object type • Object Selector Page: A page shown in a popup window that is used to select related records when using a lookup field in a Create or Edit page

• Login Form: A page specifically designed to allow portal visitors (i.e. Records of an object with the ‘Portal Visitor' attribute) to login and authenticate to a portal

Rollbase: Progress® Rollbase® in Action: Version 2.2

349

Chapter 12: Portals and Hosted Files

• Object Type (not shown for Generic Pages): Depending on the type of page you selected above, you will be presented with different object types to select here that determine what type of object record(s) this page will be dealing with:

• If you selected a Login Form page, you will be presented with a list of objects that have the Portal Visitor attribute; in this way you are creating a login page for a specific type of portal visitor. o

• If you selected any page type other than Generic Page and Login Form, you will be able to choose from all available objects Portal Pages can be shared among different Portals in your Customer. When you create a new Page by clicking on the "New Page" link in a Portal's View page, this new Page is automatically assigned to the selected Portal. Later, you can share that Page with other Portals by using the "Assign Pages" link.

Portal Page Properties The "Actions" column in the list of portal pages offers the following choices:

• View: Preview the selected portal page in a pop-up window. For View and Edit pages you will be asked to select an existing record first

• Edit: Edit the selected portal page in the Page Editor • Clone: Clone the selected page and edit the new page n the Page Editor • Del: Delete the selected page (not available for the main portal page) • Copy to: Clone the selected page and assign it to a different portal • Properties: Set the selected Page's properties; available properties vary depending on the page's type (see below) Page Properties allows you set the following type-specific page attributes: Property

350

Description

Page Type

Page Name

Human-readable page name

All

Only logged in portal visitors can access this page

Portal visitor must be All except Login authenticated, otherwise he/she will be redirected to this portal's Login page

Rollbase: Progress® Rollbase® in Action: Version 2.2

Rollbase Portals

Property

Description

Page Type

Destination Page

Page to redirect visitor to after New, Edit, Login form submission

Automatically redirect to destination page when visitor already logged in

Self-explanatory

Onload

JavaScript code to be invoked All by the DOM "onload" event

Onunload

JavaScript code to be invoked All by the DOM "onunload" event

Login

Portal Page URLs Templates used on portal pages may frequently use URLs to other portal pages. To simplify portal development Rollbase provides UI helpers which for each page may generate:

• Page's URL • Link to page • Page's ID

For Generic or List pages these tokens can be used in UI templates directly. However for View or Edit pages you need to add an ID of the record being edited or viewed (generic token does not include this info for obvious reasons). For that append URL "id" parameter to UI token {!#PORTAL.159007.159009#url}&id={!id}

At run time this will be resolved into full record's URL. Tokens pointing to portal pages can be used in email templates as well.

Using an EVAL Block on a Portal Page The following example uses an #EVAL[ ] block on a Portal page to generate and output an HTML table with a list of records of Object "A" with integration name "a1": Note: To use this example make sure that Portal Visitor role has sufficient access to view records of Object A.

Rollbase: Progress® Rollbase® in Action: Version 2.2

351

Chapter 12: Portals and Hosted Files

Use Page Editor and add Script Component with the following body: #EVAL[ function f1() { var arr = rbv_api.selectQuery("SELECT id,name FROM a1", 1000); var buff = 'IDA\n'; for (var k=0; k More Actions dropdown. Setting permissions for Portal Visitor objects requires careful planning to ensure that portal visitors cannot access information they are not supposed to. For the example from the previous section, you may have the following security requirements:

• Visitors can create, view and edit their own personal visitor information (i.e. their own record). • Visitors cannot access personal records of other visitors. • Visitors can create and view (optionally edit and delete) their own comments. • Visitors cannot access comments created by other visitors. To satisfy these requirements you can set the following permissions on the Visitor and Comment objects: Object

Role

Access Granted

Visitor

Portal Visitor

Create new record

Vistor

Record Creator

View, Edit

Comment

Portal Visitor

Create new record

comment

Record Creator

View

In this design any portal visitor can create a new "Visitor" record - this represents self-registration. But the "View" privilege is granted only to the Record Creator. This means that any authenticated visitor can only view her own personal record. If she tries to access data of another visitor she'll be denied access. Tip:You can assign permissions to the "Record Creator" pseudo-role from the Permissions section of an Object definition's details page. Tip: You can assign permissions through relationship between current Visitor and records the same way as between regular User and records. See Chapter 11 for details.

Creating Portals Without Authentication Consider the following simple Portal example, where a portal visitor can:

• Search a list of products • View a list of search results • View information on a selected product The following diagram shows the required Portal Pages and navigation among them:

Rollbase: Progress® Rollbase® in Action: Version 2.2

353

Chapter 12: Portals and Hosted Files

To create this simple but fully functional Portal, take the following steps: 1. Create a new Portal as described in previous sections that will generate the Main Page. 2. Edit the Main Page and add a Text Search component to it (this will automatically be available in the "Available Components" section of the page editor), along with a template-based welcome message. 3. Create a Search Results Page for the Product object. The system will place a list of Product components onto this Page for you automatically. 4. Create a View Page for the Product Object. Rollbase will place existing Product fields onto this Page by default automatically. 5. Edit the Product View Page and remove or re-arrange Fields as needed. Create an HTML or Script component and, using the merge fields selector in the page editor, add links to the previously created Pages: Main Page and Search Results. Using these links, visitors can navigate through the Portal. 6. Finally, add permissions to view Product Object records to the Portal Visitor Role. Tip: You can create and edit Portal Links in the Page Editor to add explanatory text or images. Warning: Unless the proper permissions are assigned to the Portal Visitor role, visitors your Portal will not be able to view, edit or create records. Make sure to update the Portal Visitor role permissions when creating and deploying portals.

Creating Portals With Authentication Consider the following more complex example, where a Portal visitor can:

• Register for access to a Portal • Login to that portal through login Page • View his/her information • Create comments • View list of his/her own comments (but not comments created by other visitors) To build such a portal you need to first create the following:

• An Object called "Visitor" with the Portal Visitor and Contact attributes. • An Object called "Comment" with a Text Area field • A One—Many Relationship between Visitor and Comment. The next step is to create a Portal and several portal pages. The following diagram illustrates the required Portal Pages and the typical navigation between them:

354

Rollbase: Progress® Rollbase® in Action: Version 2.2

Rollbase Portals

To create this Portal, create the following Portal Pages: Page

Object

Page Type

Description

Authentication Required

Main

None

Generic

Has links to Login No and Self-Registration Pages

Self-Registration

Visitor

New record

Allows new visitor No to enter some personal info, including login name and password

Login Page

Visitor

Login

Contains Login form

Visitor View

Visitor

View

Displays personal Yes info and list of comments created by current visitor

Rollbase: Progress® Rollbase® in Action: Version 2.2

No

355

Chapter 12: Portals and Hosted Files

Page

Edit Visitor

Object

Visitor

Create Comment Comment

Page Type

Description

Authentication Required

Edit

Allows existing visitor to change some personal info, including login name and password

Yes

New record

Allows creation of Yes a new comment record. Current visitor will be automatically attached to the new comment record (and vice versa).

Hosted Files As with most websites, in portals you often need to make use of and reference files such as images, Flash movies, JavaScript, CSS, etc. These files are typically referenced in web pages through , and other HTML tags. Rollbase provides a convenient way to host and reference arbitrary files through a mechanism called Hosted Files. For example, using this feature, third party and custom JavaScript and CSS libraries can be uploaded and use by your portals to create a unique user experience and look and feel. JavaScript Hosted Files can be very useful in development of both client-side and server-side scripts. You can preview these files while working in Formula editor using drop-down list "View JS Hosted Files". Note: Hosted files can be included as part of published applications just like other application components (e.g. Portals, Objects, etc.) Note: Hosted files are most often used in Portal pages but can also be used in Rollbase Object pages. You can prepare CSS Stylesheet with all tags used by Rollbase UI (see Appendix D for details) and upload this CSS as Hosted File. In this case you could use hosted CSS to customize appearance of all pages in your Customer. See Chapter 14 for details. You can reference hosted files using merge fields in various scenarios such as in Template and Formula fields, HTML and Script components in pages, as well as within email and document templates. Using hosted file tokens in email templates provides a convenient way to add email attachments. See Hosted File Tokens on page 357 and Using Hosted File Tokens on page 358for more information.

Managing Hosted Files From the Hosted Files Page you can create, view, update and delete hosted files.

356

Rollbase: Progress® Rollbase® in Action: Version 2.2

Hosted Files

To modify text-based Hosted files (JavaScript, HTML, XML) you can simply modify text on web page without uploading a new file. To upload and manage hosted files: 1. click the Hosted Files link in the Applications Setup page (Setup > Applications Setup > Hosted Files). For convenience, this link is also shown on each Portal's details page.

2. To create a new hosted file, click the New Hosted File link, then enter: The size of a single uploaded file cannot exceed maximum allowed for Rollbase installation (5MB by default).

• • • •

Display name Browse to upload the file Description (optionally) Select applications to which this file should be attached

Hosted File Tokens The following table summarizes usage of merge field tokens corresponding to different types of hosted files:TOKEN NAME WHERE USED REPLACED WITH Filename Filename [image] Filename [text] Token Name

Where Used

Replaced With

Filename

Anywhere, for example: URL to the file hosted by {!#HOSTED_FILE.7034090} Rollbase Note: When used in an email template, the hosted file is added to the email as an attachment instead of as a URL in the email body

Filename [image]

Any Template field or HTML tag with URL to page-level HTML or Script image file. This works very component, for example:

Filename [text]

Any Template field or page-level HTML or Script component, for example: {!#HOSTED_FILE.13687907#text}

Rollbase: Progress® Rollbase® in Action: Version 2.2

Entire text of the hosted file. This approach has many possible usages such as using custom JavaScript libraries in server-side formulas.

357

Chapter 12: Portals and Hosted Files

Using Hosted File Tokens In the Template Helper UI when editing any of these components, select the Hosted Files group and then select the merge field token corresponding to the desired hosted file and paste it into your template.

Example Using Tokens in Formulas The following example illustrates the usage of hosted JavaScript files in server-side formulas (using the Filename[text] format described above). Assume you have created and uploaded a JavaScript file that contains: function my_func(x, y) { return x+y; }

You can create a server-side formula which uses this file by using the hosted file's Filename[text] merge token and then invoking the function, as follows: {!#HOSTED_FILE.499203#text} my_func({!num1}, {!num2});

If you use the formula debugger to debug this formula, it will be parsed in the following form: function my_func(x, y) { return x+y; } my_func(100, 200);

Important: When using JavaScript functions in server-side formulas, do not use a stand-alone return statement; doing so will cause an error. The result of the very last JavaScript statement (typically a function call) will be used as the formula result. Please see Chapter 6. Server-side Code: Templates, Formulas and the Rollbase Query API for more details.

358

Rollbase: Progress® Rollbase® in Action: Version 2.2