You can preset the parameter values of the first n
levels of a cascading prompt group so that the user viewing the report only
needs to select values from a subset of the parameters. There are some factors
to consider when using dynamic cascading parameters to add this functionality
to your application:
Only dynamic cascading prompts that have a
parameter associated with them can be programmatically set. For example, if a
prompt group only has a parameter associated with its lowest level, you can
only set a parameter value for that one level.
A cascading parameter prompt group can only be
partially set when viewing the report at run-time. Reports can't be saved in a
state where only some of the parameters in a cascading prompt are set. Either
all the cascading parameters are set and saved back to the report (as saved
data), or none of the cascading parameter values are saved (user is prompted to
select parameter values when viewing).
Only valid, matching values that are set at all
levels of a cascading prompt group will ensure the report displays correctly.
Validity is important because no restrictions or exceptions are thrown
programmatically if you set invalid values. For example, if you have a
'Country', 'Region', and 'City' set of cascading parameters, and you set the
values to 'USA', 'CA' and 'Paris' respectively ('Paris' being an invalid value
for this country and region), the viewer will try to display the report with
those mismatching values with unpredictable results. However, if you are
setting only a subset of the levels to trigger a prompt dialog box for users,
and you have mismatching values, any invalid cascading values will be discarded
so the prompt dialog box can be displayed correctly.
Note: The ReportClientDocument object model does
not currently support creating new prompt groups programmatically and saving
them to the report. For more information about dynamic cascading parameters and
creating prompt groups with the Crystal Reports Designer, see the
Crystal Reports User's Guide.
Example:
This example programmatically sets the first two
parameters of a three-level, dynamic cascading prompt in a report. The report
has three dynamic cascading parameters: 'Country', 'Region', and 'City'. These
values will be pre-populated when the prompt dialog box is rendered, and they
will filter the allowed values of the third level parameter, 'City', which can
be entered by the user.
void setDynamicCascadingParameters(ReportClientDocument clientDoc, CrystalReportViewer viewer)
{
ParameterFieldController paramController;
paramController = clientDoc.getDataDefController().getParameterFieldController();
paramController.setCurrentValue("", "Country", "USA");
paramController.setCurrentValue("", "Region", "CA");
viewer.setReportSource(reportClientDocument.getReportSource());
}