Crystal Reports 9 The Complete Reference PHẦN 9 doc

As ePortfolio is entirely Web based, and because Crystal Decisions providescompletely open source code for ePortfolio, you have complete flexibility to customizeePortfolio to your exacti

Each parameter in the report is listed, with currently set values displayed A newly

added report normally shows EMPTY in the Values column Click the word EMPTY to

obtain the dialog box for setting initial values for that parameter

The Set Initial Values dialog options vary according to the way the parameter was

created in the report, allowing for single, multiple, and/or ranged parameter values

When you have set the initial values for a given parameter field, click OK to save these

values and return to the main Parameters tab

When you have established values for each parameter desired, click Update

(bottom right) before looking at other tabs

Filters Tab

You can create or modify existing record and group selection formulas on this tab If

users have the rights to schedule a report, they will be able to modify these, but all other

viewing methods will run the record and group selections exactly as entered here

The Crystal Management Console does not check for correct Crystal syntax in the selection formula If you update an incorrect formula, the resulting report instances will not run successfully.

You can also add processing extensions to the report on this tab A list of availableprocessing extensions is on the left, and the list of processing extensions to be used forthis report is on the right.The left and right arrow buttons are used to include and excludeprocessing extensions, while the up and down arrow buttons are used to specify theexecution order for the included processing extensions

Be sure to click Update (bottom right) to save all of your changes before viewingother tabs

Processing Extensions are a new Crystal Enterprise 8.5 feature that allows designed processing to be performed on a report when it is run Your organization must have designed or purchased processing extensions, and installed them properly, to make use of these options.

custom-Schedule Tab

This tab offers scheduling options similar to those in either the Crystal Publishing Wizard

or the scheduling page of ePortfolio You can schedule instances to run on a regularcalendar basis, or you can indicate that the report will be available for on-demandviewing

When you use this tab to schedule a report, it uses the values currently set in the other tabs For example, if you would like to schedule a report to be produced in Excel format, you must first use the Format tab to set the report format before completing the Schedule tab So be sure to set your database logon information, parameters, filters, destination, and format before scheduling a report.

Each calendar option, when selected, provides additional prompts for furtherdefining the schedule In all cases (except for the “Now” option), you will be askedfor a Start Date, which is the date and time you want to run the report, as well as anoptional End Date, which is the date and time past which you would not want thereport run You will also have the option to select “with events.” This combines withthe scheduling information to delay processing until a specific event or events havebeen triggered For example, a weekly report could be scheduled to run every Fridaynight at 11:00P.M.but only after an event is triggered that signifies that the database

synchronization has been completed Events may also be set up to trigger upon the

completion of the report processing

On Demand Choose On Demand if you do not wish to schedule any recurrent

instances at this time This allows users with run rights to view and schedule the

report on demand from their Enterprise environment

Once Choose Once to run the report immediately or at a specific time in the future.Daily Choose Daily to see three suboptions:

■ Once each day

■ Every X hour(s), N minute(s)

■ Every X day(s)

Weekly The Weekly option allows scheduling on any combination of the seven days.Check boxes are provided for easy selection For example, three clicks could schedule

a report to run on Monday, Wednesday, and Friday of each week

Monthly Choose Monthly to see five suboptions:

■ On the Nth day of the month For example, on the fifteenth of every month

■ On the Nth X of the month For example, on the second Friday of every month

■ Every N months

■ On the first Monday of the month

■ On the last day of the month

When you have established any recurrent or on-demand scheduling, click Update(bottom right)

If you created a recurrent schedule, you can view the resulting instance on the

The destination choices for a report instance file are

■ Default Kept on the Crystal Enteprise server and managed by the APS.

■ Unmanaged disk Written to any accessible disk location.

■ FTP Transferred via FTP to any accessible FTP server.

■ Email (SMTP) Attached to an e-mail message and sent via SMTP.

■ Printer Written directly to a printer.

Once you’ve selected your destination, click Update (bottom right)

Once you’ve selected your format, click Update (bottom right).

Limits Tab

This tab defines the rules for limiting the number of instances kept in the system There

are two basic rule types for deleting instances: delete excess instances when there are

more than N instances and delete instances after N days These two types of rules may

be applied for users and/or groups, as well as globally.For example, a global rule may be

to delete excess instances over 100, and a specific rule may be to delete any instances more

than seven days old for a specific management group

To add rules, click the appropriate Add/Remove button on the right side.The

resulting page has three possible modes: Add/Remove Groups, Add Users, or Remove

Users Use the arrow buttons in the middle to move the desired groups and/or users

into or out of the report’s list box When you are finished, click the OK button Any

users or groups added will now have a line on the limits tab so that you may fill in

the numbers to complete the rule

Rights Tab

On this tab, you can define what access other users will have to this report Only usersand groups with rights set at a higher level are displayed here, with their net rights tothis report (inherited rights based on the folder it’s in) listed on the far right You canchange a user or group’s explicit rights to this report by selecting a different rights levelfrom the drop-down box

You can also add or remove users and groups by clicking the Add/Remove button

on the upper-right side The resulting page has three possible modes: Add/RemoveGroups, Add Users, or Remove Users Use the arrow buttons in the middle to move thedesired groups and/or users into or out of the report’s list box When you are finished,click the OK button Any users or groups added will now have a line on the rights tab

so that you may select the desired rights

The available rights levels are

■ No Access User or group cannot see the report at all.

■ View User or group is allowed to view scheduled instances, through History

and View Latest Instance; cannot run (View or Schedule) the report

■ Schedule User or group is allowed all viewing and running functions,

including View and Schedule

■ View on Demand User or group is allowed to preview the report.

■ Full Control User or group is allowed all viewing and running functions and

can also move, rename, or delete the report

