Form Validations hands-on exercise!

Getting Started with the Agile Platform

Welcome to the Agile Platform! To get started with the Agile Platform and explore all the resources
the OutSystems community provides you, follow the steps below if you havent done so yet. If you
know all this, just skip this page and go on to the tutorial.

Download and Install the Agile Platform Community Edition

The Agile Platform is the first fully integrated platform for the delivery and management
of web business applications using agile methodologies. Download and install the free
version of the Agile Platform, and start developing your web business applications today!
http://www.outsystems.com/Download

Learn How to Use the Agile Platform

Learn Ad-Hoc
After installing the Agile Platform, Service Studio opens showing several tutorials you can
follow to learn how to use the Agile Platform. Simple sample applications are also available
to get started!
http://www.outsystems.com/GettingStarted

or Follow the Online Developer Training

If you prefer a more structured and in-depth training, follow the Online Training in the
Agile Network Academy. There you can also get certified as an Agile Professional!
http://www.outsystems.com/Academy

Engage with the Community

The Agile Network TechCenter provides you several discussion forums and
pre-built components to jump start your projects. Visit the Agile Network
TechCenter to engage with the community and share your own components
with the others!
http://www.outsystems.com/TechCenter

Ask for Help

Ask the Community
Ask the community, using the Agile Network TechCenter Forums. Engage with other agilists!
http://www.outsystems.com/AskCommunity

Ask OutSystems
Ask directly to OutSystems. Let us answer your questions, and give us your feedback. We want to hear from you!
http://www.outsystems.com/AskOutSystems

Associate Developer Training Advanced Topics 1

Form Validations hands-on exercise!

Form Validations hands-on exercise!

In the words of Sun Tzu: "To be prepared beforehand for any contingency is the greatest of virtues".

In this exercise you will learn how to bullet proof your application by applying a series of rules to
validate the user inputs, and elegantly handle unexpected errors (well... as elegant as an error can
be).

This hands-on is comprised of 2 exercises:

1. Validate user inputs

2. Handle exceptions
Are you a developer used to other programming languages and frameworks, such as .NET? Then use
this Developer Cheat Sheet as a companion while following these exercises. It describes the
OutSystems language main concepts and their mappings to other development languages.

The one minute guide to this lesson

In OutSystems we are all about getting the work done and thats why weve created these exercises.
By doing them youll practice what youve seen in the previous lessons and learn a bunch of other
cool stuff.

Take a minute to understand how all this is organized. Each exercise has 3 levels:

1.1 Tasks each task is comprised of a goal (its purpose) and a sequence of steps

Goal: <description of the task goal>

a) Steps Individual activities you must undertake to achieve your goal and complete your task
Instructions These are detailed descriptions of how to perform each step. They will vary in detail
depending on the expected familiarity with the given task.

During the course of the exercise, you can
decide the level of assistance you want.
Skip the instructions if youre looking for a
challenge and come back to them if you
get stuck.
The closer look boxes (like this one) provide you
tips and additional information regarding a step.
They may also contain links (in blue) to online
resources, namely the Agile Platform documentation,
where you can find more detailed information about
some of the concepts and tools under discussion. Dont
forget to check them out!

Note: With each hands-on exercise comes a baseline application, we recommend you use your own
application (the one that was the output of the previous hands-on exercises) instead, but if you prefer, you can
always use the baseline application provided with this exercise and proceed with the hands-on.

Associate Developer Training Advanced Topics 2

Form Validations hands-on exercise!

1. Validating the user inputs

1.1. Prevent Save if the form is not valid

Goal: Prevent the Save action from calling the CreateOrUpdateCONTACT

