Archive

Archive for the ‘API’ Category

API: Example custom capture controller

December 11, 2009 Leave a comment

The DocEdge API allows you to customize the behavior of your work queue by creating a capture controller.  A capture controller is a .NET class that extends the Edge.DocEdgeUI.Capture.CaptureController object.  This article demonstrates how to:

  • Implement custom business logic.
  • Hide unnecessary fields.
  • Disable fields to create Read-only fields.
  • Hide or un-hide the Submit, Attachment, Email or Export buttons.
  • Automatically convert fields to upper or lower case.
  • Enable the Math feature to allows users to perform simple mathematical functions.
  • Disable drop down box text editor to only allow drop down values.
  • Enable the static feature to minimize load times for resource intensive look ups.
  • Configure a grid to stretch to fill the with of the screen.
  • Set the column width of a grid field.
  • Add functionality to the hot keys F5,F6, F7 and F8.
  • Add functionality by adding custom utility buttons.
using System ;
using System.Windows.Forms;
using Edge.DocEdgeUI;
using Edge.DocEdge.Api ;
using Edge.DocEdge.Api.Capture ;
using Edge.DocEdge.Api.Workflow ;
using Edge.DocEdge.Util ;
using Edge.DocEdge.Struct ;
using Edge.DocEdge.Validation ;
using Edge.DocEdge.Validation.Source ;
using Edge.DocEdge.Authentication ;
using Edge.DocEdgeUI.FieldView ;
using Edge.DocEdgeUI.Capture ;
using Edge.DocEdge.Capture ;
using Edge.DocEdge.Workflow ;
using Edge.DocEdge.Archival;
namespace TestAPI
{
    public class DocCap : Edge.DocEdgeUI.Capture.CaptureController
	{
        ///
        /// The Default constructor
        ///
	public DocCap()
	{
	}

        ///
        /// Hides or un-hides the submit button.  This is useful for work queues
        /// that should not user the default submit feature.
        ///
        public override bool SubmitVisible
        {
            get
            {
                return true;
            }
        }

        ///
        /// Hide or un-hide the attachment button.
        ///
        public override bool AttachmentVisible
        {
            get
            {
                return true;
            }
        }

        ///
        /// Hide or un-hide the email button.  Note: This will not allow
        /// users to access this feature if they are not granted the appropiate
        /// privilege from the management console.
        ///
        public override bool EmailVisible
        {
            get
            {
                return true;
            }
        }

        ///
        /// Hide or un-hide the export button.  Note: This will not allow
        /// users to access this feature if they are not granted the appropiate
        /// privilege from the management console.
        ///
        public override bool ExportVisible
        {
            get
            {
                return true;
            }
        }

	public override IContentDisplayProperties ContentDisplay
	{
  	    get
            {
                IContentDisplayProperties prop = base.ContentDisplay;

                // This is the an example of how to set the character casting
                // for a field.  Any characters in this field will
                // automatically be converted to uppercase.
                prop["INVOICE"]["INVOICE_NUMBER"].CharacterCasing
                            = CharacterCasing.Upper;

                // This is an example of how to hide a field.  The user will
                // not see this field on the field group.  You may still access
                // this field using the API.
                prop["VENDOR"]["REMIT_CODE"].Visible = false;

                // This is an example of how to disable a field.  The field
                // will be visible.  However, it will not be editable.
                prop["VENDOR"]["VENDOR_NUMBER"].Enabled = false;

                // The math property allows the user to perform
                // simple calculations in the text editor.  For example,
                // if the user enters "100.25+30" the system will convert
                // the value to 130.25.
                prop["CHARGES"]["FREIGHT_AMOUNT"].MathEnabled = true;

                // This property allows you to disable the text editor of a
                // combo box.  This forces the user to select an item from the
                // dropdown list and prevents any free-form data entry.  This
                // is useful if the captured value will ALWAYS be selected from
                // the dropdown list.
                prop["VENDOR"]["VENDOR_NAME"].ComboProp.EnableTextEditor = false;

                // A field may be marked as static.  A static field will be
                // created by the SmartClient only once.  This is useful for
                // dropdown boxes populated by time-consuming lookups.
                prop["VENDOR"]["VENDOR_NAME"].Static = true;

                // The fill method set to "Stretch" instructs the SmartClient to
                // stretch a grid to fill the width of the screen.  Setting the
                // fill method to "Compress" will collapse the to use the
                // minimum amount of space.
                prop["LINE_ITEMS"].FillMethod = GridFillMethod.Stretch;

                // The grid column width property allows you to set the
                // minimum column width in the grid.
                prop["LINE_ITEMS"]["ITEM_NUMBER"].GridColumnWidth = 200;

                return prop;
            }
	}