■ Advanced… This option produces a page where much more granular rights

may be either explicitly granted or explicitly denied For example, a single usermay be granted the right to refresh the report’s data

The report must be in a shared public folder in order for users to find it easily If the report was published into a single user’s Favorites folder, and that folder is not shared, then users with access to the report can find it through the search functions but will not see the folder it’s in.

When you’ve adjusted the rights to the report, click Update (this time on theupper-right side) before going to another tab

When you have reviewed all the desired tabs and updated any changes on eachtab, you can close the report by navigating to another function or page in the CrystalManagement Console, or you can close the Console

Reports and report instances you’ve published through any of the publishingmethods are now visible in ePortfolio and the Enterprise environment

Crystal Enterprise comes “out of the box” with its own user interface, ePortfolio.

This Web-based application is the default method for users to interact withCrystal Enterprise when you first install it

As of the publication date, Crystal Reports 9 does not work with the most recent release

of Crystal Enterprise, version 8.5 In order to take advantage of Crystal Enterprise, you’ll have to stick with Crystal Reports 8.5 Therefore, all material in this chapter refers

to Crystal Reports 8.5 only For more information on Web delivery options with Crystal Reports 9, see Chapter 20.

While ePortfolio is fairly complete in the Enterprise feature set that it exposes,

it is obviously not designed to mirror your existing corporate intranet or Internet lookand feel As ePortfolio is entirely Web based, and because Crystal Decisions providescompletely open source code for ePortfolio, you have complete flexibility to customizeePortfolio to your exacting requirements.In fact, the included Crystal Enterprise Software

Development kit, or SDK, allows you to completely design and code your own custom

Crystal Enterprise user interface

If you wish to just use the standard ePortfolio without any customization, you can find detailed information about its features and options in Chapter 23.

Customization Overview

While the unmodified ePortfolio that comes with Crystal Enterprise may be appropriatefor many Enterprise installations, you may have a desire to customize its appearance tomore closely match the look and feel of your standard corporate Web site Perhaps youalready have a corporate intranet or portal in place that you wish to match ePortfolio to

Or, you may have an Internet site that will benefit from the scheduling or reportpresentation capabilities of Crystal Enterprise.These are just a few of the many possibleinstances where you’ll find the ability to customize ePortfolio to be of immense value

in your overall Web development direction

You should make it a practice to always make copies of any Crystal-supplied images, HTML pages, CSP pages, and JavaScript code before you make your own modifications.

If you experience technical problems with modified files, you can revert to the supplied files to see whether the problems go away.

Crystal-There are several directions you may take to customize the appearance and behavior

of ePortfolio, from simple replacement of bitmap images with those more appropriatefor your existing Web standards, to a complete redesign of the Crystal Enterprise user

interface (in essence, replacement of ePortfolio) utilizing the full capabilities of the

Enterprise SDK The direction you choose will be based on a combination of factors:

■ The extent to which you want to change the look and feel of the standard

ePortfolio

■ The level of Web development and coding expertise in your organization

■ The amount of time available for completing the customization

As you might expect, you can generally expect to require less time and less expertise

to perform simpler customizations However, if you prefer to largely redesign the basic

look and feel of ePortfolio, or perhaps even design your own from-the-ground-up user

interface using the Enterprise SDK, expect larger time and expertise requirements

Simple Customization

Relatively simple customization of ePortfolio can consist of merely replacing some of

the included bitmap images with your own, or performing simple customization to the

existing CSS, HTML, and JavaScript code already supplied by Crystal Decisions This

customization can be as simple as replacing the default logo for ePortfolio with your

own custom logo

Another easy customization can be performed by editing the default CSS file.With just a few changes, you can significantly alter the fonts and colors of ePortfolio.You may also perform modifications to existing JavaScript code (provided you have

a basic knowledge of JavaScript) or modify other graphical elements of ePortfolio bymodifying other GIF files that are shipped with the product

Complete Customization

Crystal Decisions also includes a complete Software Development Kit (SDK) to allowyou to either customize ePortfolio in larger scale or completely replace ePortfolio withyour own custom-designed interface to the core Crystal Enterprise components

Utilizing your existing HTML and Active Server Page coding skills, you can makeuse of Crystal Server Pages (CSP) to gain access to the core Crystal Enterprise components,such as folders, reports, and report instances.You may then build your own user interfacearound these elements, displaying reports inside a Web browser utilizing one of theprovided report viewers

Crystal Enterprise even includes the Crystal Web Wizard, an interactive Windowsapplication that generates a basic set of CSP code automatically, on the basis of theparameters you supply to the Web Wizard

Crystal Decisions provides extensive documentation for different customization options,

as well as sample custom applications After installing Crystal Enterprise, point your

Web browser to http://web server/crystal/enterprise and click the Web Developer’s Guide

and Developer Samples links.

Simple Modifications

As discussed earlier in this chapter, if you have minimal customization requirements

for your particular Web environment, there are many places you can turn to provide

a custom look to ePortfolio without having to undertake a large customization project

Since ePortfolio consists primarily of images, Cascading Style Sheets, and Crystal Server

Pages (JavaScript and HTML) that are completely open and available for your

modification, you may make relatively simple changes to the standard ePortfolio

offering with limited effort

By simply replacing some GIF image files provided by Crystal Decisions, you may

replace the standard ePortfolio logo with your own company logo.And by making

some simple changes to a CSS file, you may quickly change the colors and fonts for

the entire ePortfolio application While a specific Crystal Enterprise user can choose

between all the available Web-based report viewers, the Guest account is restricted to

the DHTML report viewer by default (the differences among report viewers is discussed

later in the chapter in “Changing Defaults for the Guest Account”).By performing simple

modifications to a single Crystal Server Page, you may change this default to a preferred