action if the Edit Record form is not valid.
a) Open the Contact_Edit Save Action.
Double-click the Contact_Edit Save Action in the eSpace Tree on the right (under
Screen Flows > Main Flow > Contact_Edit).
b) Rearrange the flow to get some free space before the CreateOrUpdate.
Youll be adding some logic between the Start element and the
CreateOrUpdateCONTACT action. Rearrange your flow by dragging the elements
(remember that you can select and drag more than one element at a time) in such a
way that you get some free space between the Start element and the
CreateOrUpdateCONTACT action.
c) Add an If element to the action flow immediately before the CreateOrUpdateCONTACT
action and set its label to Valid?.
Drag an If element from the left-hand tree until it is over the arrow and drop it only when the arrow turns
blue. Then change the Label property in the bottom-right of the screen to Valid?
d) Add the If element condition that checks if the Edit Record form is valid.
Open the Expression Editor for the If element Condition property by double-
clicking the If element in the action flow. Expand Widgets > EditRecord1 and
double-click the Valid property. Press OK to close the Expression Editor.
The Edit Records Valid property allows you to check whether all the
inputs inside this Edit Record (to be more specific, widgets with the Parent
Edit Record property set to this Edit Record) are valid. This property is True
only when all the widgets "inside" the Edit Record are valid.

You can learn more about the Edit Records runtime properties here.

e) If the outbound connector of your If element is the False path, swap the If element connectors.
Notice the label of the If element outbound connector. If its False this means your
CreateOrUpdateCONTACT action is on the False path and you want it to be on the True path. Right-click
the If element and select Swap Connectors.
f) Add an End element and connect the If element to the End element.
Drag the End element from the tree on the left of your
screen and drop it somewhere to the right of the If When the flow of a Screen Action
element. Connect the two together by dragging from the If ends in a End element, this means that
element to the End element when the cursor turns into a if the flow reaches this point, you want
cross. to immediately return to the screen.

Associate Developer Training Advanced Topics 3

Form Validations hands-on exercise!

1.2. Add an input validation to make sure te email is valid

Goal: Add the logic to check if the email is valid (lets assume an email is
valid if it has a @). If not, return an appropriate validation message.
a) Rearrange the flow to get some free space before the If element.
Youll be adding some logic between the Start element and the If element.
Rearrange your flow by dragging the elements (remember that you can select
and drag more than one element at a time) in such a way that you get some
free space between them.
b) Add an If element to the action flow immediately after the Start
element and set its label to Invalid Email?.
Drag an If element from the left-hand tree until it is over the arrow and drop it
only when the arrow turns blue. Change the Label property in the bottom-right
of the screen to Invalid Email?.
c) Add the If element condition that checks if the text in the input widget is a valid email.
Open the Expression Editor for the If element
Condition property by double-clicking the If
element in the action flow. Expand Built-in
Functions > Text and double-click the Index
function. Place the cursor in the first
argument. Expand Widgets > EditRecord1 >
Record > CONTACT and double-click the
Email attribute. Place the cursor in the
second argument and type @ (enclosed in
quotes because its a text literal). Type = -1
after the function call. Press OK to close the
Expression Editor.

This was the first time we used one of the Built-in Functions the Agile Platform provides you. You
have a lot more, spread through several folders and they may be used in any expression.

If you have any question regarding the behaviour of a specific function you can simply select it in the
scope tree and a short help text is displayed on the right.

In our case we used the Index function to determine if the search text @ existed anyware in the
Email the user typed. This function returns -1 if the search text isnt found.

You can have an overview of the available Built-in Functions here.

d) Add an Assign element to the action flow and set its label as Invalid Message. Connect the If
element to the Assign element and the Assign to the Valid? If.
Drag the Assign element from the left-hand tree and drop it in the empty space to the right of the Invalid
Email? If element. Change the Label property in the bottom-right to Invalid Message. Connect the
Invalid Email? If element to the Assign element by dragging between them when the cursor turns into a
cross and then connect the Assign element to the Valid? If element.

Associate Developer Training Advanced Topics 4

Form Validations hands-on exercise!

e) Set the assignments to mark the widget as not valid and an appropriate validation message.
Select the Assign element by clicking it in the action flow. Double-click
the Variable 1 assignment label (in the Properties box on the bottom-
right of your screen) to launch the Select Variable window. This
window displays all variables available on scope.
Expand Widgets > EditRecord1 > Widgets >
CONTACT_Email and pick Valid (through
double-click). In Expression 1 type False.
Notice that a new slot for a new assignment
was added in the Properties Box. Double-click the Variable 2 assignment label to
launch the Select Variable window. Expand Widgets > EditRecord1 > Widgets >
CONTACT_Email and pick ValidationMessage. In Expression 2 type Not a valid
email address. (enclosed in quotes because its a text literal).