        ///
        /// The load method is called when the document or batch is loaded.
        ///
        /// A validation result object.
        public override ValidationResult Load()
        {
            return base.Load();
        }

        ///
        /// This method is called when each field receives focus.
        ///
        /// The field event argument.  This contains the
        /// field object associated with the event.
        ///
        public override ValidationResult FieldGotFocus(FieldEventArgs e)
        {
            return base.FieldGotFocus(e);
        }

        ///
        /// This method is called when a field loses focus.
        ///
        /// The field event argument.  This contains the
        /// field object associated with the event.
        /// A validation result object.
        public override ValidationResult FieldLostFocus(FieldEventArgs e)
	{
            // Get the default validation result
            ValidationResult result = base.FieldLostFocus(e);

            // Ensure the vendor name is not blank
            if (e.Field.FieldName == "VENDOR_NAME" && e.Field.Value == "")
            {
                // The message will be presented to the user
                result.Message = "Vendor name is required";

                // Set the status code to GeneralError to indicate an issue.
                result.StatusCode = ValidationStatusCodes.GeneralError;
            }

            return result;
	}

        ///
        /// This method is called when the field group receives focus.
        ///
        /// A validation result object.
        public override ValidationResult FieldGroupGotFocus()
        {
            MessageBox.Show("Field Group Got Focus: "
                  + Manager.FieldGroup.GroupName);
            return base.FieldGroupGotFocus();
        }

        ///
        /// This method is called when a field group loses focus.  Validations
        /// that need to compare/contract multiple fields should be placed in
        /// this method.
        ///
        /// A validation result object.
        public override ValidationResult FieldGroupLostFocus()
	{
            ValidationResult result = base.FieldGroupLostFocus();
            return result;
	}

        ///
        /// This method is called when the document or batch is
        /// about to be unloaded.
        ///
        ///
        public override ValidationResult Unload()
        {
            return base.Unload();
        }

        ///
        /// This method allows you to add custom functionality for
        /// the HotKeys F5, F6, F7 and F8.
        ///
        ///
        public override void ProcessHotKey(HotKeys Key)
	{
		switch( Key )
		{
			case HotKeys.F5:
			    MessageBox.Show( "Pressed F5" ) ;
			    break;
                	case HotKeys.F8:
	                    // The prompt note method displays a dialog
                            // to add a note to the passed content ID.
                	    DocEdgeUIAPI.PromptNote(
                                    this.Manager.CurrentPage.ContentID);
                    	    break;
		}
	}

        ///
        /// This method allows you to add custom utilities to
        /// your capture screens.  The SmartClient will call
        /// this method and pass the name of the selected utility.
        ///
        ///
        public override void ProcessUtility(string Name)
        {
            // In this example, a utility named "PO Search" has
            // been configured.
            if (Name == "PO Search")
            {
                // This is an example of performing a search.  This will
                // generate a search request and display the search results
                // to the user.
                IContent content = Manager.CurrentPage;

                // Create the search request
                IRetrievalRequest request = DocEdgeAPI.CreateEmptyRequest();

                // Add purchase order content type
                request.ContentTypes.Add(DocEdgeAPI.GetContentType(3));

                // Create a search criteria for the po number
                IIndex poNumIndex = DocEdgeAPI.CreateIndex("PO Number");
                poNumIndex.Value = content.GetFieldGroup("INVOICE")
                      .GetField("PO_NUMBER").Value;

                // Add your created index to the search.
                request.Indexes.Add(poNumIndex);

                // Send the user to the search screen.
                IRetrievalResult result = DocEdgeAPI
                       .ExecuteRetrievalRequest(request);
                this.Manager.DisplayRetrievalResult(result);
            }

            // In this example, the utility will run a configured report.
            if( Name == "Work Item Report")
            {
                DocEdgeAPI.RunReport(1);
            }
        }
    }
}
Advertisements
Categories: API