Chapter 4: Using Your Modules to Simplify and Encapsulate Your Code

The OutSystems platform was designed to simplify technical and architectural issues as much as possible. Thus, it offers different types of modules according to the needs and features that we want to develop. All just a few clicks away.

Here, we will learn what types of modules exist, their characteristics, and their purposes, as they relate to each other. We will also notice that the standardized nomenclature allow us and the platform itself to catalog the modules and applications in the correct layers of Architecture Canvas (also known as 3 Layer Canvas).

This chapter covers the following topics:

• Types of modules
• Distributing modules across applications
• Applying modules to the correct architecture layers
• Modules and application naming conventions

In the end, we will be able to identify where we should place our developments based on the role and purpose they fulfill.

Technical requirements

In this chapter we will cover how to create modules based on their types and name them in Service Studio, this being the base software for us to apply the knowledge that we will acquire here.

Types of modules

For a better understanding of this topic, we must make the following analogy: the application is the molecule and its modules are the atoms. Atoms can be of different types, according to their purpose. To this end, when creating modules within the application, five types are natively available:

• Reactive web app/phone app/tablet app: These are the modules that provide the final user interface for our applications. These are used to build and develop everything related to the frontend, from widgets and patterns to blocks and web screens. These modules can be used in the frontend layer to provide the pages and blocks that users will access for the foundation layer, to create themes, templates, custom patterns, and business-agnostic widgets.
• Blank: These modules are a blank screen. Here, the prebuilt components are initially minimally used, leaving the programmer the possibility to go their own way.
• Service: These modules are used from a Core Services perspective. These are the modules used for the backend code, where we create and manage our own databases and manage the code that ensures compliance with business rules.
• Library: As the name implies, these modules are business-agnostic libraries that are used to support mainly non-functional requirements. These modules usually belong to the foundations layer.
• Extension: Although we can invoke their creation through Service Studio, these modules are created and developed in Integration Studio. These serve to extend our platform, such as creating our C#/.NET code and abstracting it in OutSystems, creating connections with non-standard external systems, and connecting with external databases.

Service Studio's way of selecting the module type at the time of creation is as simple as a selection dropdown, as shown in Figure 4.1:

Figure 4.1 – Module types for web applications

In the previous case, the application is for the web, with the first type appearing as Reactive Web App. If it is a mobile application, the first type becomes Phone App, as shown in Figure 4.2:

Figure 4.2 – Module types for mobile applications

Note that, depending on the type of module, certain tabs may appear or disappear in Service Studio. For example, a module of the Service type does not have an Interface tab as it is not intended to contain frontend elements, just as modules of the Library type do not have a Processes tab, as it is not its purpose to make asynchronous processes available.

The types of modules allow us to distinguish their purpose, just as Service Studio characterizes with the right tabs and tools for each of them. This makes it more intuitive and easier to follow the concepts of our developments. In addition, it makes it easier to identify any relationship that exists between modules and applications and how they are distributed, which is what we will see next.

Distributing modules across applications

Modules must be organized within applications according to the layer to which they correspond. For this, we will be based on OutSystems Architecture Canvas, also called 3LC or 3 Layer Canvas.

Tip

The OutSystems architecture model from now on will simply be called 3LC.

This model is applied on two levels: the applications level and the modules level. What does this mean? Both applications and modules correspond to certain layers, and applications adopt the topmost layer of the module that constitutes it, which has the upper layer. For example, an application that contains a foundation layer module and a core layer module is from the core layer, since the top module that composes it belongs to this layer. If this application contains an end user layer module, it will assume the end user layer.

The typical OutSystems framework architecture layers and their properties are as shown in Figure 4.3:

Figure 4.3 – Framework layers and their properties

Info

We'll learn more about architecture issues in Chapter 13, Designing the Architecture of Your OutSystems Applications.

Although modules belong to a given application, they can be consumed as dependencies in other modules of other applications in order to reuse features and data models, thus preventing data and code replication.

To do so, Service Studio's Manage Dependencies functionality is used, as shown in Figure 4.4:

Figure 4.4 – Service Studio Manage Dependencies popup

Clicking on the Manage Dependencies link opens a popup with all modules that have public elements (otherwise they will not appear as available, as they are only from the context of the module in which they exist) where we can search for the desired module and the elements we are looking for. Finally, we just select the elements we want to reuse in the right column, click Apply, and that's it! It is available for use!

Tip

When a certain consumed element is updated or changed in its producer, we must open the Manage Dependencies console and refresh it (only in strong references or when a weak reference updates its signature). We can update the producer modules individually (those that have changes are identified with a refresh icon) or we can use the Refresh all button shown in the previous screenshot. If we are opening the module after these changes, Service Studio detects them and asks whether we want to open the Manage Dependencies console to refresh. If we do not perform this operation, we may have problems at runtime.

In this section, we can see that for our applications to be scalable, sustainable, and well organized, they must be built on a proven architectural template, the 3LC. This turns out to be like libraries; each book must be in the right place based on its content and subject in order to make your search simpler and allow the library to grow in the right way. It's the same with applications: the more organized, the easier it is to grow, scale, and maintain.

For this to work, we have to know how to catalog and apply modules to their layers correctly. Let's go see how to do that!

Applying modules to the correct architecture layers

In order to define our modules in the correct layers, we must know their purpose at the time we create them. For this, they can be categorized in different ways and depending on the layer they belong to.

Foundation layer

In this layer, we can have specific types of modules to support our applications; that is, they are like the foundations of a house. They serve to ensure that foundations are present, well organized, and reusable wherever they are needed.

Library modules

Library modules are business-agnostic modules that are a perfect match for the foundation layer, as they are intended to support non-functional or foundation functionalities of our applications, like the foundations of a house.

