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 theOutSystems UI Reactive Style Guide Templateapp from the forge;
.png "OutSystems UI Reactive Style Guide Template")
1.2 Clone the existing templateOpen 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_YourTemplateNameWe 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_, where is the name you wish to assign to the new template.
Know more about at outsystems.com.
%20(1).png "Rename Template")
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 "An item from list of templates")
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 "Independent Modules app")
Independent Modules appNow your template will be available to be used when you want to create a new application from scratch.
.png "New Template App available")
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 "App Theme")
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 LayoutTopMenuStart 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 "Main Layout")
%20(1).png "Main Layout tree")
%20(1).png)
%20(1).png)
4 — Create a custom Layout login
.png)
.png)
.png)
.png)
.png)
5 — Custom Layout Blank
.png)
6 —Integrate the Menu with the Layout
.png)
.png)
%20(1).png)
7 — UserInfo component
%20(1).png)
%20(1).png)
%20(1).png)
8 — Images and other assets
%20(1).png)
9— leave Login and exceptions
.png)
10 — Configure an Error Screen
%20(1).png)
11 — Home screen
%20(1).png)
12— Remove what is not needed
.png)
13- test your template
.jpeg)
-
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.
-
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)
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.