You can learn all the details on validating end-user typed values in the online help.

1.3. Deploy the new version

Goal: Publish this version and test the application.

a) Verify your eSpace. Fix any errors or warnings you may have.
Press the Verify button in the Toolbar. If you have any errors or warnings, they will be displayed in the
TrueChangeTM window. Fix them until you have a valid eSpace.
You can double-click the Error and Warning messages and be redirected to the location where
the error was detected. The element/property that originated the message will also have the focus.

b) 1-Click Publish your eSpace.

Publish the eSpace by pressing the 1-Click Publish button in the
Toolbar or by using the F5 key.

If the Modified Version Detected Window appears,

simply press the 1-Click Publish button again, that is, select
the Continue Publishing local file option. For now, lets forget
about version conflicts in these lessons. You can learn more
about the Modified Version Detected Window here.

c) Test the features youve just implemented.

Press the Open in Browser button which will open the MyContacts application in your browser.

1.4. An additional validation rule

Goal: Add an additional validation rule to prevent the creation of contacts with an existing email.

We wont provide you the steps to complete this task. We want you
to try it for yourself, without assistance.
Challenge
Remember to test this validation for both the create and
update function. The update function has an extra twist because if
you didnt changed the email, the database already as a record with
that email the one youre editing.

Associate Developer Training Advanced Topics 5

Form Validations hands-on exercise!

2. Handling Exceptions

2.1. Add the error message display

Goal: Add the ability to display an error message to the

Category_Show screen.

We choose this action flow because it provides a typical

project scenario in which a referential integrity violation throws an
exception. Because the Foreign Key between CONTACT and
CATEGORY has the Delete Rule property set to Protect, the
referential integrity mechanisms are turned on. This means that if
the user tries to delete a Category that is already assigned to a
Contact, the database throws an exception.

a) Add a Local Variable to the Category_Show screen and name it ErrorMessage.

Right-click the Category_Show element on the eSpace Tree on the right. Select Add Local Variable and
type ErrorMessage as its name.

The variable will store the error message (if any). This way is pretty straightforward to
determine if we have an error: If we do, the variable is not an empty text; if we dont, the variable
wont be empty.

b) Open the Category_Show screen.

Double-click the icon on the eSpace Tree on the right (under Screen Flows > Main Flow).
c) Drag an Expression into the cell to the right of the buttons and format it as Text_Error.
Drag a new Expression widget from the toolbar on the left and place it in the cell to the right of the
buttons. Set the Expression widget Style property (on the bottom-right) to Text_Error.
You should, whenever it makes sense, setup the Expression widgets Example property. This
property has no runtime effect but it determines the text displayed in design time and it will help
you to better understand and document your screens. Do it now, set it for example as Error Message
and see what happens.

d) Set the new local variable ErrorMessage as the Expression value.

Select the Expression widget by clicking on it. Double-click the Expression property label (in the
Properties box on the bottom-right of your screen) to launch the Expression Editor so that you can see all
variables available on scope. Pick the local variable ErrorMessage (through double-click). Press Close to
close the Expression Editor.
If there is no error message, the expression will be an empty text and the end-user wont event
notice its there. Thats why we dont need any extra screen logic to prevent the Expression widget
from being visible in normal circunstamces.

Associate Developer Training Advanced Topics 6

Form Validations hands-on exercise!

2.2. Catch the Exception

Goal: Catch any Database Exception that may occur in the Delete
screen action of the Category_Show screen. Construct an elegant
error message to be displayed.
a) Open the Category_Show Delete Action.
Double-click the Category_Show Delete Action in the eSpace Tree on
the right (under Screen Flows > Main Flow > Category_Show).
b) Drag an Error Handler element and drop it somewhere to the
right of the existing flow. Set the exception to Database.
Drag an Error Handler element from the left-hand tree and drop it in
the empty space to the right of the existing flow. Pick Database from
the Select Exception window.
When an Exception is raised, the current execution flow is aborted and the flow restarts in the
Error Handler element that handles that exception. This new flow is called the Exception Flow. When
you set the Exception to Database youre stating that only exceptions originated from the database
will be handled (and we are looking for a referential integrity violation).

