New Business Types: Percent & Web Address (Andrew Lader)

New Business Types: Percent & Web Address (Andrew Lader)

Rate This
  • Comments 3

As many of you know, the first version of LightSwitch came with several built-in business types, specifically Email Address, Money and Phone Number.  In the upcoming release of LightSwitch, two new business types have been added: the Percent and the Web Address. In this post, I’m going to explain the functionality they provide and how you can leverage them in your LightSwitch applications.

The Percent Business Type

Starting with the Percent business type, this new addition gives you the ability to treat a particular field in your entity model as a percentage. In other words, your customers will be able to view, edit and validate percentages as an intrinsic data type. Like other business types in LightSwitch, it is part of the LightSwitch Extensions included with LightSwitch and is enabled by default.  Keeping this enabled gives you all of the familiar business types like Money, Phone and Email Address.

Using Percent in the Entity Designer

With this release, you can choose the Percent data type for a field in your entity, just like you can for the other existing data types. When you create a field, or edit an existing one, simply click on the drop down in the Type column of the entity; within the drop down list is a data type called “Percent”. Selecting it lets LightSwitch know that this field is to be treated as a Percent business type.

Percent Decimal Places Property

This business type shares some familiar properties that you can find on the Decimal data type, notably Scale and Precision.  And they are used in exactly the same way.  What’s new with the Percent business type is a property called Percent Decimal Places, though it is tied closely to the Scale property.  In practice, this value represents the number of decimals displayed when the value is formatted as a percent.  In other words, if it is set to 4, a value of 60% would be displayed as 60.0000%.  By default, this value is set to 2.  It must be greater than or equal to 0, but it can be no greater than 2 less than the value of the Scale property.

Choosing the Percent Business Type

For this introduction, I am going to use a simple application that records and displays how a community has voted on certain topics. There is one table, Topics, that tracks the votes for each particular topic being considered. As the image below shows, the Entity Designer for field types now contains Percent in the drop down menu:

TableTopicsPercentMenu

The Topics table is pretty basic, as the picture below illustrates. It contains fields for defining the name and description of the topic. And there are three integers which are used to record votes for Yes, No and Undecided. The other field of note is the ThresholdNeededToPass field, which is a Percent used to decide the percentage needed for the particular topic to pass. For example, it might be a simple majority like 51%, or it might be something higher like 60%. The last three fields are computed fields that present the percentage values for those in favor of the topic, those against it, and those that are undecided:

TopicsTableCropped

Percent Computed Fields

The code for the computed fields is also pretty simple and straight forward.  Here is the code I used to implement these computed properties using Visual C#:

        private decimal TotalNumberOfVotes
        {
            get
            {
                decimal totalNumberOfVotes = 0;

                if ((this.VoteYes != null) && (this.VoteNo != null) && (this.VoteUndecided != null))
                {
                    totalNumberOfVotes = (decimal)(this.VoteNo + this.VoteYes + this.VoteUndecided);
                }

                return totalNumberOfVotes;
            }
        }

        partial void InFavor_Compute(ref decimal result)
        {
            if (TotalNumberOfVotes > 0)
            {
                result = Decimal.Round((decimal)this.VoteYes / TotalNumberOfVotes, 6);
            }
            else
            {
                result = 0;
            }
        }

        partial void Against_Compute(ref decimal result)
        {
            if (TotalNumberOfVotes > 0)
            {
                result = Decimal.Round((decimal)this.VoteNo / TotalNumberOfVotes, 6);
            }
            else
            {
                result = 0;
            }
        }

        partial void Undecided_Compute(ref decimal result)
        {
            if (TotalNumberOfVotes > 0)
            {
                result = Decimal.Round((decimal)this.VoteUndecided / TotalNumberOfVotes, 6);
            }
            else
            {
                result = 0;
            }
        }

And here is the same code written using VB.NET:

        Private ReadOnly Property TotalNumberOfVotes() As Decimal
            Get
                Dim totalNumberOfVotes__1 As Decimal = 0

                If (Me.VoteYes IsNot Nothing) AndAlso (Me.VoteNo IsNot Nothing) AndAlso (Me.VoteUndecided IsNot Nothing) Then
                    totalNumberOfVotes__1 = CDec(Me.VoteNo + Me.VoteYes + Me.VoteUndecided)
                End If

                Return totalNumberOfVotes__1
            End Get
        End Property

        Partial Private Sub InFavor_Compute(ByRef result As Decimal)
            If TotalNumberOfVotes > 0 Then
                result = [Decimal].Round(CDec(Me.VoteYes) / TotalNumberOfVotes, 6)
            Else
                result = 0
            End If
        End Sub

        Partial Private Sub Against_Compute(ByRef result As Decimal)
            If TotalNumberOfVotes > 0 Then
                result = [Decimal].Round(CDec(Me.VoteNo) / TotalNumberOfVotes, 6)
            Else
                result = 0
            End If
        End Sub

        Partial Private Sub Undecided_Compute(ByRef result As Decimal)
            If TotalNumberOfVotes > 0 Then
                result = [Decimal].Round(CDec(Me.VoteUndecided) / TotalNumberOfVotes, 6)
            Else
                result = 0
            End If
        End Sub

Using Percent in the Screen Designer

In addition to having this new business type for your entities, your screens will be aware of the Percent business type as well. By default, the screen designer will use the Percent Editor control for fields of this data type, while computed fields of type Percent will default to using the Percent Viewer control. Like other business types, you can choose to use either control for fields in the screen designer:

ScreenDesignerPercentEditorMenu

How does it work in the Runtime?

Once you have an entity that contains a field of this type, and have created a screen that displays it, what will it look like when you run your application?

The Percent Viewer Control

