User Control object

Official Content
This documentation is valid for:

A User Control object is a type of object offered since GeneXus 16 to simplify the development of User Controls and code reuse in the GeneXus community.

Most important benefits

  • It provides the possibility to define User Controls in a built-in way into the Knowledge Base.
  • Allows you to base its appearance on a style provided by a designer, CSS Framework, etc.
  • Generates server-side HTML code, which means power, since it is easier to scale a server than the clients.

User control object sections

A User Control object contains three tabs:

UsercontrolObjectTabs

  1. Screen Template: In this section, you have to include the HTML code provided by designers or CSS Frameworks.
  2. Properties: In the Screen Template section you can replace static data (hard-coded) with properties names defined by you bounded by {{ }} with the objective of dynamizing the User Control. These properties names defined by you will appear in the Properties section, so that you can indicate their data types, default values, etc.
  3. Documentation

Also, something very important you must set for the User Control is its Base Style property (User Control object).

Sample

Suppose that you want to integrate SemanticUI controls to achieve the design of this Card:   

card_2018528141256_1_png

SemanticUI provides the HTML corresponding to this widget:

<div class="ui card"> 
   <div class="image"> 
      <img src="/images/avatar2/large/kristy.png"> </div> 
      <div class="content">
         <a class="header">Kristy</a> 
         <div class="meta"> <span class="date">Joined in 2013</span> </div>
         <div class="description"> Kristy is an art director living in New York. </div> 
     </div> 
   <div class="extra content">
       <a> <i class="user icon"></i> 22 Friends </a> 
   </div> 
</div>

Therefore, the necessary steps are as follows:

1. Create a User Control object:

UCNewObject_png

2. Paste exactly this HTML code in the Screen Template section of the User Control object:

CardCode_png

3. Proceed to replace fixed data with properties names defined by you enclosed between {{ }} to dynamize the User Control object.

e.g. {{ImageUrl}}, {{Title}}, {{MetaInfo}}, {{Description}} and {{ExtraContent}} are properties called with those names:   

<div class="ui card"> 
   <div class="image"> 
      <img src="{{ImageUrl}}"> </div> 
      <div class="content">
         <a class="header">{{Title}}</a> 
         <div class="meta"> <span class="date">{{MetaInfo}}</span> </div>
         <div class="description"> {{Description}} </div> 
     </div> 
   <div class="extra content">
       <a> <i class="user icon"></i> {{ExtraContent}} </a> 
   </div> 
</div>

Note that those properties are created in the Properties User Control tab, and there you can define their data types, default values, etc.

Once the object has been saved, it is ready to be used in a Web Panel object.

4. When creating a Web Panel, in the toolbox you can see that the "Card" User Control is available (under the KBUserControls group of controls) to be dragged to the form.

After dragging it, you can set the User Control properties in any GeneXus event. For example, in the Start event you can define:

Event Start
    card1.Title = "Facundo"
    card1.MetaInfo = "Born 2011"
    card1.Description = "Minecraft fan"
    card1.ExtraContent = "Doesn't have a Facebook account"
    card1.ImageUrl = "https://genexususa.com/wp-content/uploads/2017/08/Gaston-Milano-GeneXus-CTO-cropped.jpg"
EndEvent

You can set the properties at both Design Time and Runtime.

The result of running it is as follows :

resultadoUC_png

Event Management

It is possible to define events in the HTML code elements. The events available are the DOM (Document Object Model) events. 
Applying the above concept and using the Click event as an example, the code would look as follows:

<div class="ui card" {{OnClick}} > 
   <div class="image"> 
      <img src="{{ImageUrl}}"> </div> 
      <div class="content">
         <a class="header">{{Title}}</a> 
         <div class="meta"> <span class="date">{{MetaInfo}}</span> </div>
         <div class="description"> {{Description}} </div> 
     </div> 
   <div class="extra content">
       <a> <i class="user icon"></i> {{ExtraContent}} </a> 
   </div> 
</div>

and in the User Control events section, the OnClick event will be available.

Suppose in the Web Panel the following is programmed:

Event card1.OnClick
    msg("Hello User Control Object!")
