Reference Guide
Tutorials / ASP.NET Web Forms / Client/Server coming and going with Custom Actions
In This Topic
    Client/Server coming and going with Custom Actions
    In This Topic
    This tutorial assumes that you have fully followed the Your first DocuVieware ASP.NET Web Forms page tutorial first as its starting point is the end of it.
     Overview

    This tutorial shows how to implement a simple button whose action will be to draw a QR Code on the current document with a specified value that will be prompted to the user in a C# ASP.NET Web Forms project.

    DocuVieware™ requires .NET Framework 4.6 or above.
    The screenshots have been taken using Visual Studio 2015 and GdPicture.NET™ 14, it may differ from the current release.
     Preparing your action client side

    This tutorial shows how to implement a simple button whose action will be to draw a QR Code on the current document with a specified value that will be prompted to the user.

    Step 1: Add a button on the page and attach an onclick event to it that will execute a JavaScript function.

    Adding a button on the page.
    Copy Code
    <button onclick="drawQRCode(); return false;">Draw QRCode</button>

    Step 2: Add the JavaScript function that will call the PostCustomServerAction function from the DocuVieware™ JavaScript public API that is documented here.

    Adding the JavaScript function.
    Copy Code
    function drawQRCode() {
         var codeValue = prompt("Enter the text to encode", "DocuVieware");
         if (codeValue != null) {
             DocuViewareAPI.PostCustomServerAction("DocuVieware1", true, "drawQRCode", codeValue);
         }
    }

    Once in the Default.aspx page, here is what you now have:

     Handling your action server side

    The client side part is done, now you need to properly route the DocuVieware™ custom action event in the Global.asax.cs.

    Step 1: In the Application_Start,  subscribe to the CustomAction event and redirect it to a private handler named CustomActionHandler in this example for the sake of clarity.

    Handling the action server side.
    Copy Code
    protected void Application_Start(object sender, EventArgs e)
    {
        DocuViewareLicensing.RegisterKEY("XXXX"); //Unlocking DocuVieware
        DocuViewareEventsHandler.CustomAction += CustomActionsHandler;
    }
    private void CustomActionsHandler(object sender, CustomActionEventArgs e)
    {
        // if we are in the drawQRCode action and we have parameters
        if ((e.actionName == "drawQRCode") && (e.args != null))
        {
           Default.handleCustomAction(e);
        }
    }

    Now, each time the PostCustomServerAction JavaScript function is called client side, it will fire the event server side that will go into CustomActionHandler method, the actionName will be checked and dispatched accordingly.

    Step 2: Implement Default.handleCustomAction that does not exist yet so it won't compile. Because you are going to use GdPicture.NET™ to draw your barcode, you need to add some using in Default.aspx.cs.

    Step 3: Implement the event handler that will actually draw the QR Code:

    Implementing the event handler.
    Copy Code
    using GdPicture14.WEB;
    using GdPicture14;
    using System.Drawing;
    
    public static void handleCustomAction(CustomActionEventArgs e)
    {
        string barcodeValue = e.args.ToString();
        if (e.docuVieware.PageCount > 0)
        {
           // we need to check if the document is an image...
           if (e.docuVieware.GetDocumentType() == DocumentType.DocumentTypeBitmap)
           {
              int ImageID;
             GdPictureStatus status = e.docuVieware.GetNativeImage(out ImageID);
              if (status == GdPictureStatus.OK)
              {
                 GdPictureImaging oGdPictureImaging = new GdPictureImaging();
                 oGdPictureImaging.BarcodeQRWrite(ImageID, barcodeValue,
                  BarcodeQREncodingMode.BarcodeQREncodingModeUndefined,
                  BarcodeQRErrorCorrectionLevel.BarcodeQRErrorCorrectionLevelH,
                  0, 5, 4, 10, 10, 0, Color.Black, Color.Transparent);
              }
              else
              {
                 e.message = new DocuViewareMessage("Error during get native image : " + status.ToString() + ".",
                  "#ff5656", 2500, 300, 300, false, "130%", "normal",
                  "#ffffff", "none", "none", "48px", DocuViewareMessageIcon.Error);
              }
           }
           else
           {
              // ...or a PDF document
              if (e.docuVieware.GetDocumentType() == DocumentType.DocumentTypePDF)
              {
                 GdPicturePDF oGdPicturePDF = new GdPicturePDF();
                 GdPictureStatus status = e.docuVieware.GetNativePDF(out oGdPicturePDF);
                 if (status == GdPictureStatus.OK)
                 {
                   oGdPicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);
                    oGdPicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter);
                    oGdPicturePDF.DrawBarcodeQrCode(barcodeValue,
                     BarcodeQREncodingMode.BarcodeQREncodingModeUndefined,
                     BarcodeQRErrorCorrectionLevel.BarcodeQRErrorCorrectionLevelH,
                     0, 4, 1, 1, Color.Black);
                 }
                 else
                 {
                    e.message = new DocuViewareMessage("Error during get native PDF : " + status.ToString() + ".",
                     "#ff5656", 2500, 300, 300, false, "130%", "normal",
                     "#ffffff", "none", "none", "48px", DocuViewareMessageIcon.Error);
                 }
              }
           }
        }
        else
        {
           e.message = new DocuViewareMessage("Please load a document first.",
            "#ff5656", 2500, 300, 300, false, "130%", "normal",
            "#ffffff", "none", "none", "48px", DocuViewareMessageIcon.Error);
        }
     }
     Sending and receiving data with a custom action
    This part is demonstrated in the Barcode Recognition sample that is provided within the SDK installer (in the barcode_recognition_demo.aspx page).
    It is strongly recommend that you refer to it in order to understand fully how it should be used.

    Let's have a closer look at the PostCustomServerAction JavaScript function:

    PostCustomServerAction JavaScript function.
    Copy Code
    function PostCustomServerAction: function (docuViewareID, async, actionName, params, success, error)

    There are two extra parameters that you did not used in the previous example that are success and error.
    These two callbacks are used to run your own code on success or on error, they are optional functions you need to write on your own depending on what you want to achieve.

    The important part here is the success callback, this is through this one that you will be able to retrieve a result from the server action.

    Step 1: Define your success callback funtion:

    Success callback funtion.
    Copy Code
    function onBarcodeDrawingSuccess(result) {
         alert("result: " + JSON.stringify(result));
    }

    Step 2: You need to slightly change the parameter you are sending because you need it to contain the code value but the result as well, simply call it json.
    Then you can use it in the PostCustomServerAction call together with the success callback, like this:

    Changing parameters.
    Copy Code
    function drawQRCode() {
         var codeValue = prompt("Enter the text to encode", "DocuVieware");
         if (codeValue != null) {
             var json = {
                 value: codeValue,
                 example: false
             };
             DocuViewareAPI.PostCustomServerAction("DocuVieware1", true, "drawQRCode", json, onBarcodeDrawingSuccess);
         }
    }

    From now on, each time the custom action is called and successful, the onBarcodeDrawingSuccess function will be triggered.
    Step 3: You need to declare the structure of the new parameter you are passing, it has to exactly match with the JavaScript object you just created.

    Declaring the new structure.
    Copy Code
    internal class myCustomActionParameters
    {
         public string value { get; set; }
         public bool example { get; set; }
    }

    Step 4: The server side handling, to keep things simple, just change the boolean value called example from false to true.

    Server side handling.
    Copy Code
    public static void handleCustomAction(CustomActionEventArgs e)
    {
        // we need to properly cast the parameters according to the internal class we have defined...
        myCustomActionParameters myParameters = JsonConvert.DeserializeObject<myCustomActionParameters>(e.args.ToString());
        // ...so we can access to its content
        string barcodeValue = myParameters.value;
        if (e.docuVieware.PageCount > 0)
        {
           // we need to check if the document is an image...
           if (e.docuVieware.GetDocumentType() == DocumentType.DocumentTypeBitmap)
           {
              int ImageID;
              GdPictureStatus status = e.docuVieware.GetNativeImage(out ImageID);
              if (status == GdPictureStatus.OK)
             {
                 GdPictureImaging oGdPictureImaging = new GdPictureImaging();
                 oGdPictureImaging.BarcodeQRWrite(ImageID, barcodeValue,
                  BarcodeQREncodingMode.BarcodeQREncodingModeUndefined,
                  BarcodeQRErrorCorrectionLevel.BarcodeQRErrorCorrectionLevelH,
                  0, 5, 4, 10, 10, 0, Color.Black, Color.Transparent);
              }
              else
              {
                 e.message = new DocuViewareMessage("Error during get native image : " + status.ToString() + ".",
                  "#ff5656", 2500, 300, 300, false, "130%", "normal",
                  "#ffffff", "none", "none", "48px", DocuViewareMessageIcon.Error);
              }
           }
           else
           {
              // ...or a PDF document
              if (e.docuVieware.GetDocumentType() == DocumentType.DocumentTypePDF)
              {
                 GdPicturePDF oGdPicturePDF = new GdPicturePDF();
                 GdPictureStatus status = e.docuVieware.GetNativePDF(out oGdPicturePDF);
                 if (status == GdPictureStatus.OK)
                 {
                    oGdPicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);
                    oGdPicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter);
                    oGdPicturePDF.DrawBarcodeQrCode(barcodeValue,
                     BarcodeQREncodingMode.BarcodeQREncodingModeUndefined,
                     BarcodeQRErrorCorrectionLevel.BarcodeQRErrorCorrectionLevelH,
                     0, 4, 1, 1, Color.Black);
                 }
                 else
                 {
                    e.message = new DocuViewareMessage("Error during get native PDF : " + status.ToString() + ".",
                     "#ff5656", 2500, 300, 300, false, "130%", "normal",
                     "#ffffff", "none", "none", "48px", DocuViewareMessageIcon.Error);
                 }
              }
           }
           // now we change the example value we want to send back to client side
           myParameters.example = true;
           // and we put our parameter object into the proper one
           e.result = myParameters;
        }
        else
        {
           e.message = new DocuViewareMessage("Please load a document first.",
            "#ff5656", 2500, 300, 300, false, "130%", "normal",
            "#ffffff", "none", "none", "48px", DocuViewareMessageIcon.Error);
        }
    }
    See Also