The Percent Viewer control works just as you would expect.  Much like other viewer controls, it is a read-only, data-bound textbox that displays the percentage value like this:

PercentViewerControl

Please note that the format of the percentage value is based on the culture of the LightSwitch application.  In my example above, you can see another screen entitled “Vote On Topics”.  This is a straightforward screen I created using the Editable Grid screen template, and it lets you edit each topic in a grid.  I entered a value of 37 for the VoteYes field, 26 for the VoteNo field and 10 for the VoteUndecided field.  That’s what yielded the numbers you see in the image above.

Remember the Percent Decimal Places property we discussed earlier?  Close the application and change that property to a value of 4 for the Undecided computed field.  Now run it again.  You will see that the list details screen displays a value of 13.6986% instead of 13.70%.  This gives you some freedom to control how the values are displayed.

The Percent Editor Control

The editor control for the Percent business type will let your customers view and edit a percentage value, maintaining it to the user as a percentage even while editing.  For example, tabbing into the “Threshold Needed To Pass” field selects only the value, excluding the “%” symbol.  If the user were to then delete the value, the control will behave by removing the value but leaving the “%” symbol:

EditingPercentage01

Even if the user deletes the “%” symbol, it is restored after the user tabs off.  So for example, if the user deletes everything including the “%” symbol, and then enters a value of “60”, when they tab off, the field will display the following:

EditingPercentage02

The Web Address Business Type

The new Web Address business type provides you with the ability to represent hyperlinks in your application’s entity model and screens.  This means that your customers will be able to edit, test and use hyperlinks. And just like the Percent business type, the Web Address business type is part of the LightSwitch Extensions included with LightSwitch.

Adding it to an Entity

When editing fields in the Entity Designer, you can choose to add the Web Address data type by clicking on the drop down for the field’s data type.  This will yield the following menu:

TablePersonWebAddressMenu

I’m going to show a typical situation where this might be used.  Let’s say you have an application with a Person entity, and now you would like to track their public blog address in this entity as well.  We’ll accomplish this by adding a field with a name of “Blog Address” and then choosing Web Address as the type.  That’s pretty much all you need to do.

Using it in the Screen Designer

Now add a new List Details screen, and for the screen data, select the People entity.  When you examine content tree in the Screen Designer, you will see the Blog Address field with a new control called the Web Address Editor:

ScreenDesignerBlogAddressField

You will also see a Web Link control.  That is the read-only version control that displays a link based on the data in the field.  More on this in a moment.  In the meantime, leave the selection as the Web Address Editor.

How does it work in the Runtime?

So, we’ve added a field of type Web Address to an entity, and when we added a screen, we’ve seen that the field used the Web Address Editor control by default.  So let’s see what happens when we run our application.

The Web Address Editor Control

When you press F5 to run the application, you will see that there is a text box for the Blog Address field.  To the right of this text box is a greyed-out link button named “Test”.  To see how this works, let’s add a new person by clicking on the plus symbol over the list of people on the left.  You will see the following dialog:

WebAddressNewPersonDialog

Again, for the Blog Address field there is a text box followed by the greyed-out link button “Test”.  This time, let’s fill in a valid URL for the Blog Address field, say “http://microsoft.com” without the quotes.  The “Test” link button is now enabled:WebAddressNewPersonDialog01

This button link allows you to test the web address you entered into the field. When you click on the “Test” button link, your application will attempt to open the provided URL in your default browser. This gives your customers immediate feedback on the link value they entered.

As the image above also demonstrates, when you tab off and then back to the Blog Address field, only a portion of the URL is highlighted.  The reason is that the Web Address Editor control only accepts the HTTP and HTTPS protocols.  Let’s try this out.  Put focus on the field by tabbing off of it and then back to it.  Only the portion of the value after “http://” is selected, and when you begin typing, that’ the only part that’s edited by default.  Of course, you can remove the “http://” portion as well.  In fact, if you had only entered the value “microsoft.com” in the field and then tabbed off, you would have seen that the control prefixed the value you entered with “http://”.

To test the value you have entered without using the mouse, tab into the Blog Address field.  Once you have finished editing the value, tab off.  The focus is now on the “Test” button link.  Press the ENTER key to enable the same action as if you had clicked on the button link.

The Web Link Control

Let’s add a few people and save them, and then close the application.  Return to the Screen Designer and go to the Summary field of the List Column for the Person entity.  Click the drop down menu and change it from Summary to Table Layout.  You will notice that there are now read-only fields in the content tree for each of the fields in the Person entity.  Further, the control used by default for the read-only Blog Address field is the Web Link control:

ScreenDesignerBlogAddressField02

I made a few adjustments to make sure the links are visible: I set the minimum width size for the Web Link control to be 250, left-aligned the first and last name fields, and made the list column sizeable.  When you F5 the application, you will see now something like this:

WebLinkControl

The links are entirely clickable.  With the Web Address business type, your applications can now maintain your customers' web addresses in your data store and display them as valid links in your screens.

Wrapping up

With this post, I introduced you to the two new business types offered in the next release of LightSwitch: the Percent and the Web Address.  These types allow you to create applications that leverage percentage values and web addresses as intrinsic types.  The Screen Designer now offers you new controls to display these types in your screens, providing both an editor control and a read-only control for each new business type.  I’m pretty excited about these new business types, and I’m looking forward to seeing how everyone uses them in their applications.  Go ahead, create a new application and play with them.  Enjoy!

-Andrew Lader, Visual Studio LightSwitch Team

Leave a Comment
  • Please add 3 and 8 and type the answer here:
  • Post
  • Very useful, thanks

  • Cool, Thanks.

  • Is it possible to change the Test button to read something else or only show when a URL is entered?

Page 1 of 1 (3 items)