You can learn more about Types of Exception on the Online Help.

c) Add an Assign element to the Exception Flow and set its label to ErrorMessage. Connect the
Error Handler element to the Assign element.
Drag the Assign element from the left-hand tree and drop it in the empty space below the Error Handler
element and name it ErrorMessage. Connect the Error Handler element to the Assign element by
dragging between them when the cursor turns into a cross.
d) Assign to the ErrorMessage local variable a custom message to alert for the probable referential
integrity issue followed by the system
exception message.
Select the Assign element by clicking it in
the action flow. Double-click the
Variable 1 assignment label (in the
properties box on the bottom-right of
your screen) to launch the Select
Variable window that displays all
variables available on scope. Pick the
ErrorMessage local variable (through
double-click). Double-click the Expression
1 label to launch the Expression Editor.
Type in the expression as depicted.
Notice how the + operator is used
to concatenate text. Notice that after
you type in Session. the expression The Session variable ExceptionMessage stores the
editor autocomplete appears. message of the last exception raised.

e) Add an End element to the Exception Flow and connect the Assign element to the End
element.
Drag the End element from the tree on the left-hand and drop it in the empty space bellow the Assign
element. Connect the two together by dragging from the Assign element to the End element when the
cursor turns into a cross.

Associate Developer Training Advanced Topics 7

Form Validations hands-on exercise!

2.3. Deploy the new version

Goal: Publish this version and test the application.

a) Verify your eSpace. Fix any errors or warnings you may have.
Press the Verify button in the Toolbar. If you have any errors or warnings, they will be displayed in the
TrueChangeTM window. Fix them until you have a valid eSpace.
b) 1-Click Publish your eSpace.
Publish the eSpace by pressing the 1-Click Publish button in the Toolbar or by using the F5 key.
c) Test the features youve just implemented.
Press the Open in Browser button which will open the MyContacts application in your browser.
To test this feature, simply try to delete a category in use (a category that is assigned to at least
one contact). In this scenario the database referential integrity validations cause an exception and
the exception handling logic is called.

Wow! What an ugly error message coming from the database! To make this feedback prettier, go
back and revise the expression of the ErrorMessage local variable. Try not appending the session
variable ExceptionMessage

d) Congratulations!
Now take the challenge ahead and protect all your screens. To advance and learn more, continue your
Online Training, or follow the next tutorial Reuse Pages and Logic.

2.4. One more exception handling

Goal: Add an exception handling pattern (similar to the one you just did) to the Import action of the
Contact_Import screen (handle All Exceptions) that will detect
invalid file formats and display an appropriate message.

We wont provide you the steps to complete this task. We want you Challenge
to try it for yourself, without assistance.

To test this feature try to import a file which isnt an excel file (use a word document or a simple
text file). If you want to know even more about exception handling, check this out.

Associate Developer Training Advanced Topics 8

Form Validations hands-on exercise!

Find out more

Were sure it was a fun and impressive experience but this is just a glimpse of what you can do with
the OutSystems Agile Platform. Were hoping it spiced your curiosity about learning more.

The Agile Network Academy provides all the

information and resources on training and
certification.

http://www.outsystems.com/Academy

The Agile Network TechCenter provides

discussion forums and the pre-built
components to jump start your projects.

http://www.outsystems.com/TechCenter

Moving on
Thank you for completing this hands-on exercise! Its now time to move on to the next lesson But
before that, leave us your suggestions and questions.

If you have suggestions, feedback, or

questions, please use the options in Service
Studios Help menu.

Submit Feedback
To leave us your suggestions and feedback, either regarding
this training material or not. We want to hear you!

Ask the Community

To ask help to the Community and engage with your peers in
the Agile Network TechCenter Forums.
http://www.outsystems.com/AskCommunity

Ask OutSystems
To ask help directly to OutSystems. We are here to answer
any question, may it be technical or not!
http://www.outsystems.com/AskOutSystems

Associate Developer Training Advanced Topics 9