Developers Guide

Creating the client component of the settings control

In the client component of the settings field you get the values from the input fields and serialize them as a string. This string must then be returned as the value of the custom field control.

To create the client component, you must perform the following:

  1. Create a new .js file.
    In the folder of your custom payment processor, add a new JScript file.
  2. Mark the file as an embedded resource.
    Right-click on the file and select Properties. Set the Build Action property to Embedded Resource.
  3. Register the namespace of your custom control class.
  4. Define the client class.
    You must define a client class for your custom control. It must contain a component property for each of the input fields in the template. The values of these component properties will be the client IDs of the respective controls. Additionally you have to add a component property that will represent the delegate for the processing mode control. This will allow you to show/hide input fields when the  value of the processing mode field gets changed.
  5. Define the prototype for the client class.
  6. In the prototype definition create the needed functions.
    You will require the following functions:
    • initialize
      This function is called when the control is initialized. In it you create the delegates and assign them to the respective events. In this example, you have to create a delegate for the ValueChanged event of the processing mode control.
    • dispose
      In this function you have to call the base dispose method of the client class and to delete the delegate for the load event.
    • validate
      In this function you validate the values in the input fields. It must return true if the values are valid. You can specify the validation rules in the template. For more information, see Creating the template of the settings control.
    • reset
      In this function you setup the default values for the fields.
    • get_value
      This function must return a serialized string containing the values of the input fields.
    • set_value
      In this function you set the deserialized sequence of values to the _state property. If the application is loaded, call the updateUI function.
    • isChanged
      Implement this function if you want to specify whether the value has changed.
    • _applicationLoaded
      This is an event handler for the load event of the application. In it, set the app_loaded flag to true and call the updateUI function.
    • _processingModeControlHandler
      This is an event handler for the ValueChanged event of the processing mode field. Hide or show the respective section in the UI depending on the value of the processing mode control.
    • updateUI
      Update the values of the fields and the visibility of the sections.
    • _getSettingsObject
      In this function, get the values of the input fields and return them to the calling function.
    • _isArray
      This is a helper function, that must determine whether a variable is an array or not. It is used in the _getSettingsObject.
  7. Create getter and setter functions.
    Create a get and set function for each of the component properties that represent an input field.
  8. Register the client class.
    To register the client class, call its registerClass function and the full name of its type, and its base type.

Here is a code example:

/// <reference name="MicrosoftAjax.js"/>
/// <reference name="Telerik.Sitefinity.Resources.Scripts.jquery-1.6.3-vsdoc.js" assembly="Telerik.Sitefinity.Resources"/>
Type.registerNamespace("SitefinityWebApp.CustomPaymentProcessor");
 
SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField = function (element) {
    SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField.initializeBase(this, [element]);
    this._element = element;
 
    this._testPasswordControl = null;
    this._testUsernameControl = null;
    this._livePasswordControl = null;
    this._liveUsernameControl = null;
    this._timeoutControl = null;
    this._paymentTypeControl = null;
    this._processingModeControl = null;
    this._processorCreditCardsControl = null;
 
    this._processingModeControlDelegate = null;
 
    this._state = null;
    this._appLoadedDelegate = null;
    this._appLoaded = false;
};
 
SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField.prototype =
{
    initialize: function () {
        SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField.callBaseMethod(this, "initialize");
 
        if (this._appLoadedDelegate === null) {
            this._appLoadedDelegate = Function.createDelegate(this, this._applicationLoaded);
        }
 
        if (this._processingModeControl) {
            this._processingModeControlDelegate = Function.createDelegate(this, this._processingModeControlHandler);
            this._processingModeControl.add_valueChanged(this._processingModeControlDelegate);
        }
 
        Sys.Application.add_load(this._appLoadedDelegate);
    },
 
    dispose: function () {
        SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField.callBaseMethod(this, "dispose");
 
        if (this._appLoadedDelegate) {
            Sys.Application.remove_load(this._appLoadedDelegate);
            delete this._appLoadedDelegate;
        }
    },
 
    /* --------------------  public methods ----------- */
 
    // this method is called by definitions engine just before saving. It should return true
    // if value is valid; otherwise false. As our field control is composed of several other
    // field controls, we will validate them (remember, both this control and child controls
    // inherit base FieldControl JS component.
    validate: function () {
        if (!$(this.get_element()).is(':visible')) {
            return true;
        }
 
        // if only one of the child field controls fails, this (parent/container) field control
        // should fail as well
        var isValid = true;
 
        if (!this.get_timeoutControl().validate()) {
            isValid = false;
        }
 
        if (!this.get_processorCreditCardsControl().validate()) {
            isValid = false;
        }
 
        // here you can also perform other validations that could depend
        // on the values of multiple fields, so you have a very extensible
        // validation meschanism
 
        if (this.get_processingModeControl().get_value() == "live") {
            // validate live fields
            if (!this.get_livePasswordControl().validate()) {
                isValid = false;
            }
 
 
            if (!this.get_liveUsernameControl().validate()) {
                isValid = false;
            }
 
        }
        else {
            // validate test fields
            if (!this.get_testPasswordControl().validate()) {
                isValid = false;
            }
 
            if (!this.get_testUsernameControl().validate()) {
                isValid = false;
            }
 
        }
 
        // we return the aggregate result of all our validations
        return isValid;
    },
 
    reset: function () {
        // Setup default values
        // ProcessorCreditCards is set to undefined so updateUI handles both the 'New' and 'Edit' cases correctly.
        this._state = { 'TestPassword': '', 'TestUsername': '', 'LivePassword': '', 'LiveUsername': '', 'Timeout': '30000', 'ProcessingMode': '', 'ProcessorCreditCards': undefined, 'PaymentType': '' };
    },
 
    // Gets the value of the field control.
    get_value: function () {
        return Sys.Serialization.JavaScriptSerializer.serialize(this._getSettingsObject());
    },
 
    // Sets the value of the text field control depending on DisplayMode.
    set_value: function (value) {
        if (value !== null && value.length > 0) {
            var settingsObject = Sys.Serialization.JavaScriptSerializer.deserialize(value);
            this._state = settingsObject;
        }
 
        if (this._appLoaded) {
            this._updateUI();
        }
    },
 
    // Returns true if the value of the field is changed
    isChanged: function () {
        // TODO: implement
    },
 
 
 
    /* -------------------- events -------------------- */
 
    /* -------------------- event handlers ------------ */
 
    _applicationLoaded: function (sender, agrs) {
        this._appLoaded = true;
        this._updateUI();
    },
 
    _processingModeControlHandler: function (e) {
        $('.sf_payFlowProPaymentMode').hide();
        if (this.get_processingModeControl().get_value() == 'test') {
            $('.sf_payFlowProTestMode').show();
        }
        else {
            $('.sf_payFlowProLiveMode').show();
        }
    },
 
 
    /* -------------------- private methods -------------------- */
 
    // this method updates the user interface with the values from the state
    _updateUI: function () {
        this.get_testPasswordControl().set_value(this._state.TestPassword);
        this.get_testUsernameControl().set_value(this._state.TestUsername);
 
        this.get_livePasswordControl().set_value(this._state.LivePassword);
        this.get_liveUsernameControl().set_value(this._state.LiveUsername);
 
        this.get_timeoutControl().set_value(this._state.Timeout);
        this.get_processingModeControl().set_value(this._state.ProcessingMode);
 
        // By default we want all credit cards to be checked. We made the reset method set the state's ProcessorCreditCards to undefined.
        var creditCardValues = this._state.ProcessorCreditCards;
 
        if (creditCardValues === undefined) {
            creditCardValues = $.map(this.get_processorCreditCardsControl()._choices, function (choice) { return choice.Value; });
        }
        this.get_processorCreditCardsControl().set_value(creditCardValues);
 
        this.get_paymentTypeControl().set_value(this._state.PaymentType);
 
        $('.sf_payFlowProPaymentMode').hide();
        if (this.get_processingModeControl().get_value() == 'test') {
            $('.sf_payFlowProTestMode').show();
        }
        else {
            $('.sf_payFlowProLiveMode').show();
        }
    },
 
    _getSettingsObject: function () {
        var creditCards = this.get_processorCreditCardsControl().get_value();
        if (!this._isArray(creditCards)) {
            creditCards = [creditCards];
        }
 
        var settings = {
            'TestPassword': this.get_testPasswordControl().get_value(),
            'TestUsername': this.get_testUsernameControl().get_value(),
            'LivePassword': this.get_livePasswordControl().get_value(),
            'LiveUsername': this.get_liveUsernameControl().get_value(),
            'Timeout': this.get_timeoutControl().get_value(),
            'ProcessingMode': this.get_processingModeControl().get_value(),
            "ProcessorCreditCards": creditCards,
            'PaymentType': this.get_paymentTypeControl().get_value()
        };
        return settings;
    },
 
    // a more compact version
    _isArray: function (obj) {
        return (obj.constructor.toString().indexOf('Array') != -1);
    },
 
    /* -------------------- properties ---------------- */
 
    // gets the reference to the choice field which holds credit cards to be processed
    get_processorCreditCardsControl: function () {
        return this._processorCreditCardsControl;
    },
    // gets the reference to the choice field which holds credit cards to be processed
    set_processorCreditCardsControl: function (value) {
        this._processorCreditCardsControl = value;
    },
 
    // gets the reference to the choice field which holds available processing modes
    get_processingModeControl: function () {
        return this._processingModeControl;
    },
    // sets the reference to the choice field which holds available processing modes
    set_processingModeControl: function (value) {
        this._processingModeControl = value;
    },
 
    // gets the reference to the control that holds the test password of the payment processor
    get_testPasswordControl: function () {
        return this._testPasswordControl;
    },
    // sets the reference to the control that holds the test password of the payment processor
    set_testPasswordControl: function (value) {
        this._testPasswordControl = value;
    },
 
    // gets the reference to the control that holds the test username of the payment processor
    get_testUsernameControl: function () {
        return this._testUsernameControl;
    },
    // sets the reference to the control that holds the test username of the payment processor
    set_testUsernameControl: function (value) {
        this._testUsernameControl = value;
    },
 
    // gets the reference to the control that holds the live password of the payment processor
    get_livePasswordControl: function () {
        return this._livePasswordControl;
    },
    // sets the reference to the control that holds the live password of the payment processor
    set_livePasswordControl: function (value) {
        this._livePasswordControl = value;
    },
 
    // gets the reference to the control that holds the live username of the payment processor
    get_liveUsernameControl: function () {
        return this._liveUsernameControl;
    },
    // sets the reference to the control that holds the live username of the payment processor
    set_liveUsernameControl: function (value) {
        this._liveUsernameControl = value;
    },
 
    // gets the reference to the control that holds the timeout of the payment processor
    get_timeoutControl: function () {
        return this._timeoutControl;
    },
    // sets the reference to the control that holds the timeout of the payment processor
    set_timeoutControl: function (value) {
        this._timeoutControl = value;
    },
 
    // gets the reference to the control that holds the payment type of the payment processor
    get_paymentTypeControl: function () {
        return this._paymentTypeControl;
    },
    // sets the reference to the control that holds the payment type of the payment processor
    set_paymentTypeControl: function (value) {
        this._paymentTypeControl = value;
    }
};
 
SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField.registerClass("SitefinityWebApp.CustomPaymentProcessor.CustomPaymentSettingsField", Telerik.Sitefinity.Web.UI.Fields.FieldControl);

Next steps

+1-888-365-2779
sales@sitefinity.com

Related topics:

Feedback

How useful is this article?

Tell us more

Submit
Your message was successfully sent.

We appreciate your feedback.

Your message could not be sent.

OK