01-15-2008 09:00 AM
As mentioned in my previous blog entry, one way to create a dashboard component is to derive from Act.Framework.ComponentModel.Core.Dashboard.BaseComponent.
BaseComponent provides header text, footer text, a filter button and filter text as base controls on the component. The component also exposes properties to set the text, set the font of the headers/footers and the ability to turn off some of the controls (i.e. don't show the footer etc...).
To create a component that derives from BaseComponent the easiest thing to do is just have Visual Studio 2005 just create a new user control then just change the base class from UserControl to BaseComponent. You'll need to add a reference to the Act.Framework.ComponentModel.Core.dll to access that type.
After you have created the new control you'll need to add the Act.Shared.ComponentModel.CustomDashboardComponent attribute.
Here is the C# syntax for that:
[CustomDashboardComponent(true)] // This attribute tells ACT! that this class is a custom dashboard component.
This would be placed right above the class definition in the .cs file. You would also need a using statement at the top adding in the Act.Shared.ComponentModel namespace.
For ease of development I recommend creating another user control to put your content in and then put that user control in the center control area of the component that derives from BaseComponent. This allows you to use the Visual Studio designer to build your content.
BaseComponent exposes a CenterControl property. You would then add your user control to the Controls collection of the CenterControl of the class you dervied from BaseComponent.
Two useful virtual methods I'll mention are OnFrameworkDashboardComponentChanging and OnFrameworkDashboardComponentChanged. These methods fire before and after the ActFrameworkDashboardComponent is set. This is how your component would get access to the ACT! Framework SDK from within your custom dashboard component.
The ActFrameworkDashboardComponent has two important events for the dashboard data model. It exposes Connected and Display events.
These two events make up the data model of the dashboard.
Connected is fired when an ActFramework object is logged on to a database and is connected to the ActFrameworkDashboardComponent. This is when your component should retrieve it's data. The event is guaranteed to be called on the thread that created your control, but it is called asynchronously so the main ACT! can remain as responsive as possible. Your control should retain the data it loaded and not update the UI of your control until the next event.
The Display event is when your control should update it's UI with the data that was loaded previously in the connected event.
Once you sign up for these events you will participate in the same data loading model that the ACT! dashboard components do. When the dashboard view is loaded the connected event is fired and the consumers of the event are asynchronously called to load their data. Then when all the components have loaded their data a call is made to the ActFrameworkComponent and it then asynchronously fires the display event to have all the controls update their UI with the data.
Here is a sample of how to sign up for those events and how to property unregister from the events:
protected override void OnFrameworkDashboardComponentChanging(Act.Framework.ComponentModel.Core.Dashboard.ActFrameworkDashboardComponent oldFrameworkDashboardComponent, Act.Framework.ComponentModel.Core.Dashboard.ActFrameworkDashboardComponent newFrameworkDashboardComponent)
if (oldFrameworkDashboardComponent != null)
// Unregister from the old dashboard framework component's events.
oldFrameworkDashboardComponent.Connected -= new ActFrameworkComponent.ConnectedHandler(frameworkDashboardComponent_Connected);
protected override void OnFrameworkDashboardComponentChanged(Act.Framework.ComponentModel.Core.Dashboard.ActFrameworkDashboardComponent frameworkDashboardComponent)
if (frameworkDashboardComponent != null)
frameworkDashboardComponent.Connected += new ActFrameworkComponent.ConnectedHandler(frameworkDashboardComponent_Connected);
The Dashboard view will set the ActFrameworkDashboardComponent on any component that implements IFrameworkDashboardBoundControl. Since BaseComponent does this for you it gets an ActFrameworkDashboardComponent set at load of the dashboard. When this happens those two virtual methods are called before and after it takes place. When the user chooses a different dashboard the new ActFrameworkDashboardComponent will be null, this allows you to unregister from the events of the old ActFrameworkDashboardComponent so that your component can go out of scope. This also happens when you logout of a database. Note there is a defect in ACT! 10.0 gold that prevents callback with null for the ActFrameworkDashboardComponent on custom controls, this will be fixed in the first point release for 10.0.
The ActFrameworkDashboardComponent has a Framework property which you can use to get access to the current ActFramework object being used by the ACT! application.
Most of this applies to deriving from a user control instead of BaseComponent as well, I'll cover the differences in the next entry.