These modules can support the following types of artifacts:

• UI Flow: Group of screens or blocks
• Blocks: Set of sections for reuse on screens
• Images: jpg, jpeg, bmp, png, or diff files
• Themes: CSS file abstractions to use in screen customization
• Scripts: JavaScript code encapsulation
• Data Actions: Encapsulation of data handling for data that comes from external sources
• Server Actions and Client Actions: Encapsulation of handling and implementing components behavior
• Consumed and exposed integrations (SOAP, REST, and SAP): Abstractions of standard web service integrations
• Exceptions: Abstractions for handling errors or unexpected behavior
• Structures: Representations of in-memory data models
• Resources: Files used as a resource in our applications, such as Excel for data bootstrapping

  Tip

  If you are curious, you can see the official documentation on libraries here: https://success.outsystems.com/Documentation/11/Developing_an_Application/Reuse_and_Refactor/Libraries.

Extension modules

As the name implies, these modules are used to extend our platform. These modules work with Integration Studio, and we can create our own native C#/.NET code to integrate its functionality in our applications. We can create custom integrations with third parties and we can also connect our platform with external databases.

For this, these modules provide four types of elements:

• Actions: Encapsulation of handling and implementing business rules
• Structures: Representations of in-memory data models
• Entities: Representation of database tables in OutSystems
• Resources: Files used as a resource in our applications, such as Excel for data bootstrapping

When these elements are used by consumer modules, their visualization will be identical to elements from other types of modules generated and developed in Service Studio. This guarantees the standardization of OutSystems' low-code paradigm, in addition to abstracting the complexity of developing the code provided by the producer module.

Tip

If you are curious, you can see the official documentation on extensions here: https://success.outsystems.com/Documentation/11/Extensibility_and_Integration/Extend_Logic_with_Your_Own_Code/Extensions.

Core layer

In this layer, the modules that define the data models and business operating rules will be present. Here, we can find database Entities and Actions to manipulate them, synchronize them with external databases, and batch process information standardization.

Service modules

In our applications, we have to process, treat, and manage the concepts and business rules related to the problem we are solving. We often have to offer an extension of our application to third parties, both internal and external. Well then, service modules are meant to abstract, centralize, and guarantee this. These modules have core characteristics of our applications; they govern and process what the business needs, thus being directly associated with the core layer.

These modules can support the following types of artifacts:

• Service logic, using server Actions and service Actions
• Integrations (SOAP, REST, and SAP)
• Processes and Timers
• Database Entities

These modules have a very well-defined purpose at the backend level and, due to this context, they do not have frontend-related functionalities, such as the Interface tab and any kind of logic or artifacts related to that theme.

Tip

If you are curious, you can see the official documentation on services here: https://success.outsystems.com/Documentation/11/Developing_an_Application/Reuse_and_Refactor/Use_Services_to_Expose_Functionality.

End user layer

In this layer, the modules where we define our frontend will be present. Here, we will be presenting the screens that we will show our users, separated by the application concept in order to simplify and facilitate the segregation in the development for the future.

Reactive web/phone app/tablet app modules

Reactive web modules are nothing more than the modules where we develop our frontends for web applications (Reactive web app modules) and mobile applications (phone app or tablet app).

Note

In these modules, we create blocks and web screens that we show to the end user. By default, the only logic and Entities that exist in these modules are just frontend support and not related to the business. These modules can also be used to develop foundation layer features, more specifically, themes and UI templates.

All layers

There are types of modules that can be used in any of the layers, and they are presented as blank sheets, making available all of the existing features in Service Studio so that we can create our code freely and according to our needs without limit on customization.

Blank modules

Blank modules can be used transversely. What does this mean? Basically, it's a blank sheet that we can use to create whatever we want, in the context we want, with the necessary customizations.

By default, these modules are used in cases where the application's needs do not take great advantage of the prebuilt components of the previous types of modules.

In summary, for each of the existing 3LC layers, OutSystems provides different types of modules characterized and enhanced by the tools necessary for the characteristics of each one of them, thus ensuring greater robustness in the modular construction of applications and a more refined and precise architecture according to best practices.

However, we also show that this does not in any way remove the customization capacity or borders regarding what we need to do, as everything was designed to leave us free, but always with maximum security and prevention in order to avoid unnecessary mistakes and allow a greater focus on what matters: success!

Modules and application naming convention

To better identify the modules and applications we create, there is a convention advised by OutSystems for their names. This convention involves the use of suffixes, and although the suggestion is not mandatory (each one can follow its own normalization, as long as it is adequate), it is heavily used in the OutSystems world.

This convention is based on two attributes of modules and applications: their layer and their sub layer.

The following table explains the convention used today:

Figure 4.5 – Module naming conventions in OutSystems

* Nowadays, in frontend modules, suffixes are no longer used, because it is presented in the URL and is unfriendly if it has one.

** If they are modules dedicated to mobile, add an M before, such as _MCS or _MPat.

Based on the suffixes shown, the platform can correctly infer (in most cases) which layer and sub layer each module/application belongs to. This makes it easier to understand the general state of the architecture in our OutSystems software factory and what types of violations may or may not be occurring.

Summary

In this chapter, we get to know the various types of modules that exist, which layers they fit into, and what the conditions for this are.

In addition, we understood how to perform the naming in order to easily identify the purpose of each of the modules and respective examples.

Basically, if we adopt this kind of approach, development becomes much simpler, following one of the best software development practices: divide and conquer!

The next step, which we will cover in the next chapter, will be learning what types of Entities exist to store our data, how they are related, how to model them, and how we can populate them in a simple and fast way.

Ready, set, go!