report viewer Other defaults may be set at the same time to further tune ePortfolio to

your application And if you do plan on relying largely on the DHTML report viewer,

you may easily customize its top toolbar frame by replacing GIF image files with those

more appropriate to your environment

Depending on how you’ve installedCrystal Enterprise, you may needto search on

separate computers to find files necessary for customization If you’ve installed both the

Web Connector and the Web Component Server on your Web server, look on this single

computer for the pathname \Program Files\Crystal Decisions\Web Content\Enterprise\

ePortfolio\en\ You’ll findmostly JavaScript (JS) andCrystal Server Page (CSP) files

in this folder In the images folder below, you’ll find GIF files, and in the css folder,

you’ll findCascading Style Sheet files If you have installedthe Web Component Server on

a computer separate from your Web server, most image andJavaScript files will reside

on the Web server, but CSP files will reside on the Web Component Server You’ll need

to coordinate modifications on both computers.

Adding Your Own Company Logo

One very simple customization can be undertaken if the general look and feel of

ePortfolio meets your needs and you merely wish to customize the product with

your own company logo Locate the file eportfolio_default.gif in the \Program Files\

Crystal Decisions\Web Content\Enterprise\ePortfolio\en\images folder This image

appears in the upper left-hand corner of many ePortfolio pages; by replacing this filewith your own company logo, you can easily add your own identity to ePortfolio.

If you are allowing users to change their color schemes, you will also want toreplace the four alternate-color logos: eportfolio_gold.gif, eportfolio_green.gif,eportfolio_purple.gif, and eportfolio_red.gif To maintain proper appearance, you’llwant to ensure that your replacement files are named the same, and are the samehorizontal and vertical size as the original files you are replacing

One other change you may want to make is to eliminate the “powered by Crystal”image There are two ways to do this: eliminate the image tags from the available.cspand logonform.csp files, or simply replace the pb_blue_sml.gif image with a white ortransparent image.The crystaldecisions.com hyperlink may also be eliminated or replaced

