Base Class with universal logic for 'Shepherd Framework' (design and start of implementation)

From OpenPetra Wiki
Jump to navigation Jump to search

Shepherds Framework Introduction

The Shepherds Framework will be a support in creating individual instances of 'Shepherds' for openPETRA. 'Shepherds' are Installer-like Dialogs with Next-Back-Finish buttons. They have several steps/pages and through that offer a 'guided walk' to the openPETRA user on what key data to enter (or review) for a specific purpose.

Example Screenshots of an existing PETRA (not openPETRA) Shepherd can be found here.


Base Class Purpose


Desired Outcome

Key Requirements

  • Shepherds need to be based on a base Form (TPetraShepherdConcreteForm [which itself is based on TPetraShepherdForm]).
  • All attributes of the Shepherd need to be specifiable through a Shepherd Definition YAML file (Example: \csharp\ICT\Petra\Definitions\Shepherd_Church_Definition.yaml)
    • Title of the Shepherd
    • Size of the Shepherd Form...
    • All the Shepherd's Pages
    • MAYBE: some way of defining 'Conditions' in a terse way for page transitions, etc.
  • Navigation Buttons and Navigation Panel need to be able to be change states dynamically at runtime
  • Finish Page (UC_PetraShepherdFinishPage.yaml)
    • MultiLine TextBox for summarising data
    • optional second MultiLine TextBox underneath the first one (needed in the 'Intranet Registration Shepherd').
    • optional CheckBox that allows to kick off another process/open another window/another dialog after data was successfully committed to the DB (needed in the 'Intranet Registration Shepherd').
  • 'Sub-Shepherds' need to be possible
    • Realisation: specify all possible Shepherd Pages, incl. those of 'Sub-Shepherds' right away in the Shepherd Definition YAML file. Have the 'Sub-Shepherd' pages invisible initially and shown them once a 'Sub-Shepherd' is entered.
  • Ability to start off at an arbitrary page, which will become the 'first page'.
    • This implies that when the user clicks 'Back' he can't go further back than this 'first page'!
  • UserControls that form the individual Shepherd Pages will need to be able to communicate with the Shepherd and be able to react on certain Events that the Shepherd might emit.
    • These UserControls could be any UserControl within openPETRA, but they would need to implement certain Interfaces (IPetraEditUserControl and Ict.Petra.Client.CommonForms.IFrmPetra). Examples: UC_PartnerDetails_Church.yaml, UC_PartnerDetails_Family.yaml.
  • Pop-up Dialogs (=Modal Windows) from within the UserControls which form the indiv. pages need to be possible.
    • These Dialogs could be any Dialog Form (=Modal Window) within OpenPetra, but it would need to implement a certain Interface (needs to be created)
    • Data from those Dialogs needs to flow back to the UserControl, not to the DB directly as things are only committed at the end when the user presses 'Finish'!
      • such Dialogs need to be able to communicate with the Shepherd (especially the data entered or the user's choice on something);
      • such Dialogs need to be able to know that they must not save data when pressing OK but to instead only hide themselves and to not close themselves.
  • Navigation Panel on the left, collapsible
    • Show all available Shepherd Pages as a Collapsible Panel (TPnlCollapsible Control) which hosts a Task List (TTaskList Control) in 'vsShepherd' Visual Style.
      • Some Shepherd Page LinkLabels might be disabled - initially ('Enabled' attribute in the Shepherd Definition YAML file), or at run time, or enabled at run time.
      • Some Shepherd Page LinkLabels might be hidden - initially ('Visible' attribute in the Shepherd Definition YAML file), or at run time, or shown at run time.
  • Navigation Buttons 'Back' and 'Next' need to skip disabled and hidden Shepherd Pages when clicked!
  • Show progress through the Shepherd's Pages
    • Show 'Page x of y' in a Label Control of the Shepherd Form.
      • Note: 'y' can change dynamically at run time as Shepherd Pages can be hidden/shown at run time!
    • Show percent complete in a ProgressBar Control of the Shepherd Form.
  • Some Shepherds will not only be used to enter new data, but also will need to be able to load existing data into the Shepherd for editing (e.g. the 'Personnel Data Shepherd', found in Chapter 2.3 of the Petra 2.3 Personnel User Guide)!

Outline of the Solution

Step 1

Create a new Class in Project 'Ict.Petra.Client.CommonForms.Logic' (found in \csharp\ICT\Petra\Client\CommonForms\logic). Name of the Form Class File: 'PetraShepherdForm.cs' Name of the Form Class: 'TPetraShepherdFormLogic'


To Be Continued in Class...


Approval of Functionality and Program Code


Follow-on: Thoughts on Implementing the Server Side of the Shepherds

See Thoughts on Implementing the Server Side of the Shepherds

Update January 2013

ChristianK brought the 'Shepherd Framework' in line with trunk, cleaned it up and made it to mostly conform to our OpenPetra Coding Standard and Guidelines. He also fixed two Unit Tests that were broken when the students left that branch.

The framework consists of several Classes, an Interface and a generic GUI in which UserControls with functionality can be hosted at run time:

UML Diagram showing the Classes involved

The implementation for two very basic Shepherds got started to prove that the Shepherd Framework can underlie and drive OpenPetra Shepherds as we are planning to have them. Simply uncomment the lines that contain 'AddNewFamilyShepherd' and 'AddNewChurchShepherd' to launch the two Shepherds from the OpenPetra Main Menu.

The client-side implementation is far from complete and the handling of data, let alone saving or loading of data has not been implemented yet. Nothing was done yet for the server-side aspects of Shepherds.

Basic Documentation as written by the students:

  • /doc/Shepherd Framework.html