.png)
This article is about our Masterclasses available on Youtube, specifically supporting the April 2021 Masterclass.
Before we start:
- I’m not the source of the truth and what I’ll share it's based on our process at Hi Interactive;
- In my defense, during the last few years I've been responsible to manage my amazing front-end team and I’m not anymore putting my hands on code as a full-time developer. 😂
What is an App Template?
An app template is a feature available on the OutSystems Platform helping the teams to accelerate their work, reducing repetitive tasks, and also to promote consistency.
This was based on something that we called Starter App, at that time associated with the Silk UI Framework.
We started by using an eSpace (module) with pre-configured assets to help developers to start their new apps with a menu, layout, styles, login and other implemented features.
Today this feature is available on the Platform as a Template and it’s very helpful!
.png)
App template is not a theme!
Unfortunately, we’ve seen this happen many times, and this is a common mistake. Themes and templates are related but are not the same!
After creating a new app based on a template, the app cannot have any references to the Template! To apply centralized changes, make them in the theme, not in the Template.
.jpeg)
The template doesn’t go to Production
The template is a module with pre-configured assets to be cloned by the platform. Use it to start new app developments. It’s not a good approach to create new apps outside of the development environment.
One of the reasons to promote templates in other environments is related to bad references and mistakes when using the template as a theme.
.png)
This is for low code development
It’s important to have in mind that this is for low-code developers and has to respond to their needs. An App Template is a tool to accelerate development, to promote consistency and enable developers to focus on the business, reducing the repetitive tasks.
When you implement an App Template, please take into consideration the following:
- Try to follow familiar code conventions
I don’t agree with many things delivered by the platform, but I do recognize that following the existing rules will be more familiar and easier for others to understand. - Avoid dependencies
Reduce the number of dependencies. Usually an App Template only needs references to your theme and resource modules.
Sometimes to deliver custom login integrations we also need to reference those assets. - Reduce the expertise
A developer using an App Template doesn't need to understand how the layout or the menu works. Think like that time when you started developing your first app with OutSystems, just dragging entities and the CRUD (Create, Read, Update, Delete) was implemented for you… This is the experience that you need to deliver to someone who will use your App Template!
List of templates available on the Platform
You can find all the available templates in your environment by clicking on the New Application option and choosing “Start from scratch”.
The platform has three different templates available for you: Reactive web app, Tablet app, and Phone app. Under these options, we have the custom templates.
.png)
Let’s starting to create a new template
1 — Clone a template module from the OutSystems Style Guide
1.1 Install the OutSystems UI Reactive Style Guide Template app from the forge;
.png)
1.2 Clone the existing template
Open a Template_ReactiveStyleGuide. The system will show you a message related to the protection system modules. Don’t change anything, just clone it!
.png)
.png)
.png)
1.3 Rename it to Template_YourTemplateName
We suggest giving it a name related to the type of communication that it will cover, for example, Template_B2C_Theme or Template_External_Theme
The Template name should have the following code convention:
Template_<module_name>, where <module_name> is the name you wish to assign to the new template. Know more about at outsystems.com.
%20(1).png)
1.4 Set an image
The image associated with this new template needs to be square and we suggest a 256px size in PNG format.
%20(1).png)
1.5 Create a description for the module
This description it’s not only for describing the module itself but also to describe the template in the list.
.png)
1.6 Publish and move it from the independent modules to your new app.
When we clone modules, they are published in an Independent Module App available in your environment. We suggest moving the module to an app that avoids going to production in the future. We leave it on the theme documentation app (Live Style Guide).
.png)
Now your template will be available to be used when you want to create a new application from scratch.
.png)
2 — Setting your custom theme
After creating a new App Template, we need to define which theme will be responsible for giving the styles to your future apps.
2.1 Rename the app theme as you wish, for example, MyAppTheme;
%20(1).png)
You need to have a specific theme, even when you don't have any css. That's because you need to use a specific app layout (layout wrapper) so that you can have this layout to be automatically added inside the pages when they are created, and for it to happen the theme must be already defined.
%20(1).png)
2.2 Add a reference from your custom theme and set it as a Base Theme for your MyAppTheme;
%20(1).png)
2.3 To finish this process, remove all references from the Style Guide Theme.
3 — Create your own custom layout
Unfortunately (for me), OutSystems dropped the approach of having layouts on the UI framework, and this causes many troubles for our projects.
To solve this, we promote creating layouts inside the theme module to be referenced on the App Template as we do for all other components.
3.1 Create a new layout based on the LayoutTopMenu
Start it by copying the existing LayoutTopMenu to your theme module and rename it to Layout. We’ll refactor it by applying some extra placeholders and simplifying the content.
%20(1).png)
.png)
Copy the content from the blocks that help you to compose the LayoutTopMenu (Menu, MenuIcon, ApplicationTitle, and UserInfo) and integrate those contents with your custom layout. Keep the placeholders so they can receive dynamic content.
This will help you to isolate the UI, give you flexibility and easier maintenance.
%20(1).png)
Use the current LayoutTopMenu from your template as a wrapper. Add a reference to your custom layout and use it inside your layout wrapper with the predefined content for your App Template.
%20(1).png)
The handicap as you see in the image under is that this approach duplicates the placeholders for the content that changes between screens, like the Breadcrumbs, Title, Actions and the Main Content.
The big plus is the full control from the theme, helping future maintenance, and also the simplicity to be understood on changes made by other developers.
4 — Create a custom Layout login
Following the same approach from the main layout, you will create and isolate your custom layout login in your theme module.
4.1 Use the LayoutBlank and Login screen content
Copy the content from the Blank Layout and also the content from the Login screen and merge them into a single layout.
.png)
4.2 Define the placeholders
All fields and content need to be controlled by the developer when creating a placeholder. For example: Logo image, fields, and input labels.
Leaving placeholders filed with expected content is a great approach to help the developers using your layout.
.png)
4.3 The Layout Login doesn't need a wrapper
For the Layout Login you don’t need to create a wrapper in the Template, because usually it’s not repeatedly used.
.png)
4.4 Concerns about the isolated Form
This approach causes some concerns when for your login button you have Is Form Default as True. The Form is not detected by the platform because it’s inside of your layout!
.png)
The platform shows the warning “Expected Form — Is Form Default property will only have an effect on Buttons inside Forms.”, but don’t be worried, it still works! You can hide this warning.
.png)
5 — Custom Layout Blank
Like for the other layouts, follow the same approach here. Isolate the UI, create a custom layout in your theme module and use it in your template inside your Error Screen (Invalid Permissions).
.png)
6 —Integrate the Menu with the Layout
One of the biggest concerns about templates is the way how to manage the Menu, assuring an easier way for developers to configure the app navigation.
.png)
As an exception, we need to leave a Menu block on the Common flow to ensure the scaffolding. Try to leave only what it’s really needed, in this case, a Block named Menu, with a PageLinks container inside so it can be detected by the system and ensure a working scaffolding (ex: automatically add links when someone drags a screen on top of it).
.png)
Parameters and actions from the original menu can be available directly on the Layout.
%20(1).png)
7 — UserInfo component
We manage this component the same way as all our UI components, by isolating the UI from the business logic!
%20(1).png)
7.1 Copy the content from the UserInfo block.
What I suggest is to copy the content to your custom layout and leave a placeholder only for dynamic content.
%20(1).png)
7.2 Actions
In your Layout wrapper, add the actions that are necessary to get data and do the business logic.
%20(1).png)
7.3 Add content on the placeholder
Inside your Layout wrapper, use the corresponding placeholder (UserInfo) to add your common content and business logic that will be needed in the screens of your app.
%20(1).png)
7.4 Benefits
This type of approach gives you a flexible and easier way to apply UI changes to your user info in a single place (custom theme), affecting all the apps that will be created with your App Template.
8 — Images and other assets
We need to be careful about having images on the App Template.
Try to avoid having images in the App Template module, unless your images are not shared between apps.
%20(1).png)
A common mistake is related to the brand logo. Usually, the logo is shared between multiple apps, in this case, don’t use a logo from your App Template and reference it from the theme module. This way you will update your brand logo used between multiple apps in a single place.
9— leave Login and exceptions
.png)
It’s common to integrate new login systems, and App Template. The big plus is that you can leave the custom integration already done for all future apps.
10 — Configure an Error Screen
Probably this is the screen you forget the most. It’s not expected to have errors in our apps, but the truth is that they happen and we need to manage them with as fewer constraints as possible.
A good configuration with a clarified message and navigation suggestions will help the users. Delivering this on your App Template will be helpful for future apps.
10.1 Rename it
Change the Invalid Permissions screen name to ErrorScreen so this screen is customized and will be available to others needs, not only for the invalid permissions.
%20(1).png)
10. 2 Use layout blank
The reason for it is that you don’t want to show the menu or other information to some users without specific access permissions.
11 — Home screen
All applications have their own Home screen. It’s a good practice to have a screen with a menu link as an example for the developers to start from there and see how the screen and menu works.
%20(1).png)
12— Remove what is not needed
12.1 Remove unused dependencies
.png)
We know why Templates from OutSystems R&D have this amount of references, but we suggest removing them because developers will remove them.
The reason is to help new developers knowing that all these features exist. Usually, if you don’t see it, you don’t know you can use it.
12.2 Remove blocks
Well, this depends on what your template needs to offer, but what we suggest is just to leave what is really needed. So you can remove these:
- LayoutBase
- LayoutBaseSection
- LayoutSideMenu
- ApplicationTitle,
- MenuIcon
- UserInfo
13- test your template
.jpeg)
As a platform feature used by other developers, we need to pay attention to details, and we cannot also forget that the Template is an end-user core base module for many future apps. We need to give enough attention to this asset and obviously have a good quality process.
To ensure quality, these are the common tasks that we do on our processes:
13.1 Validate dependencies
Check if there are any dependencies to other modules that are not needed for your future apps, like sample data, live style guide, charts, etc.
1.3.2 Create a new app
Creating a new app with your template is a good way to check the quality of our custom template.
- Check the Service Studio preview. The design experience must be as similar as possible to a run time;
- Create new screens to ensure the layout and assets functionalities;
- Check the menu behaviors.
13.3 Ensure the scaffolding
Scaffolding is one the best Platform features, speeding up your development and generating automated code.
- Drag an entity to a flow and check if the screens list and detail (CRUD) are created and work properly;
%20(1).png)
- Drag an entity to the main content placeholder of a screen and check if the table was created well;
%20(1).png)
- Drag an entity to a form and check if the form fields were created well;
.png)
- Assure that the links are automatically generated at the menu block when dragging a screen on top of it.
%20(1).png)
13.4 Check the architecture dashboard
Finally, check your architecture dashboard to ensure that the base of your future apps already follows the best implementation rules.
Final Notes:
- This is for having a good base when starting new apps.
- Don’t forget to think about the experience for the developers that will be using it.
- Nothing of what was shared here is the unique way to do it. as we can see, we need some workaround and dependency on your needs.
- Scaffolding is important!
- Why is an empty theme in our app needed?
Because we have a layout wrapper, and the scaffolding needs to set layout on theme.
- Organization is important.
Leave flows and folders closed and the Home screen selected.
- Take care about preview
- Remove the dependencies from the Template that originally came from the copied assets;
.png){kind=small}
.png){kind=small}