EndEvent

Finally, when selecting Run, you will see that interactivity and connectivity have been generated in your control.

UCResultadoWithEvent_png

For more details about event management, visit this article.

User Control Containers

In the previous case, there is a rather specific control in the elements contained by the Card. Assuming that instead of entering something fixed in the extra content section you want to be free to include whatever you want in that slot, what should you do?

GeneXus allows doing this with the HTML 5 standard element called slot. A slot must be added to the extra content section (a div within the User Control) to be filled by the control's user.

The modified code is as follows:

<div class="ui card" {{Click}} > 
   <div class="image"> 
      <img src="{{ImageUrl}}"> </div> 
      <div class="content">
         <a class="header">{{Title}}</a> 
         <div class="meta"> <span class="date">{{MetaInfo}}</span> </div>
         <div class="description"> {{Description}} </div> 
     </div> 
   <div class="extra content">
       <a> <i class="user icon"></i> {{ExtraContent}} </a> 
       <slot name="extraContent" />
   </div> 
</div>

When opening the Web Panel, you can see that now there is a table within the User Control called "extraContent" to which any element of the toolbox can be dragged.
Suppose a TextBlock is added to define a new caption:

controlWithSlotSection_201852815817_1_png

When running it after the change, you can see that the footer has changed and shows the text defined in the TextBlock added:

UCResultadoWithSlot_png

User Controls with Collection properties

What if instead of wanting to show simple data you want to show a list?

For this purpose, there are properties of collection type.
Suppose that in addition to the data for the Card a list of categories is received to be displayed in the extra content as an HTML list (UL). So, you want to generate something like this:

<UL>
<LI>Facundo</LI>
<LI>Cecilia</LI>
<LI>Santiago</LI>
</UL>

To model this situation, the properties of Collection type will be indicated by adding a # as a prefix to the name.
By applying this to the Card control, the code will look as follows:

<div class="ui card" {{Click}} > 
   <div class="image"> 
      <img src="{{ImageUrl}}"> </div> 
      <div class="content">
         <a class="header">{{Title}}</a> 
         <div class="meta"> <span class="date">{{MetaInfo}}</span> </div>
         <div class="description"> {{Description}} </div> 
         <div>
            <UL>
            {{#Categories}}
               <LI>{{Name}}</LI>
             {{/Categories}}
             </UL>
         </div>
     </div> 
   <div class="extra content">
       <a> <i class="user icon"></i> {{ExtraContent}} </a> 
       <slot name="extraContent" />
   </div> 
</div>

When saving the control, GeneXus will realize that there is a new property of SDT Collection type and that each member of that collection needs a Name property.
Now you only need to define a variable of Collection type based on the SDT created, assign it to the Categories property of the control and load it in the Start event.

SDT:

SDTGenerado_png

Associating the SDT with the control (binding):

SDTBinding_png

Code to perform the load:

Event Start
   &Item = new()
   &Item.Name = "Facundo"
   &CategoriesItems.Add(&Item)
   &Item = new()
   &Item.Name = "Cecilia"
   &CategoriesItems.Add(&Item)
   &Item = new()
   &Item.Name = "Santiago"
   &CategoriesItems.Add(&Item)
EndEvent

The result is as follows:

ResultadoSDTBinding_png

Events in repetitive elements

If you wanted to trigger the Click event in every element of the previous iteration instead of triggering it in the highest hierarchical element in the HTML (the outermost one), how would you do it?
GeneXus automatically infers that it is a repetitive element, and when triggering the event, it makes the index of the selected element available in a property.

So, the Click event can be programmed as shown below:

Event card1.Click
    &Name = &CategoriesItems.Item(card1.CategoriesCurrentIndex).Name
    msg(&Name)
EndEvent

Clicking on each name displays it.

Availability

This feature is available as of GeneXus 16.

Scope

Platforms Web (.NET,Java)

See Also

SemanticUI Design System

Videos

Start Video User control object presentation at #GX28 (in Spanish)

Subcribe to this category's changes
Sub CategoriesAdd a new subcategory in this category
PagesAdd a new page in this category
Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.