Client properties.

Set values in the server-side and use them in the client-side

Sometimes client-side scripting may need information that must be retrieved in the server-side. Usually, acquiring this could be implemented by doing an asynchronous request to the server or other approaches.

Calipso has implemented its own way of doing that through client properties.

Concept

Some client-side control developed using JavaScript and Calipso needs to show some server information like its operating system name and version.

A client property will be a configuration added to the server control that will transmit the operating system name and version as a string to the client-side control.

How does it work?

Any server-side Comkarl.Web.UI.Controls.ScriptControl-derived control can override AddClientProperties** method.

Look at the next code:

    public sealed class OSInfo : ScriptControl
    {
        protected override string CommonID
        {
            get
            {
                return "OSInfo";
            }
        }

        protected override string ControlElementCssClass
        {
            get
            {
                return "OSInfoContainer";
            }
        }

        public string OSName
        {
            get
            {
                return Environment.OSVersion.VersionString;
            }
        }

        public override void AddClientProperties()
        {
            base.AddClientProperties();

            ClientProperties.Add
            (
                new ClientProperty
                {
                    Id = Guid.Parse("bb8ba24d-6d8a-4386-a98d-857758c6ed5c"),
                    Name = "OSName",
                    Value = OSName
                }
            );
        }

        protected override void OnLoad(EventArgs e)
        {
            base.OnLoad(e);

            JavaScriptManager.RegisterInclude
            (
                "Classes//UI/Controls/OSInfo",
                "Comkarl.Calipso.Web.SampleClient.Controls.OSInfo.ScriptControl.js, Comkarl.Calipso.Web.SampleClient",
                JavaScriptIncludeKind.Resource
            );

            JavaScriptManager.RegisterReference("Classes//UI/Controls/OSInfo");
        }
    }


And pay special attention to:
        public override void AddClientProperties()
        {
            base.AddClientProperties();

            ClientProperties.Add
            (
                new ClientProperty
                {
                    Id = Guid.Parse("bb8ba24d-6d8a-4386-a98d-857758c6ed5c"),
                    Name = "OSName",
                    Value = OSName
                }
            );
        }


Above code shows how to add a client property. AddClientProperties** method override must call its base implementation because Calipso infrastructure uses some client properties.

After that, it's all about adding a ClientProperty** class instance to ClientProperties** property which exposes a list of client properties.

ClientProperty class has these mandatory properties:
  • Id. It's a unique identifier (GUID). It must be different than any other client property Id in any control.
  • Name. It must be the exact name of the property. It can't (this very important) start with:
    • get_
    • set_
    • Get
    • Set
  • Value. The value for property. Any object will be converted to string.

Note that is possible to add client properties just adding the ClientProperty class instance without creating a server class property. For example, previous code could look like this:
...
            ClientProperties.Add
            (
                new ClientProperty
                {
                    Id = Guid.Parse("bb8ba24d-6d8a-4386-a98d-857758c6ed5c"),
                    Name = "OSName",
                    Value = Environment.OSVersion.VersionString // <---- That's it!
                }
            );
...


Now you need to add the property in the client-side by hand. But Calipso will set the value in the client-side JavaScript control property for you.

Client-side part would look like next code:
$namespace.register("Comkarl.Calipso.Controls");

Comkarl.Calipso.Controls.OSInfo = $class.declare(
    function ()
    {
        // CREATE A CLASS FIELD FOR STORING OPERATING SYSTEM INFO COMING FROM SERVER-SIDE
        this.$_.osName = null;
    },
    {
        // PROPERTY GETTER FOR GETTING THE VALUE THAT CAME FROM THE SERVER-SIDE
        get_OSName: function() {
            return this.$_.osName;
        },

        // THE MANDATORY SETTER THAT WILL STORE THE OPERATING SYSTEM INFO COMING FROM THE SERVER-SIDE!!
        set_OSName: function(value) {
            this.$_.osName = value;
        },

        Render: function () {
            var lblText = $("<span />");
            
            // THEN, YOU JUST ACCESS THE GETTER OF YOUR CLIENT PROPERTY AND BINGO!
            lblText.text(this.get_OSName());
            lblText.addClass(this.get_ElementCssClass());

            $(this.get_ParentElementSelector()).append(lblText);
        }
    },
    Comkarl.Web.UI.Controls.Control
);

Comkarl.Web.PageContext.get_Manager().RegisterControl("OSInfo", Comkarl.Calipso.Controls.OSInfo);


Calipso uses conventions in order to guess that the property "OSName" set in the server-side has its counterpart "set_OSName" setter. The result is that you've shared a server-side value with the client-side control!

Last edited Jul 26, 2012 at 1:17 PM by MFidemraizer, version 9

Comments

No comments yet.