by looking through each of these CSPs for the line containing www.crystaldecisions.com.The line may be commented out with a JavaScript comment (//) or replaced with yourown desired URL

Changing Colors and Fonts

Another simple customization that can further match ePortfolio to your company’slook and feel is to change the basic color scheme and fonts This can be accomplished

by editing a Cascading Style Sheets file and replacing a couple of simple GIF images.The CSS file to edit is \Program Files\Crystal Decisions\Web Content\ Enterprise\ePortfolio\en\css\default.css To edit the file, you can use any text editor, such as Notepad,

or an editor specially made to edit CSS files, such as TopStyle or the CSS editor inVisual InterDev

It is beyond the scope of this book to get into the details of Cascading Style Sheets There are many sites on the Web with tutorials, samples, and references One great place to start is http://www.w3.org/Style/CSS/.

To change the color scheme of the application, you must edit the CSS file and replace

a couple of image files To change the main blue color everywhere, perform a and-replace; search for “#006699” and replace it with your desired RGB color value,such as “#FF0000” or “red.” There are many other colors defined in the CSS file, too,defined both as RGB values (such as “#6699FF”) and color constants (such as “black”).You may change any and all of these color values to customize font colors, backgroundcolors, link colors, etc To complete the color change, you must change two image files:menu_dot_bg_default.gif and small_dot_default.gif These two graphics produce therounded separators in the header areas You could eliminate these graphics altogether

search-by changing the HTML embedded in the CSP files, but it is a lot easier to use graphicediting software (such as Photoshop) to produce new images that match your colorscheme

To change the font across the entire application, search for “verdana” and replace itwith your desired font, such as “arial.” You may also want to make some of the fonts abit larger, replacing “9pt” with “10pt,” and then replacing “8pt” with “9pt,” for example

If you know more advanced CSS techniques, you may make other changes to theexisting CSS classes to further affect the look and feel of the application

Changing Defaults for the Guest Account

Several important defaults for ePortfolio can be set quite easily by editing \Program

Files\Crystal Decisions\Web Content\Enterprise\ePortfolio\en\globals.csp

Default Viewer

As with the Web Component Server supported by earlier versions of Crystal Reports,

as well as with the Crystal Report Designer Component and Active Server Pages,

Crystal Enterprise supports multiple browser-based viewers for displaying reports on

the Web The default viewer for all Crystal Enterprise accounts is the DHTML frames

viewer, as shown in Figure 24-1.This viewer takes advantage of the latest HTML standard

(Dynamic Hypertext Markup Language, or HTML 4) to provide very accurate report

formatting in a simple HTML frames display

Figure 24-1 DHTML repor t viewer

You may print only with the browser’s Print button

The Export button will display a pop-up window asking you to choose a download file format

While this viewer does an admirable job of reproducing most Crystal Reportsformatting accurately, there are certain functions (such as printing fully paginated reports

to an attached printer) that this viewer does not provide For this reason, there may be

a desire to use one of the available alternate report viewers For example, the ActiveXviewer (designed for the Microsoft Internet Explorer browser) or one of the Java viewers(designed for Internet Explorer, Netscape Navigator, and other Java-capable browsers)includes a more robust print function, as well as a more seamless export file option.The ActiveX viewer is illustrated in Figure 24-2

When you log on to Crystal Enterprise as a named user, you will have the ability

to choose the report viewer that you’d like to use by clicking the Preferences link onePortfolio main page (Chapter 23 discusses ePortfolio usage in more detail) However,the default account that ePortfolio initially presents to a user is the Guest account, whichdoes not have a Preferences option and does not allow a customized viewer choice

Figure 24-2 ActiveX repor t viewer

You may print either a range

or all report pages, which

will be accurately paginated

Export directly to your computer, without having to choose and download another file

Choose different zoom levels to view report

The choice of the DHTML viewer as the Guest account default has been hard-codedinto the globals.csp file You are free to change this choice should you prefer to present

an alternate viewer to the Guest account and to users when they first log in.To makethis change, find the line that has var DEF_VWR = 1 and simply change the 1 to any ofthe following:

0 ActiveX viewer

2 HTML page viewer

3 Java viewer (using the browser’s built-in Java Virtual Machine)

4 Java plug-in viewer

5 Navigator plug-in viewer (provides same functionality as ActiveX viewer,but in Netscape Navigator)

Look in Chapter 21 under “Report Viewers Compared” for a description of available viewers and a comparison of their features.

Menu StyleThe style of the menu in the upper-right corner can be set in globals.csp Find the line withvar DEF_MENU = MENU_BUTTONS_AND_TEXT, and choose from the menu types ofMENU_BUTTONS_AND_TEXT, MENU_BUTTONS_ONLY, and MENU_TEXT_ONLY

Reports per PageThe number of reports displayed on a single ePortfolio page can be set by findingvar DEF_RPP = 39 and replacing the 39 with the desired number of reports

OthersThere are several other defaults available in globals.csp, such as Report View Mode,Data View, and Report Listing With further tweaking of these defaults, you can create

a version of ePortfolio that is better tuned for your application

Another way you can change the default preferences for the Guest account is to use the ePortfolio Preferences Manager sample application, which is available from the Crystal Enteprise Launchpadpage By selecting that sample andlogging on as the Administrator

to Crystal Enterprise, you can get a listing of all the listeduser accounts in Crystal Enterprise, including the Guest account By selecting the Guest account and clicking on preferences, you can get and set the Guest user preferences you would normally see if a user logged on to ePortfolio with a defined account and chose their own preferences This method enables the change of Guest user preferences without the requirement of any code changes This also protects from those changes being lost shouldthe user apply a modified version of ePortfolio, such as might be received through a Crystal Decisions patch.

Customizing the DHTML Viewer Toolbar

While there are certain advantages to using the ActiveX and Java report viewers, you alsogain an advantage if you use the default DHTML report viewer.Not only do you negatethe need to download an ActiveX control or Java applet to the browser, potentiallyreducing network bandwidth and avoiding any related security issues, but you havemore control over how the DHTML viewer appears inside the target Web browser Inparticular, you have the ability to customize the appearance and behavior of the toolbarthat appears as part of the DHTML report viewer

A simple approach to this customization is to reorder the appearance of the elements

in the toolbar, (for example, placing page navigation buttons before other elements inthe toolbar and so forth) or change the bitmap images that make up the toolbar elements.You may edit the existing HTML that creates the toolbar by opening \Program Files\Crystal Decisions\Viewers\html\en\toolbar.html

You’ll notice a large amount of JavaScript code, which implements what Crystal

Decisions calls the HTML Frame API While it’s arguable that this is really an application

programmer interface, or API, in the true sense of the acronym, it does expose a set ofJavaScript functions that you can call from your customized toolbar HTML to manipulatethe report contained in another browser frame

Once you’ve opened toolbar.html, you can make modifications to the order in whichelements appear or eliminate elements you may not wish to provide to your end users.Another option is to leave the toolbar basically intact as Crystal Decisions has provided it,but to provide your own image files for such toolbar elements as page navigation buttons,the Refresh button, and other toolbar elements You can either change references to theprovided GIF files in toolbar.html to refer to your custom images, or you may replacethe supplied GIFs with new files with identical filenames You’ll find toolbar images

in the \Program Files\Crystal Decisions\Viewers\html\ en\images folder Just makesure you provide properly designed replacement graphics You’ll typically notice thatthree images are required for each toolbar element: an enabled button image (for example,refresh.gif), a “grey” disabled button image (refreshgrey.gif), and a “mouse over” buttonimage (refreshover.gif)

Should you wish to completely redesign the toolbar frame to match your own intranet

or Internet site, you may engage in a more complex from-the-ground-up design In thisscenario, you should perform the following high-level tasks:

■ Create a main CSP that creates a frameset for at least two frames: the reportframe and the toolbar frame You may want to consider creation of additionalframes for other window elements specific to your desired user interface

■ Create a separate HTML page that includes your custom toolbar code You’llneed to include the Crystal-supplied htmlviewer.js JavaScript code so that yourcustom toolbar HTML can call appropriate HTML Frame API functions to moveamong report pages, refresh the report, export the file, and so on

Complete Customization

with Crystal Server Pages

While the procedures discussed previously in this chapter provide you a certain amount

of customization capability to the out-of-the-box ePortfolio, you may have a greater need

than these techniques satisfy For example, you may have a radically different intranet

or Internet user interface that can’t be matched by simple ePortfolio customization Or,

you may have developed a completely customized portal for your employees or customers

that requires only limited pieces of Crystal Enterprise to be exposed Potentially, for

as many different Web interfaces that exist, there are options for integrating Crystal

Enterprise

Creating these higher levels of customization and integration will require greater

effort on your part, as well as greater knowledge of more base-level Crystal Enterprise

interfaces In particular, you’ll need to become familiar with Crystal Server Pages, or

CSP, as well as the programming interface exposed by the Crystal Enterprise Software

Development Kit, or Enterprise SDK As discussed earlier, ePortfolio is based largely on

CSP and is a good place to look when you’re first starting to explore this programming

interface

CSP Overview

Crystal Server Pages can be most closely compared to Microsoft Active Server Pages

(ASP), Microsoft’s server-side scripting language for their Internet Information Server

Web server Like ASP, CSP can support both VBScript and JavaScript code, as well as

embedded HTML and calls to Component Object Model (COM) objects.If you’re familiar

with ASP, making the transition to CSP should be a fairly straightforward process CSP

supports almost all the language functions of ASP, and it also includes additional calls

to the Enterprise SDK to allow you to interact with the Automated Process Scheduler

(APS), the central “brain” of Crystal Enterprise

Like ASP, CSP operates as a server-side development tool—that is, the code is actually

processed on the server, not on the Web browser While you may write fairly extensive

CSP code to create your custom interface to Crystal Enterprise, only the resulting HTML

or JavaScript will be returned to the end-user Web browser—you may have a 250-line

CSP script that ultimately returns only 20 lines of HTML and/or JavaScript to the Web

browser

Examine the following CSP code, which has been saved on a Web server set up to

run Crystal Enterprise:

Dim DayNumber

DayNumber = WeekDay(Date)

If DayNumber = 1 or DayNumber = 7 then

Response.Write "<B>Have a nice weekend on this " & _

be sent back to the Web browser All text outside of these special symbols will be sentdirectly to the Web browser as standard HTML As a result, the following HTML will

be returned to the browser, if the system clock on the Web Component Server is set to

a Saturday (the WeekDay of the week is 7):

ASP, which is evaluated on the Web server (and that Web server must be Microsoft

Internet Information Server), CSP is evaluated on the Crystal Enterprise Web Component

Server.This difference gives you more flexibility with Crystal Enterprise, in that you are

not required to use CSP with a Microsoft Web server You may use CSP with a variety

of Web servers, including Netscape Web servers and “plain” CGI Web servers, as well

as certain UNIX Web servers Also, CSP exposes additional software interfaces beyond

ASP that can be used to interact with Crystal Enterprise components—in particular, the

Crystal Enterprise ASP

There are other subtle differences between ASP and CSP For details, look in the

Enterprise Web Developer’s Guide, or search the Crystal Decisions support site

at http://support.crystaldecisions.com.

You will typically find there to be much more to a CSP page than the simple example

given previously Here’s a small fraction of the code belonging to a relatively small CSP

that simply extracts the list of folders from the Crystal Enterprise APS:

The resulting HTML is very small—simply showing a few GIF files and the names

of the retrieved folders:

In order for CSP functionality to operate with diverse Web servers, specific Webpage file extensions are “flagged” for special handling on the Web server when aCrystal Enterprise Web Connector is installed on the server In particular, the followingWeb page file extensions are automatically routed to the Web Component Server whenencountered by the Web server:

As such, any URL containing any of these three extensions will not be processed onthe Web server—the file will be routed by the Web server to the Crystal Enterprise WebComponent Server, which will process the file according to Enterprise’s predeterminedprocessing cycle.The results of that processing cycle (standard HTML and/or JavaScript

from a CSP or a report viewer from a CWR or RPT) will then be sent back to the Web

server for return to the Web browser originating the URL

For more information on Crystal Enterprise Architecture and a discussion of different

Enterprise components, such as the APS andWeb Component Server, refer to Chapter 22.

Creating Crystal Server Pages

Once you decide to undertake a CSP project (either modification of an existing system

or creation of a new ground-up application), you’ll have several choices available to you

when it comes to code creation.Considering that your custom application will probably

make at least minimal use of Crystal Enterprise functionality, be prepared for a fairly

code-intensive process One look at the supplied ePortfolio CSPs will give you an idea

of the amount of code required to make even moderate use of Crystal Enterprise features

(one of the main ePortfolio files, available.csp, contains over 2,000 lines of code) The

choice of your ultimate coding method will depend on a number of factors:

■ Your coding skills

■ Availability of an existing application you can modify

■ The complexity of the application

■ Whether Crystal-supplied tools can create a close enough starting point

You have several choices available, much as you do when creating Active Server

Pages.You can use HTML authoring tools, such as Microsoft FrontPage; Web-application

development tools, such as Visual InterDev; and even simple text editors, such as Notepad

Crystal Decisions provides some supplementary tools to make CSP creation easier

The Crystal Web Wizard is available to help you create a “starting application” using

a simple “expert” interface You’ll also find the CSP Query Builder to help you create

SQL-like queries to retrieve data from the APS And the sample applications (available

on the Enterprise Launchpad) show various ways to embed Crystal Enterprise

functionality into a variety of applications

Manual Creation with an HTML Tool or Text Editor

If you are familiar with Active Server Pages, you’re aware of various tools used to create

them In general, the development community appears to be evenly divided between

a development tool such as Visual InterDev, a “fancy” text editor such as Microsoft

FrontPage, and a plain text editor such as Notepad (Microsoft’s new development

environment, Visual Studio.NET, stands ready to offer a much better alternative to

these existing methods) You’ll find a similar set of options for Crystal Server Pages

While CSPs are plain ASCII text files, you may want to look for a more robust editing

tool—at least one that will highlight different syntax elements inside the VBScript

or JavaScript code your CSP is based on While none of the aforementioned tools will

specifically recognize particular Crystal Enterprise CSP syntax elements, you will gain

the benefit of at least denoting standard VBScript of JavaScript code included in the CSP

You may need to set options for Microsoft Visual InterDev or FrontPage to set the tools

to properly recognize the CSP file extension Look at online documentation for these tools to get more information on adding additional file extensions Or, you may wish to rename your CSP files with an ASP extension for editing, and then rename them back

to CSP before testing.

You may also be satisfied with the text-editing capabilities of a simple text editorsuch as Notepad.While you won’t see particular VBScript or JavaScript syntax, asimple editor requires no special configuration to recognize file types and can simply

be left open side by side with a Web browser to perform an edit-save-refresh type ofdevelopment and debugging process

No matter which method you use to create or modify CSPs, you will need to keep

a reference of CSP objects, properties, and syntax close at hand, particularly whenyou first begin developing your application.While a comprehensive discussion ofall Enterprise SDK options is beyond the scope of this Crystal Reports–oriented book,the Enterprise Web Developer’s Guide (available from the Crystal Enterprise Launchpad)provides a complete reference to the CSP object models and syntax You’ll also find acomplete set of tutorials in this help file, including sample CSP code you can copy toyour own editor for use in developing your custom application

The Crystal Web Wizard

As discussed earlier in this chapter, even a moderately simple Crystal Enterprise customapplication can become very code intensive very quickly You will want to eventuallydevelop good knowledge of the individual elements of the Enterprise SDK to maximizeyour coding flexibility However, you may appreciate a Crystal Decisions–supplied toolthat makes initial creation of custom CSP code as simple as using an expert-like interface

to specify simple requirements for your initial application The Crystal Web Wizard is

available as a stand-alone Windows program

The Crystal Web Wizard will present you with a series of screens allowing you tochoose particular options for your Crystal Enterprise application First, you’ll have thechoice of either creating a new project or creating an Admin project A new project willcreate a generic user interface, including logon information and a folder/report list.You will then be able to modify the CSP created by the wizard to more closely matchyour desired look and feel Choosing an admin project will produce an application formanaging users and groups

The Crystal Web Wizard is a Windows application that must be specifically chosenwhen you install Crystal Enterprise If you click your Windows Start button and don’tsee a Crystal Enterprise menu option or don’t see the Crystal Web Wizard option withinthis menu, you’ll need to rerun Crystal Enterprise setup from the program CD-ROMand ensure that the Web Wizard is chosen as an option

To use the Crystal Web Wizard, perform the following steps:

1.Start the Crystal Web Wizard from the Windows Crystal Enterprise Start button

menu The Web Wizard initial screen will appear

2.Choose Create a New Project or Create an Admin Project Then, click the

Next button

3.If you choose to create a new project, you’ll next be given the opportunity to

determine the logon method you wish to present to your end user when the

application first runs Choose Crystal Enterprise Authentication if you want

to provide only Crystal Enterprise–based security (no NT security option will

be available).Choose Logon (All Options) if you want to provide a choice of

authentication methods (Enterprise or Windows NT) to your end user.Or, choose

Windows NT Authentication to provide only Windows NT–integrated security

to your end user Then, click the Next button

4.You’ll then be presented with a choice of content templates to control the display

of folders, reports, and report instances Each of the four choices (Classic Report

Listing, Directory Listing, Large Icon View, and Report Listing) will display folders

and reports in a different fashion A thumbnail view of the way the page will

appear shows in the preview area when you select each option.Make your desired

choice and click the Next button

5.You’ll now be given a choice of a style sheet for the display of your Crystal

Enterprise application.As with the content template type, you’ll be given choices

in a drop-down list, with a matching thumbnail appearing in the preview area

when you choose different options Make your choice of a style sheet and click

the Next button

6.The last screen in the Web Wizard will allow you to select a drive and directorywhere the CSP, HTML, GIF, and other files should be copied.Either type

in a pathname directly or click the Browse button to choose a directory from

a directory list

7.You may choose any pathname you wish (the default being the standardinetpub\wwwroot root directory for Microsoft Web servers) However, you’llprobably want to choose a pathname that can be referenced via a Web servervirtual directory.If the pathname you choose can’t be referenced by a Webserver virtual directory, you’ll need to map the pathname you specify here to

a virtual directory with your Web server administration tools before you cansuccessfully view your completed Enterprise application

8.After you’ve specified the location to save the files, click the Finish button Thefiles composing your Crystal Enterprise application will be created and placed

in the pathname you specified

You may now modify any of the wizard-created CSPs to more closely match yourdesired intranet or Internet standards.To view the completed custom application, simplypoint your Web browser to the virtual directory where you save the application

For example, to retrieve a list of reports in a particular folder to display in a secondaryreport frame, you might execute CSP code similar to the following:

query = "Select SI_NAME, SI_ID From CI_INFOOBJECTS Where "

query = query & "SI_PROGID='CrystalEnterprise.Report' "

query = query & "And SI_INSTANCE=0 AND "

query = query & "SI_PARENT_FOLDER=" & CStr(CurrentFolderID)

'Query the serverSet ObjectResult = IStore.Query(Query)

TE AM

FL Y

Team-Fly®

An entire section of the Web Developer’s Guide is dedicated to this query syntax,including a reference to all the objects that can be returned and tested.However, CrystalDecisions provides a Web-based tool to allow you to create and execute these queriesoutside your CSP code This tool serves several useful purposes—allowing you to seeanother Web-based example of how to interact with the Enterprise SDK, facilitating aquery of the APS database with a stand-alone tool, and giving you an expert-like way

of exploring the syntax for InfoStore queries

To use the Query Builder, choose the CSP Query Builder from the Developer Samples

link on the Crystal Enterprise Launchpad, or point your browser to http://web server/

crystal/enterprise/websamples/en/query.The CSP Query Builder will appear in

a Web browser, as shown in Figure 24-3

Figure 24-3 Cr ystal Enterprise CSP Quer y Builder

This Web-based tool allows you to enter an SDK-formatted SQL statement directly

into the text box below the login information, or use a simpler step-by-step process of

building “rules.” Once you’ve built rules, you may click the Finish button to create a SQL

statement at the top of the Query Builder window When you click the Submit Query

button, your query will be submitted to the APS and a result set of folder, report, or

object data will appear in your browser.You may then use the query that you built

interactively in the Query Builder right inside your CSP code You may simply copy

and paste the query that was displayed from the Query Builder into your text editor,

or retype it using the same syntax

You’ll notice that many objects and properties exposed by the Enterprise SDK begin

with the letters “SI,” while some begin with “CI.” This indicates that the Enterprise

SDK actually had its beginnings in other Crystal Decisions products—Seagate Info

and its predecessor, Crystal Info You’ll notice some of these properties are documented

as being unavailable in Crystal Enterprise Standard or Professional Editions This

indicates that these properties are “left over” from Seagate Info and are not supported

in this release of Crystal Enterprise.

Sample Applications

The Crystal Launchpad contains links to several sample applications that feature a variety

of Crystal Enterprise functionality.All of the source code for these applications is available

for research, modification, or copying-and-pasting Depending on your needs, it may

be possible to use a sample application as the starting point for your own application

When first viewing the Crystal Launchpad, examine links to the samples on the left

side of the screen under “Client Samples.”

If you’ve read even a bit of Part I of this book, you’ve seen some of the power and

flexibility of Crystal Reports.By making the vast array of corporate databases accessiblewith its simple, straightforward user interface, Crystal Reports has established itself

as a valuable tool simply by virtue of its reporting and querying capabilities Part IIexplored the myriad ways to integrate Crystal Reports with the World Wide Web Butthere’s a whole other side of Crystal Reports that has yet to be explored

Because database reporting and querying is a large part of many standard businessapplications, you’ll often need to include these features in custom applications that youcreate for your own use If you develop custom applications for Microsoft Windows inany of the popular Windows development tools, you’ll probably soon need some type

of database reporting functionality inside the application While you can develop yourown routines to step through the database record by record to generate your own internalreporting mechanism, all the intricacies of formatting, font management, graphics,and other Windows-related printing issues can create a significant, if not impossible,coding challenge

Crystal Reports has featured developer interfaces for virtually all of its Windowsversions Version 9 offers some improved developer integration features that make it

an even better choice for inclusion in custom Windows applications Microsoft VisualBasic 6 (VB) developers, as well as other developers using a development tool compatiblewith Microsoft’s Component Object Model, will appreciate improvements to the ReportDesigner Component (RDC).In Visual Basic and later Microsoft Office Developers editions,this interface allows both report design and flexible report integration to occur entirely

in the VB integrated development environment (VB IDE) You’ll never have to leaveVisual Basic to perform any report development or integration tasks!

If you’re looking toward Microsoft’s significantly updated Visual Studio NET toolfor Windows or Web application creation, you’ll find Crystal Reports is an integral part

of this new development environment as well.Much like the Report Designer Componentwith Visual Basic 6, Crystal Reports for Visual Studio NET is fully integrated withthe development environment, allowing complete report development right insideVisual Studio NET Finished reports can be made available in both Windows and Webapplications, as well as being published as Web services.And, Crystal Reports 9 AdvancedEdition adds even more functionality to your existing NET environment

Furthermore, Crystal Decisions provides flexibility when it comes to distributingyour custom applications.While you are not allowed to redistribute the Crystal Reportsdesign components (such as the Crystal Reports design program itself), your customprograms that merely manipulate and customize existing reports can be distributedwithout charge.You receive a royalty-free license to distribute the Crystal ReportDesigner Component and associated files, such as associated database and exporting.DLL files You may purchase a single copy of Crystal Reports, develop your customapplication, and distribute the run-time files with as many copies of your application

as you like, at no additional charge If you elect to use newer report creation functions

or the embedded Report Designer control that is available in Version 9, you will need

to purchase a run-time license from Crystal Decisions

Don’t forget that Crystal Reports 9 is available in four different editions The Developer

or Advanced Edition will be of interest to you if you plan on using any Windows

development features To use any of the developer interfaces discussed in this section of

the book, you need to purchase the Developer or Advanced Edition—the other editions

don’t provide necessary components for custom Windows integration If you want to make

use of new Crystal Reports 9 additions to Visual Studio NET, you need to purchase the

Advanced Edition.

Development-Language Options

Crystal Reports developer interfaces have been designed to work with most popular

Windows development tools that support Microsoft’s standard Component Object

Model (or COM) Previous Crystal Reports versions also included “legacy” interfaces

that could be used with non-COM environments, such as those that integrated via

Windows API calls or Visual Basic ActiveX (.OCX) controls While some of these older

interfaces may still be supported with Crystal Reports 9, they have been given the

dubious distinction of “legacy status,” indicating that they don’t contain newer features

that the COM options provide

And finally, Crystal Decisions Software provides a Java-capable interface with Crystal

Reports 9 The Crystal Reports Java Bean Viewer allows you to integrate a report into

your Java applet or Web application The Java Bean Viewer exposes a similar set of

properties and methods as the Crystal viewer control for non-Java development tools

Which Development Language Should I Use?

Which development language you should use is a question that cannot be answered

simply in this book.It obviously depends largely on your experience level with particular

developer tools Also, your company may standardize on certain development tools

that limit your choices.However, if your project will depend heavily on built-in reporting,

you may want to consider an alternative tool if the tool you are familiar with doesn’t

support Microsoft’s COM-standard interface

With Crystal Reports 9, there is no more question about Crystal Decisions’ intended

direction with developer interfaces Previous interfaces, such as the Report Engine API,

have been relegated to “legacy” status—a separate help file exists to document these

interfaces (Legacy.CHM is located in Program Files\Crystal Decisions\Crystal Reports 9\

Developer Files\Help\<language>).Since most common Windows languages work

with Microsoft’s COM, chances are good that you’ll be able to program Crystal Reports

applications using this method

Overall, you need to balance your corporate standards, your knowledge level, the

size and speed you want your application to maintain, and the reporting demands of

your application when making a development-tool choice While Crystal Decisions still

provides several different interfaces, it is now “Crystal Clear” (pun intended!) that the

COM-based Report Designer Component is the integration direction of choice

The best source of developer-related information from Crystal Decisions is a Windows Help file that ships with Crystal Reports Use Windows Explorer to navigate to the CrystalDevHelp.CHM file in Program Files\Crystal Decisions\Crystal Reports 9\ Developer Files\Help\<language> You’ll find complete documentation for the Report Designer Component, sample code that you can copy from the Help file, and references

to sample applications that are installed along with Crystal Reports You can also find several helpful online documents in Adobe Acrobat PDF format on the product CD-ROM While DevGuide.PDF provides a higher-level overview of integration options, TechRef.PDF provides much of the same detailed information as CrystalDevHelp.CHM.

Different VB Reporting Options

One of the big reasons for Crystal Reports’ popularity is that it seems to automatically show

up whenever you install a great number of other applications It has been bundled withVisual Basic since version 3 and is also included with some other Microsoft developmenttools and over 150 other general and specific off-the-shelf applications This, combinedwith the inclusion of Microsoft’s Data Report Designer in VB 6, may beg the question:

“Why should I upgrade to the full Developer or Advanced Edition of Crystal Reports if

I can use the Data Report Designer or already have a bundled version of Crystal Reportswith Visual Basic?”

Crystal Reports Versus the

Microsoft Data Report Designer

In VB versions prior to 6, the only reporting options you had “out of the box” wereexcruciatingly painful record-by-record coding options, or the various bundled versions

of Crystal Reports.Visual Basic 6 introduced the Microsoft Data Report Designer, as well

as continuing to include a bundled version of Crystal Reports Whereas Crystal Reportswas typically installed automatically with VB in versions prior to 6, you have to dig for

it with VB 6 Microsoft automatically installs its own Data Report Designer instead.However, a peek at the Microsoft offering will quickly give you an idea of whereyou may want to turn for report design While the Data Report Designer is fairly wellintegrated with Visual Basic (using the VB Data Environment), it quickly runs out ofsteam And Microsoft obviously didn’t think that highly of its report designer either—

it has been eliminated from Visual Studio NET to make way for Crystal Reports!

Bundled Crystal Reports Versus the Stand-Alone Version

Even with Microsoft’s Data Report Designer included in VB 6, Crystal Reports is still

bundled in the VB package—you just have to install it separately.VB 4 and 5 also

■ Bundled Crystal Reports was brought to market before Microsoft’s COM became

a standard.It doesn’t contain any of the newer programming interfaces, such asthe RDC

■ Crystal Reports 5 and later introduced many new usability enhancements, such

as conditional formatting, multiple sections, and subreports Accordingly, manycapabilities will be severely limited if you choose to use the bundled VisualBasic 6 version

■ The bundled version contains absolutely no Web-reporting capabilities If your

VB apps will ever get near the Web, you’ll appreciate the stand-alone version’s

Web-reporting features, such as RAS and Crystal Enterprise (discussed in Part II

of this book)

Visual Basic Developer Interfaces

Crystal Decisions provides several methods for you to use Visual Basic to create a customreporting application Your choice of a programming interface will depend on severalfactors, such as your experience level and the particular functions that you need to include

in your application Table 25-1 discusses the different methods and their advantagesand disadvantages

As mentioned previously, the Report Designer component is, without a question,Crystal Decisions’ tool of choice for VB integration—and with good reason The RDCprovides a good mix of functionality and ease of use With its object-oriented interface,you can accomplish any sophisticated report customization that you require withouthaving to get down and dirty with Windows API calls The RDC also provides reportdesign capabilities right inside VB.And, while the ActiveX control is a great way

to integrate a report in simpler applications, you will soon find that it doesn’t offersophisticated features that you will need later on, when your application grows This isespecially true considering that it has not been updated with new features since CrystalReports Version 6

C h a p t e r 2 5 : I n t e g r a t i n g C r y s t a l R e p o r t s 9 w i t h V i s u a l B a s i c 721

Team-Fly®

One thing to keep in mind when making your choice of a VB interface is that youmust choose one option for each individual application You can’t use more than oneapproach in the same application For example, if you add the ActiveX control to yourapplication and then try to make direct API calls, errors will result.Evaluate your needsand skills.Then, choose a method and stick with it.Changing an interface in midstreamwill require you to do significant recoding.

Due to Crystal Decisions’ continuing movement towardthe Report Designer Component (RDC) as its single developer interface of choice, the remainder of this book section will concentrate on the RDC only Chapters covering the older “legacy” integration methods, such as the ActiveX control andReport Engine API, are available for reference on this book’s companion Web site at www.CrystalBook.com.

The Report Designer Component

Continuing along the direction set with Crystal Reports 8.5, Crystal Reports 9’s premier

programming integration method is the Report Designer Component, or RDC While

there aren’t major revisions to Version 9 of the RDC, there are some notable changesthat can make your development activities easier:

■ Connection Information “property bags” are part of the new core CrystalReports query engine This approach provides a complete set of propertiesfor each table in your report that can be read or written at run time

■ Support for embedding database, formula, or special fields inside text objects.While this has been supported in the Crystal Report designer for some time,

it is now available programmatically to you within your app

■ Additional exporting, printing, and charting options Many new CrystalReports 9 capabilities related to these features are now exposed by the RDC

Part III Does Not Teach You Visual Basic!

The rest of Part III assumes you have a beginning-to-intermediate working knowledge

of Visual Basic.It’s not practical to try to teach you VB at the same time you’relearning how to integrate reports.You’ll need to have a fundamental knowledge ofhow to create VB forms and how to respond to events There are many good texts(including several from Osborne/McGraw-Hill), training programs, and interactivetutorials available to teach you these fundamental skills

Also, this section assumes that you have gleaned report design knowledge fromPart I of this book Crystal Reports features, such as selection criteria, parameterfields, and object and section formatting, will be covered.If necessary, refer to Part I

to brush up on these report design topics