C1.Web.C1WebReport.2
Specifies the method used to render report images on the client.
For details, please see the property.
Report images are stored in temporary files in the application folder and
rendered on the client using an Html IMG tag.
Report images are stored in the application Cache and rendered on the
client using an HttpHandler.
Specifies the method used to perform exports.
Exported report is stored in a temporary file in the application folder.
Exported report is stored in the application Cache and transfered to the
client using an HttpHandler.
Specifies the method by which data is transferred to the source page.
For details, please see the property.
Data is transferred in a cache object.
Data is transferred in a session object.
Specifies the export formats that should be made available in the export
button of the navigation bar.
Do not allow exporting to any formats.
Allow export to PDF format.
Allow export to HTML format.
Allow export to XLS format.
Allow export to RTF format.
Allow export to all formats.
Defines the appearance and behavior of the built-in navigation toolbar.
If the property is set to true, reports are broken up
into pages and displayed on the browser one page at a time.
The built-in provides UI elements that allow users to browse
the report page by page.
Gets a string that represents this .
A string that represents this .
Returns a string that can be used in a client event to cause a navigation bar action.
The server Control that processes the action.
A string of arguments to pass to the control that processes the action.
A string that, when treated as script on the client, initiates the action.
The parameter must be one of the following values:
'<<', ' < ', ' > ', '>>', 'EXPORT<FORMAT>', or GOTO<PAGE>
Where FORMAT is PDF, RTF, XLS, or HTML, and PAGE is a number.
Loads the view state in the group object.
View state to load.
Saves the view state and returns it as an object.
Saved view state.
Tracks the view state.
Gets or sets the default export format initially selected on the Export ComboBox.
Specifies whether the built-in navigation bar is displayed on paged reports.
If you set this property to false and the report is paged, then you should provide
a custom navigation bar yourself, or the users will see only the first page of the
report.
Gets or sets the text displayed in the built-in navigation bar.
The property should contain two format placeholders, "{0}" and "{1}",
which are used to display the values of the
and properties.
The default value for the property is "Page {0} of {1}".
You can change the text in the navigation bar and also add some formatting by adding Html
formatting tags to the text. For example:
_c1wr.NavigationBar.Text =
" This report has {1} pages, and this is page <b>{0}</b>";
Gets the object used to render the built-in navigation bar.
You can use this property to customize the colors, font, and borders of the
built-in .
If you don't modify the style, the navigation bar is rendered using the
same color scheme as the owner control.
For example, the code below causes the bar to use the reverse color scheme of
the owner control, giving the bar a 'negative'
appearance:
_c1wr.NavigationBar.Style.BackColor = _c1wr.ForeColor;
_c1wr.NavigationBar.Style.ForeColor = _c1wr.BackColor;
Gets or sets the alignment of the navigation bar within the control.
This property is especially useful in RightToLeft environments.
Specifies whether the Goto Page button should be displayed.
Specifies whether the Export button should be displayed.
Gets or sets the export formats available on the Export ComboBox.
Gets the collection of images used for buttons in the normal state.
Gets the collection of images used for buttons in the mouse over state.
Gets the collection of images used for buttons in the disabled state.
Gets the collection of ToolTips associated with each navigation bar element.
Defines set of images for Navigation Bar.
NavigationBar.Images, NavigationBar.MouseOverImages, NavigationBar.DisabledImages are of the NavigationBarImages type.
Clears out any defined properties the state bag.
Gets or sets the URL of the image contained in the Goto First button.
Gets or sets the URL of the image contained in the Goto Previous button.
Gets or sets the URL of the image contained in the Goto Next button.
Gets or sets the URL of the image contained in the Goto Last button.
Gets or sets the URL of the image contained in the Goto Page button.
Gets or sets the URL of the image contained in the Export button.
Defines set of ToolTips for Navigation Bar buttons.
Clears out any defined tooltips the state bag.
ToolTip for the Goto First Page button.
ToolTip for the Goto Previous Page button.
ToolTip for the Goto Next Page button.
ToolTip for the Goto Last Page button.
ToolTip for the Goto Page button.
ToolTip for the Export button.
Implements a compressed report cache for the control.
Whenever needs to generate a report, it looks in the cache first.
If the report is found there, it is retrieved, decompressed, and sent to the client. This
is a very efficient process, much faster than regenerating the report.
If the report is not found in the cache, it is generated, compressed, stored in the
cache, and then sent to the client.
The class uses the object, which
has application scope and can be adjusted for many types of server configuration, including
web farms. Please refer to the .NET framework documentation for more details.
Removes the report from the Cache.
Reports are cleared from the cache automatically whenever there are any changes to the
report definition file, to the report definition itself, or to the file specified by the
property.
If your application relies on data that does not come directly from a file, however,
you may need to call the method explicitly when the data changes.
This will cause the control to render a new copy of the report using the modified data.
Gets a string that represents this .
A string that represents this .
Specifies whether the control should store rendered reports in the cache.
This property is set to true by default, allowing the to use
the object to store frequently used reports. This enhances
performance significantly, but it does use some server resources.
If you want to reduce the memory requirements on the server, setting the
property to false will cause the control
not to use the cache. Reports will be rendered every time they are requested, and memory
usage will be reduced at the expense of more data access and processing time needed to
create the reports multiple times.
In general, you should only turn the cache off if you are rendering a custom report
that probably won't be requested again in the next few hours.
Gets or sets the number of minutes that elapse before reports are discarded from the cache.
The default value for this property is 30, causing reports to be stored in the cache for
30 minutes before they are discarded. You can use the property to
determine whether this is an absolute or a "sliding" limit (meaning the interval is reset
every time the report in the cache is reused).
The amount of time reports remain in the cache is also affected by file dependencies.
By default, changes in the report definition file cause cached reports to be discarded. You
can select an additional file dependency using the property.
Specifies whether the expiration timer should be reset when reports are retrieved from the cache.
The default value for this property is false, meaning that the expiration time is not reset
when reports are retrieved from the cache.
Gets or sets the name of a file that invalidates the cache when it changes (e.g. the data source).
The report definition file used by the control is always set as a dependency (when it changes,
cached reports are automatically discarded).
You can select an additional explicit file dependency using the property.
The code below adds a dependency on a Sql database file. If the report definition or the
underlying report data change, cached reports will be automatically discarded and new reports
will be generated to reflect the changes:
// add dependency on SQL server data file
_c1wr.Cache.FileDependency = @"c:\MSSQL7\Data\pubs.mdf";
Gets or sets the cost of reports relative to other objects in the cache.
If your application stores many types of object in the cache, you may want to set
the property to reflect the relative cost of each type of item.
For example, you may be generating technical diagrams that take a long time to create,
and should have a higher cache priority than simple reports. Or you may be caching
customer information that is easy to retrieve from the database and should have a
lower priority.
For more details on this property, and a list of valid settings, see the
method in the .NET framework documentation.
Gets or sets the location of the report definition.
The location of the report definition is defined by two elements: the name of the
Xml file that contains the report () and the report
name ().
These two elements are needed because report definition files may contain many reports.
At design time, you can set both properties using a designer that lets you pick
the file and then select the report from a list. At run time, you can set these properties
using code.
Note that the report definition is not persisted as part of the control's
, only its location. Whenever the page is
loaded, the report definition is read from the file.
If you want to customize the report at run time, using the
object model, you should write a routine that applies the changes and call it from the
page's event.
Usually, the property is set to an absolute path
on the server. If you set it to a file name without a path, will
look for the report definition on the path that contains the page.
Gets a string that represents this .
A string that represents this .
Gets or sets the name of the report definition file that contains the report.
Report definitions are stored in XML files created with the C1ReportDesigner.
This property specifies the file that contains the report to be rendered by the
control.
Usually, the property is set to an absolute path
on the server. If you set it to a file name without a path, will
look for the report definition on the path that contains the page.
Gets or sets the name of the report to load from the report definition file.
Report definitions are stored in XML files created with the C1ReportDesigner. Each
report definition file may contain several reports. The
property specifies which report in the report definition file will be loaded and
rendered by the control.
The report definition file is specified by the property.
C1WebReport is an ASP.NET control that hosts a control and
streams HTML and PDF reports to a browser.
To use the control, drag it onto a WebForm and use the
property to select a report definition. Then customize the
appearance and behavior of the control using the ,
, , ,
, and properties.
Creates a new instance of a control.
Redirects the browser to show the current report in Adobe's Portable Document Format (Pdf).
Pdf is a rich format, often more convenient than straight Html for rendering complex
documents such as reports. Pdf is compressed by default, and it can be saved and annotated
by users who have Adobe's Acrobat Viewer. Pdf documents are usually more faithful than
Html because they allow you to specify page dimensions and orientation, and the format
offers more flexibility than Html in rendering graphic elements such as lines.
Saving Pdf files is easier than saving Html files, because Pdf is a stand-alone
format, and images in Html are always represented by links to external files.
Most browsers are capable of displaying Pdf files via plug-ins, which Adobe offers
for free with the basic version of its Acrobat Viewer (see www.adobe.com for details).
Pdf reports are also cached by (see the
property), so once they are generated, subsequent requests can be fulfilled almost
instantly.
The code below show a Pdf version of the report when a button si clicked:
private void PdfButton1_Click(object sender, System.EventArgs e)
{
// show PDF version of the report on the client
_c1wr.ShowPDF();
}
Redirects the browser to show the current report in Adobe's Portable Document Format (Pdf).
Whether TrueType fonts should be embedded in the Pdf document.
Embedding TrueType fonts into the document increases document size but ensures the document
will be rendered correctly even if the fonts are not installed on the client's computer.
If the Pdf document does not display properly in the browser, or if the browser offers to
open or download the file instead of simply displaying it, try re-installing the Acrobat Reader
software.
Exports the report to a specified format and shows the result in a new window.
Export format to use.
Exports the report to a specified format and shows the result in a new window.
Export format to use (HTML, PDF, RTF, or XLS).
Raises the event.
An object that contains the event data.
Raises the event.
An object that contains the event data.
Raises the event.
An object that contains the event data.
Restores control state information from a previous page request that was
saved by the method.
An object that represents the control state to be restored.
Saves any server control state changes that have occurred since the time the page
was posted back to the server.
An object that represents the server control's current state.
Raises the event.
An object that contains the event data.
Sends server control content to a provided object,
which writes the content to be rendered on the client.
The object that receives the server control content.
Releases the resources used by the control.
This member overrides Control.LoadViewState.
This member overrides Control.SaveViewState.
This member overrides Control.TrackViewState.
Fired when the value of the property changes.
This event is useful when you want to implement custom navigation bars and need to
update the display to show the number of the page being displayed.
The code below uses the event to enable or disable
the navigation buttons and to update the current page/page count display:
// update bar state after page changes
private void _c1wr_CurrentPageChanged(object sender, System.EventArgs e)
{
int curr = _c1wr.CurrentPage;
int cnt = _c1wr.PageCount;
// show/hide navigation buttons
_btnFirst.Visible = _btnPrev.Visible = (curr > 1);
_btnLast.Visible = _btnNext.Visible = (curr < cnt);
_btnJump.Visible = _txtPage.Visible = (cnt > 1);
// update label
string str = string.Format("This is page {0} of {1}", curr, cnt);
if (curr == 1) str = "This is the first page.";
else if (curr == cnt) str = string.Format("This is the last page ({0}).", cnt);
_lblCurrent.Text = str;
}
Fired when the contained control starts rendering the report,
before it opens the source recordset.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when the contained control finishes rendering the report.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when the control starts rendering a report and the source recordset is empty.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when the control starts rendering each page.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when the control finishes rendering each page.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired before each report section is formatted.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired before each report section is rendered (after it is formatted).
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when the control finishes rendering each report section.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when an error occurs while rendering a report.
This event does not fire if the report is retrieved from the cache (see the
property).
Fired when the control needs to obtain report parameters.
Reports that have a PARAMETERS clause in their property
allow users to provide report parameters.
C1Report displays a dialog where users may enter the report parameters.
The C1WebReport control runs on the server and thus cannot show the parameter
dialog. However, it will fire this event to allow event handlers to customize
the parameters using code.
The code below uses the InitializeParametersDialog event to modify the values
of the report parameters.
private void C1WebReport1_InitializeParametersDialog(object sender,
C1.Win.C1Report.DialogEventArgs e)
{
C1.Win.C1Report.ReportParameterCollection p = e.Parameters;
p["Beginning Date"].Value = Calendar1.SelectedDate;
p["Ending Date"].Value = Calendar2.SelectedDate;
}
Gets or sets a reference to the contained component
that renders the reports.
Use this property to access the underlying report object model when you want to
customize the report on the web page, or if you want to use
features that are not exposed through the object model
(such as creating RTF or XLS versions of the report).
The code below shows how you can customize a report to reflect user selections. The page
contains a ListBox called _lstYear. When the page loads, the control automatically
reloads the report definition from the . Then the Page_Load
event fires and the report is modified to reflect the choice made by the user.
In this case, the code changes the report's
property to apply a WHERE clause and retrieve data only for the year selected.
private void Page_Load(object sender, System.EventArgs e)
{
// customize report with info submitted by the user by setting
// the RecordSource property on the contained C1Report control
string sql = "SELECT * FROM Orders";
// select specific year
string year = _lstYear.SelectedItem.Text;
if (year != "All") sql += " WHERE Year(Orders.ShippedDate) = " + year;
// assign new RecordSource to control
C1.Win.C1Report.C1Report rpt = _c1wr.Report;
rpt.DataSource.RecordSource = sql;
}
Gets or sets the location of the report definition.
The location of the report definition is defined by two elements: the name of
the Xml file that contains the report () and
the report name ().
These two elements are needed because each report definition file may contain
many reports).
At design time, you can set both properties using a designer that lets you
pick the file and then select the report from a list.
At run time, you can set these properties using code.
Note that the report definition itself is not persisted as part of the control's
, only its location. Whenever the page is loaded, the report
definition is read from the disk. If you want to customize the report at run time,
using the property, you should write a routine that applies the
changes and call it from the form's Page_Load event.
Usually, the property is set to a specific
path on the server. If you set it to a file name without a path,
will look for the report definition on the path where the page is located.
Gets a reference to the object that controls how reports
are cached on the server.
The report cache is one of the most powerful features in the
control. By default, every time the control renders a report, it compresses the resulting
Html stream and stores it in the object. If the same report is
requested again, the control simply fetches it back from the cache and sends it directly
to the client. This results in fast response times and consumes little memory (because the
reports are cached in compressed form).
The control is smart enough to detect changes to the report definition and keep track
of different versions in the cache. It also detects changes to the report definition file
and discards old reports from the cache.
The cache object itself is provided by the ASP.NET framework (
property), and can be set up to match your server configuration, including Web Farm scenarios.
The object allows you to disable the cache, specify time out
values, and add dependencies (to data source files for example).
The code below configures the to keep rendered reports in the
cache for one hour, renewing the time out period every time a report is retrieved from the
cache. It also adds a dependency on a SQL server database file, so whenever the underlying
data changes, the control know that the report must be rendered again (the report definition
file is automatically added as a dependency).
// enable cache
_c1wr.Cache.Enabled = true;
// cached reports expire after one hour
_c1wr.Cache.Expiration = 60;
// renew one-hour limit whenever a report is retrieved from the cache
_c1wr.Cache.Sliding = true;
// add dependency on SQL server data file
_c1wr.Cache.FileDependency = @"c:\MSSQL7\Data\pubs.mdf";
Gets a reference to the object that controls the
appearance of the built-in navigation bar.
The built-in navigation bar is useful when you are rendering paged reports
(see the property) and you don't want to write a custom
navigation bar to allow user to page through the report. The built-in navigation
bar is easy to use and customizable. You can set the text displayed in the bar and
the Style used to render it.
If the customization provided by the built-in navigation bar is not enough
to suit your needs, you can set the
property to false and write your own custom navigation bar. The "CustomNavBar" sample,
provided with the control, shows how to do that.
In most cases, you will set up the at design time, using
the standard Style editor. However, you can also set it at run time, as in the example
below:
_c1wr.Paged = true;
_c1wr.NavigationBar.Visible = true;
_c1wr.NavigationBar.Text = "Page {0} of {1}";
_c1wr.NavigationBar.Style.BackColor = Color.Black;
_c1wr.NavigationBar.Style.ForeColor = _c1wr.BackColor;
Specifies whether the report control should have scrollbars or autosize to fit its contents.
By default, the report will be rendered within the bounds of the control, and scrollbars
will be added so the user can see the entire contents of the report. If you set the
property to false, the control will automatically resize itself on
the page to fit its contents.
Specifies whether the report should be rendered as a single continuous document or broken up
into pages.
If you set the property to true, the report will be broken up into pages,
rendered one at a time on the client. In this case, you should either set the
property to true or provide a custom
navigation bar yourself, so the user an browse through the pages to see the entire report.
Specifies whether the control should generate javascript code to allow users to collapse
and expand report sections with the mouse.
The ability to expand and collapse report sections makes it easy to analyze and
understand the data being presented.
For example, a user can collapse a catalog report by clicking on the report
header and see all the product categories at a glance. Then he can select the
category he is interested in and click the category header section to drill-down and
examine the individual products in that category.
Note that not all browsers support this capability. The most popular ones do,
including Microsoft's Internet Explorer, Mozilla FireFox, and Opera 8. Some older
browsers however, may not handle this at all, in which case the report will be shown
completely expanded.
Specifies whether drill-down reports should be initially displayed in a collapsed state.
This property is used with the property.
Gets or sets the index of the page being viewed (between 1 and ).
This property is useful if you want to implement custom navigation bars. For example,
you could have four buttons on the page to browse to the first, previous, next and last
pages. The buttons would be attached to event handlers that would set the value of the
property.
Setting the property to a value smaller than one or
greater than does not throw any exceptions. The control simply
adjusts the value and displays the nearest page.
These event handlers could be used to implement a custom navigation bar:
// handle navigation buttons
private void _btnFirst_Click(object sender, System.Web.UI.ImageClickEventArgs e)
{
_c1wr.CurrentPage = 1;
}
private void _btnPrev_Click(object sender, System.Web.UI.ImageClickEventArgs e)
{
_c1wr.CurrentPage--;
}
private void _btnNext_Click(object sender, System.Web.UI.ImageClickEventArgs e)
{
_c1wr.CurrentPage++;
}
private void _btnLast_Click(object sender, System.Web.UI.ImageClickEventArgs e)
{
_c1wr.CurrentPage = _c1wr.PageCount;
}
Gets the number of pages in the current report.
If the report is not paged ( property is set to false),
this property will always return one.
This property is useful if you want to implement custom navigation bars that
show a "Page n of m" message.
The code below updates a custom navigation bar to show the current page and page
count values:
// update bar state after page changes
private void _c1wr_CurrentPageChanged(object sender, System.EventArgs e)
{
int curr = _c1wr.CurrentPage;
int cnt = _c1wr.PageCount;
// update label
string str = string.Format("This is page {0} of {1}", curr, cnt);
if (curr == 1) str = "This is the first page.";
else if (curr == cnt) str = string.Format("This is the last page ({0}).", cnt);
_lblCurrent.Text = str;
}
Specifies whether field contents should be encoded to render Html elements as literals,
or as raw Html content.
If you set the property to true, fields that contain Html
characters are encoded so the characters appear as literals.
For example, a field that contains "<b>Hello</b>" would be displayed in the
browser as plain text. The Html tags will be rendered and the "Hello" string would not be bold.
If you set the property to false, fields that contain Html
characters are rendered directly to the browser.
For example, a field that contains "<b>Hello</b>" would be displayed in the
browser as a bold "Hello".
Note that setting to false allows you to render fields with Html
content only into the browser. It does not work with Pdf reports.
Specifies whether the component should render Html reports using TABLE instead of DIV elements.
By default, generates Html reports using absolutely-positioned
DIV elements. You can use this property to generate Html reports based on TABLE tags instead.
TABLE-based reports don't use absolute positioning, so the resulting layout is usually
less accurate than the traditional DIV-based reports. On the other hand, they are easier to
modify in Html editors and offer better clipboard support (you can copy parts of a report and
paste them into Excel for example).
Gets or sets the method used to render report images on the client.
When a report contains images, the images must be transferred from the
server to the client separately from the report body.
This can be done in two ways:
Method 1: Set the property to .
This will cause the control to store the images in temporary files in the application folder. The
main report can then reference the images using regular IMG Html tags.
To use this method, the application must have permissions to create sub-folders and
write files to the application folder.
Method 2: Set the property to .
This will cause the control to store the images in the application Cache or Session depending on the
property value.
In this case, the main report will contain references to an HttpHandler that is used to return the image data.
To use this method, you must add an entry to the application's Web.config file.
<configuration>
<system.web>
<!-- add these: -->
<httpHandlers>
<add verb="*"
path="c1wrImg.imgx"
type="C1.Web.C1WebReport.C1WebReport, C1.Web.C1WebReport" />
</httpHandlers>
<!-- other settings... -->
This entry will cause IIS to invoke to process
the c1wrImg.imgx url, returning the requested image.
Gets or sets the method used to transfer image data.
Gets or sets the method used to transfer export data.
Gets or sets the method used to export the report.
Reports may be exported by calling the method, or directly
by the user, by clicking th export button on the report's navigation bar.
Specifies a folder for temporary files produced when exporting the report with the
property is set to .
The root application directory is assumed if a virtual path is not specified.
File security settings must allow writing by the anonymous web user.
Gets or sets the control to be shown during callback to provide visual feedback.
Gets or sets the Url of an image to be shown during callback to provide visual feedback.
Specifies whether the control should use Ajax to update its contents without refreshing the entire page.