Stencil object

Official Content

Stencils allow you to create compositions of UI controls in order to be able to define designs (without associated code) that can be reused in different objects.

They integrate the work of designers and developers and allow sharing designs (reuse them "as a unit" in different objects, export them, etc.).

You can even define several Stencils that have the same controls but are distributed or presented in different ways and this allows you to keep the same design in different objects but with variants.

Surely, they help you to define standards and add consistency, simplifying the implementation of Design Systems.

Below is described how Stencils can help you:

1. Reuse the visual design of a table control in multiple panels by wrapping it as a Stencil.

Consider the BitBitNews application, which manages and shows articles about cryptocurrencies as well as the latest valuations.

It contains the following Transactions:

Coin
{
   CoinId*
   CoinName
   CoinCode
   CoinImage
   CoinCurrentPrice
   CoinCurrentTrend
}

Article
{
    ArticleId*
    ArticleTitle
    ArticleImage
}

and two Panels for Smart Devices: Coins and News.

At runtime the panels will look as follows:

Stencils_Image0

The blue frames in the panels point out a design that is desired to be reused always to show the coins (a coin image followed by its code: Stencils_Image1). 

Initially, the News Panel for Smart Devices (whose object name in the KB is: ListArticles) is designed as shown below:

Stencils_Image2

The table that contains a coin code and a coin image (in this particular case the two controls that show the data are elements of an item collection variable which have been loaded with a certain logic) can be reused in other objects with the same design. So, it makes sense to wrap the table as a Stencil. To achieve this, right-click on the table and in the contextual menu select: Wrap as New Stencil.

Then, the following dialog is opened to enter a name for the new Stencil:

Stencils_Image3

After assigning a name to the Stencil and pressing the Create button, the Stencil will be created as a new object:

Stencils_Image4

You can make any change in the ShowCoin Stencil object (colors, controls movements, settings, etc.). Once saved, the changes will be reflected in the object that contains the Stencil (the ListArticles panel).

Even, to make the Stencil more generic, you can replace the &Categories.item(0).CoinCode variable with a new scalar variable (i.e. &CoinCode). Likewise, you can replace the &Categories.item(0).CoinImage variable with a new scalar variable (i.e. &CoinImage):

Stencils_Image5

Now suppose you remove the label associated with the image in the Stencil object:

Stencils_Image6

As already explained, appearance changes made to a Stencil object, are applied to the objects that contain the Stencil. So, the ListArticles panel does not show the label anymore:

Stencils_Image7

On the other hand, notice that the original variables were not changed in the panel, that is to say, the ListArticles panel still contains the original variables and the code that was defined for it. Other panels could share the same Stencil to inherit the layout and you may replace these two controls, for example, by attributes. 

What is applied and reused is the Stencil appearance.

When a second panel includes the Stencil and the two controls are replaced by two attributes, it is probably unnecessary to define the code for that load. The Stencil has nothing to do with the logic defined in the object.

Even though the layout and the appearance properties now can only be changed in the ShowCoin Stencil and not in the ListArticles panel (the panel layout shows the Stencil with gray color), while positioned on the Stencil in the panel, you can quickly access the Stencil object by right-clicking and selecting in the context menu: Open Referenced Stencil.

Stencils_Image8

Finally, to reflect the exact design that must be shown at runtime, in the Stencil object let’s swap the image with the code:

Stencils_Image9

and the ListArticles panel “receives” the corresponding update.

Now, suppose that another panel (ListCoins) is defined as shown below:

Stencils_Image10

The ShowCoin Stencil must be inserted in the grid on the left, because the coin image and the coin code must be shown with the standard design, being the first data to be shown for each line.

You can drag it into the grid from the Stencils window. After that, you only need to select each control of the ShowCoin Stencil and replace each suggested variable with the corresponding attribute (&CoinImage must be replaced with CoinImage, and &CoinCode must be replaced by CoinCode):

Stencils_Image12

Note: You can open the Stencils window by selecting in the main GeneXus Menu: View / Other Tool Windows.

Finally, as you may have noticed, in the first panel (ListArticles), the Stencil is inside a Flex Grid (which presents the data in a horizontal line) while in the second panel (ListCoins) the Stencil is inside a Standard Grid.

Watch Video (49s)
 

2. Swapping Stencils that contain the same controls.

Stencils can also be used to quickly change between alternative designs.

Suppose you continue working with the same Knowledge Base. Now suppose you are asked to modify the design of the coin by showing the coin image below the coin code:

Stencils_Image14

Instead of editing the ShowCoin Stencil you can save it as another Stencil object and update the second one to keep both design alternatives:

Stencils_Image15

As both Stencils contain the same controls, from an object that contains one of them, you can swap it with the other (or with any other defined that contains the same controls).

So, open for example the ListCoins panel and select the ShowCoin Stencil control. After that, search in the Stencils window the ShowCoin_TitleTopImageBottom and press its SWAP button:

Stencils_Image16

Thus, the referenced Stencil is the one you have chosen, and the design has changed accordingly:

Stencils_Image17

Note: You can decide to use the new Stencil only to show the coins in that way in that object, or in certain objects, or in all objects that show coins since coherence is maintained. The two Stencils correspond to the same concept of a coin, with two alternative designs.


3. Design for both Web and Smart Devices while maintaining conceptual unity. 

When designing an app for both Web and Smart Devices, there are some visual elements across both platforms that are conceptually the same, even if they have to be designed differently. To take this into account, Stencils contain two layouts, one for Smart Devices and another one for the Web.

For instance, in the BitBitNews Knowledge Base, the ShowCoin Stencil was designed for SD, but it offers a combo as the image shows, to switch between the layouts for SD and Web to edit both:

Stencils_Image20

The layouts need to be edited separately because, even if they look the same at runtime, they use different design properties and might contain different controls.

If being in a Web Panel object you open a Stencil by selecting Open Referenced Stencil, it takes you directly to its Web layout.
 

Availability

This feature is available as of GeneXus 15 upgrade 12

Scope

Objects Panel for Smart DevicesWeb PanelsWork With for Smart Devices
Controls Compositions of controls inside a table
Platforms Web (.NET,Java), Smart Devices (iOS, Android)

Videos

Start Video Stencils 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.