Skip to main content

Expense App Tutorial

note

This tutorial goes straight to the point. If you want to get more context around what you are doing, take a look at our Guided Overview, or to our DRAW Reference Guide.

The goal of this tutorial is to create multi-screen app with Olympe DRAW. It consists in a basic Expense App where a user can create new expenses with basic details, take a picture of the receipt and then consult the expenses created. You can find the final result in the Examples / Expense project.

We will build the app as follows:

  • We start by creating the data model to store our expenses
  • We then add some logic bricks to make it easy to manipulate our expenses
  • We then move to the UI and build the various screens

Folder

1. Project#

Let's start by creating a project that will contain our expense app.

Folder

1. Create a Project and name it "Expense" and open it
2. Create the following Folders
- Data
- UI

2. Data#

2.1 Data Model#

Expenses will need to be created and stored. Our expenses will have a description, an amount, a currency and a picture of the receipt. Let's now create a data model to describe our expenses.

Data Model

1. Open the Data folder
2. Create a new Data Model, name it "Expense Data Model" and open it
3. Create a new Business Model and name it "Expense"
4. Add following Properties to Expense Model
- description (String)
- amount (Number)
- picture (File)

The currency is a bit different, as it is taken from a list of possible values (CHF, EUR, ...). We therefore need to describe it as a separate model, and link it to our expense as a relation rather than a property.

1. Create a new Business Model and name it "Currency"
2. Add the following Property to Currency Model
- name (String)
3. Add the following Relation to Expense Model
- currency (Currency)

2.2 Data Set#

Our expenses will be created by users directly within the application. Currencies on the other hand need to be set once and for all, which we do using a data set. During this step, we therefore define the currencies available when creating expenses.

Data Set

1. Go back to Data folder
2. Create a new Data Set, name it "Currencies" and open it
3. Click on Currency and add following entries
- CHF
- EUR
- USD

3. Data Logic#

Now that we have defined the data model for our expenses, we can think about how we will manipulate those expenses: they need to be created, updated, displayed, etc. To make it very easy to perform those activities once we get to the UI, we create a few helper functions and actions (also called constructors, getters and setters in standard programming terminology).

3.1 Create Expense Action#

Let's start with an action to create a new expense. In a nutshell we need to:

  • Define the inputs we need to create the expense
  • Create the expense and persist it (i.e. save it in the database)
  • Set the description, amount and currency and finally save it in the database.

Hopefully, DRAW will make most of the job for us.

Create Expense

  1. Go back to Data folder
  2. Open the "Expense Data Model"
  3. On "Expense" model, click on the 3 dots icon to open the contextual menu
  4. Click on "Generate helper bricks"
  5. Select folder "Data" and click on "Save to Data" button
  6. Select "Constructor" and unselect "picture" (see screenshot below)
  7. Click on continue
  8. Once the bricks are generated, click on close
  9. Go back to Folder "Data" => A new brick named "Create Expense" was generated.

Create Expense

3.2 Get Expense's Attributes Function#

We now create a helper Function to make it easy to retrieve the Expense's values.

  1. Go to Data folder
  2. Open the "Expense Data Model"
  3. On "Expense" model, click on the 3 dots icon to open the contextual menu
  4. Click on "Generate helper bricks"
  5. Select folder "Data" and click on "Save to Data" button
  6. Select "Getter"
  7. Click on continue
  8. Once the bricks are generated, click on close
  9. Go back to Folder "Data" => A new brick named "Get Expense's attributes" was generated.

Get Expense's Attributes

3.3 Set Expense Picture Action#

We now create an Action to attach the picture of the receipt to the expense.

  1. Go to Data folder
  2. Open the "Expense Data Model"
  3. On "Expense" model, click on the 3 dots icon to open the contextual menu
  4. Click on "Generate helper bricks"
  5. Select folder "Data" and click on "Save to Data" button
  6. Select "Setter" and unselect every properties except "picture" (see screenshot below)
  7. Click on continue
  8. Once the bricks are generated, click on close
  9. Go back to Folder "Data" => A new brick named "Set Expense's attributes" was generated.
  10. Rename the brick to "Set Expense's picture"

Get Expense's Attributes

3.4 Get Currency's Attributes Function#

We now create a helper Function to make it easy to retrieve the Expense's values.

  1. Go to Data folder
  2. Open the "Expense Data Model"
  3. On "Currency" model, click on the 3 dots icon to open the contextual menu
  4. Click on "Generate helper bricks"
  5. Select folder "Data" and click on "Save to Data" button
  6. Select "Getter"
  7. Click on continue
  8. Once the bricks are generated, click on close
  9. Go back to Folder "Data" => A new brick named "Get Currency's attributes" was generated.

3.5 Format Expense Summary function#

We now create a helper function that will return a summary of the expense, including the currency, the amount and the description (e.g: USD40-Description)

Set Expense

1. Go back to Data folder
2. Create a new Function, name it "Format Expense Summary" and open it
3. Create an input, name it "expense" and set type to Expense
4. Add "Get Expense's attributes" function and configure as follow:
a. Connect the function input "expense" to "Get Expense's attributes" Object input
5. Add "Get First Object In List" function and configure as follow:
a. Connect "Get Expense's attributes" currency output to "Get First Object In List" Object List input
5. Add "Get Currency's attributes" function and configure as follow:
a. Connect "Get First Object In List" Object output to "Get Currency's attributes" Object input
7. Add 3 "Concat" functions to concatenate the following texts:
a. name output of "Get Currency's attributes"
b. amount output of "Get Expense's attributes"
c. " - "
d. description output of "Get Expense's attributes"
8. Connect output of last concat to the output of the edited function

4. UI#

We have now defined the data that we will be managing within our application, as well as some helper functions to simplify the manipulation of those data. Similarly, there are some UI components that will be reused across all several screens, so designing them once and for all allows us to reuse them with minimal effort.

4.1 Header#

Our app has a header, which we see on every screen. In order to avoid creating it from scratch on each screen, we now create a reusable UI Component, which we will then be able to drag and drop every time we need it.

Header

1. Go back to Project and open UI folder
2. Create a new Visual Component, name it "Header" and open it
3. In the tree, click on the "Header" to select it
4. In Properties Panel, under Background Properties tab (3rd tab), set Background Color to black
5. Add a "Button" Visual Component and configure its properties it as follows:
a. 1st tab: Name = "Header button", Theme Class = "black"
b. 2nd tab: X = -6, Y = Middle (select Middle using the menu next to the properties), Width = 80
c. 3rd tab: Border Width = 2, Border Color = #8080806C
d. 4th tab: Text = "< Back"
6. Add a "Label" UI Component and configure its properties it as follows:
a. 1st tab: Name = "Header title", Theme = h3
b. 2nd tab: X = Center, Y = Middle
c. 4th tab: Horizontal Align = "Center"
7. Add a "Rectangle" and configure its properties as follows:
a. 2nd tab: X = Left, Y = Bottom, Width = 100%, Height = 6
b. 3rd tab: Background color = #455A64

Header

The text of our button and title will not be the same on all screens. Similarly, when we click on the header different things may happen depending on the screen. We therefore want to be able to customise our component a little bit each time we use it. This is done in four steps:

  1. Define a Context
  2. Set the value of the title
  3. Determine whether the Back button is visible or not
  4. Trigger an event from the Back button when we click on it

1. Define the Context of our Visual Component#

Each Visual Component (and screens as well by the way) can have a Context, i.e. a set of parameters and events that are available from outside the component. In our case, we want to configure the Header Button visibility and the Header Title text. Also, when the button is clicked, the component must notify its parent.

On the top of the Editor, click on "Context Editor" tab
1. Add the following Properties
- Hide Button (Boolean)
- Title (String)
2. Add following Event:
- On Back

Header Context

2. Set the text of the Title#

On the top of the Editor, click on "Visual Editor" tab
1. Select the "Header title" label
2. In properties panel, 4th tab, create a function for property Text using F(x) button and configure it as follows:
1. At the left of the screen, under UI Property Picker, drag "Header" and drop it to the Function body (empty rectangle in the middle of the screen)
- Select property "Title (String)" (that's the one created previously) and click on "Get Value"
- Connect "Get UI Property" value output to Function Text output
2. Close the function

Set the visibility of Header button#

1. Select the "Header button" label
2. In properties panel, 3rd tab, create a function for the property "Hidden" using F(x) button and configure it as follows:
- At the left of the screen, under UI Property Picker, drag "Header" and drop it to the Function body (empty rectangle in the middle of the screen)
- Select property "Hide Button (Boolean)" (that's the one created previously) and click on "Get Value"
- Connect "Get UI Property" value output to Function Text output
3. Close the function

Raise the event when the button is clicked#

In the properties panel, 5th tab, create an action for Interaction "On Click" using the F(x) button and configure it as follows:
1. Add "Dispatch Event"
- Connect Action Control Flow input to "Dispatch Event" Control Flow input
- Click on the "event" input and click on the Target icon
- Click on "Header" in the tree and select "On Back (UI Event) and "Done"
2. Close the action

5. App#

5.1 Expense App#

We have now built the plumbing for our application: we have a data model and helper functions to manipulate the data, and we have a reusable header component. Let's now create the Expense App and start plugging the different parts together.

Expense App

Go back to Project
Create a new UI App, name it "Expense App" and open it
OPTIONAL: Run the app on another tab or on a mobile device using the two little buttons at the top-right of the editor next to the marketplace

Run

5.2 Home Screen#

Let's start with the Home screen of our app. The home screen consists in

  • The header we built above
  • A button to create new expenses
  • A list of existing expenses with a button to open one and see its details.

Home Screen

Open the Home screen
1. Add the "Header" Visual Component you just created, a Button and a List
2. Select the Home screen in the tree
- 4th tab: Layout = Vertical, Spacing = 60
- Using the tree, reorder the elements to have the Header at the top
3. Configure the Header as follows:
- 1st tab: Name = "Header"
- 2nd tab: Height = 90, Width = 100% (using menu to switch to %)
- 4th tab: Title = "My Expenses", Hide Button = True
4. Configure the button as follows:
- 1st tab: Name = "New Expense Button"
- 2nd tab: Width = 200
- 4th tab: Text = "Create an expense"
5. Configure the list as follow:
- 1st tab: Name = "Expense List"
- 2nd tab: Width = 90%, Height = 200 (or if you feel confident, you can even define a function to make it grow automatically depending on the size of the screen!)
- 4th tab: Row Height = 70

Configuring the list of expenses#

We now want to display the list of expenses. This is done in two steps:

  1. Get the list of expenses which we want to display
  2. Configure each line of the list to display the expense as we want it
1. Select the list and configure it:
- 4th tab: Data = Create a function which returns all Expenses using the "Get Object List" function

Home Screen

And now we can display an expense in the list:

1. On the list, click on "Edit" button. This will define content to be displayed on each lines (Expense details)
2. Add a new Label
- 1st tab: Name = "Summary"
- 2nd tab: X = Left, Y = Middle
- 4th tab: Text: Create a function which returns the summary of the expense.
3. Add a Button
- 1st tab: Name = "View button"
- 2nd tab: X = Right, Y = Middle, Width = 100
- 4th tab: Text = "View"
4. Close the list item renderer

Amount_in_list

You can find here an example on how to retrieve the current value of a list item renderer.

We will configure the "View" button a bit later in the tutorial. We need a few expenses to test that the list is properly configured. Before being able to create them from the application, we can create one or two expenses using the same Data Set that we used to create the currencies.

5.3 New Expense Screen#

Now that we are done with the Home screen, let's look at the screen which we open when clicking on "Create an expense" button in the Home screen.

This is the New Expense screen. It consists in:

  • A header
  • A text field to set a description
  • A text field to set the amount
  • A dropdown to set the currency
  • A button to confirm and create the expense.

New_Expense_Screen

Let's first create the screen and make it reachable from our Home screen:

1. Go back to Expense App (Screen Flow Editor)
2. Add a new Screen and name it "New Expense"
3. Create a transition between the home screen and you new screen
4. Click on the dot in the middle of the transition to edit it
5. Next to Event, click on the + button (this display the home screen)
6. Click on "New Expense" button, select "On Click (Action)" and click on Done

If you have the app running you should be able to click on the button to go to your new screen. We can now add the different UI elements:

Open the new screen
1. In the 4th tab, set Layout = Vertical, Spacing = 10
2. Add a "Header" UI Component and configure it as follow:
- 2nd tab: Height = 90, Width = 100%
- 4th tab: Title = "New Expense"
3. Add three Labels, two TextFields and one DropDown
- Use the tree on the left to reorder the components to build a proper form
4. In the tree, click on the little pencil icon to rename:
- The labels as "Description label", "Amount label" and "Currency label"
- The text fields as "Description", "Amount"
- The drop down as "Currency"
5. Set the label Text to "Description", "Amount" and "Currency" (4th tab)
6. Select the Amount text field and configure it as follow:
- 4th tab: Type = Number
7. Select the DropDown and configure it as follow:
- 4th tab: Data = Create a new function
- Add "Get Object List" with model input set to "Currency" and object list output linked to function Data output
- 4th tab: Selected Value = Create a new function
- Add "Get Object List" with model input set to "Currency" and connect it to "Get First Object In List" and connect the latter to "Select Value Function" output
- 4th tab: Renderer = Create a new function
- Add "Get Object Property" whose input is connect to function Object input, property input is set to Currency.name, and output is connected to function Value output
8. Add another Label with no text
- It acts as a spacer
9. Add a Button:
- 1st tab: Name = "Create Button"
- 2nd tab: Width = 300
- 4th tab: Text = "Create"
10. Use the tree to put the label and button at the bottom
11. Select the screen in the tree:
- 4th tab: Enable Vertical Scrolling

The final part is to actually create the expense once we click on the button. However, we actually need to do a bit more than that; clicking on the button has to:

  • Create the expense
  • Move to the next screen that will allow us to take a picture of our receipt
  • Make sure that the next screen has the expense that we are just creating, so that it can attach the receipt to it
1. Click on tab "Context Editor"
2. Add a new "Event" and name it "On Create"
3. Add a new "Property", name it "New Expense" and set type to "Expense"
4. Click on tab "Visual Editor"
5. Select the "Create Button"
- 5th tab: Add "On Click" action and configure it as follow
- Add "Create Expense" brick and connect the Control Flow input.
- Under UI Property Picker, drag'n'drop Amount and select property "Text (String) and click on "Get Value"
- Under UI Property Picker, drag'n'drop Description and select property "Text (String) and click on "Get Value"
- Under UI Property Picker, drag'n'drop Currency and select property "Selected Value (Object) and click on "Get Value"
- Connect the Get UI Property bricks value outputs to the appropriate inputs of the Create Expense brick.
- Under UI Property Picker, drag'n'drop "New Expense" and select property "New Expense" and click on "Set Value". Connect Control Flow between "Create Expense" and "Set UI Property"
- Add "Dispatch Event" brick.
- Connect its Control Flow after "Set UI Property".
- Click on event input, then on the target icon. This displays the screen.
- Click on New Expense Screen (in the tree) and select "On Create (Action). Click on Done.

5.4 Expense Picture Screen#

So far, we have created a Home screen, as well as a New Expense screen that allows creating a new expense. What we now want to do is to take a picture of the receipt, and attach it to our expense. We do this in a new screen, which is displayed when we click on the "Create" button in the New Expense screen. Our Expense Picture screen therefore consists of:

  • A header
  • A video which displays the camera
  • A button to take the picture of the receipt. When the picture is taken, we go back to the Home screen.

Expense_Picture_Screen

Let's start by creating our new screen, and connecting it to the New Expense screen. We also need to make sure that the expense created in the New Expense screen is transferred to the Expense Picture screen so that we can link the two together.

1. Go back to Expense App (Screen Flow Editor)
2. Add a new Screen, name it "Expense Picture" and open it
3. Click on tab "Context Editor"
4. Add a "Property", name it "Expense" and set type to Expense
5. Add an "Event" and name it "On Picture Taken"
6. Go back to Expense App (Screen Flow Editor)
7. Create a transition between the New Expense screen and Expense Picture screen
8. Click on the dot in the middle of the transition to edit it
9. Under Event, click on "None" and select "On Create"
10. Click on Property Mapping and connect "New Expense" and "Expense"

We can now build the UI of the screen.

1. Add a "Header":
- 2nd tab: X = 0, Y = 0, Height = 90, Width = 100%
- 4th tab: Title = "Expense Picture", Hide Button = true
2. Add a "Button":
- 1st tab: Name = "Take Picture Button"
- 2nd tab: X = Center, Y = Bottom
- 4th tab: Text = "Take Picture"
3. Add a "VideoStream Player":
- 1st tab: Name = "Camera Preview"
- 2nd tab: X = Center, Y = 90, Width = 100%, Height = Function to completely fill the space between the header and the Take Picture Button
- 4th tab: Source = Function that uses "Get Back Camera Stream"
4. Click on Take Picture Button, go to 5th tab and add Action for On Click Interaction
- Under UI Property Picker, drag'n'drop "Camera Preview" Source property and click on Get Value
- Under UI Property Picker, drag'n'drop "Expense Picture" Expense property and click on Get Value
- Add "Take a Picture" and connect it to Control Flow. Link "Get UI Property" value (Camera Preview.Source) to "Take a Picture" stream
- Add "Set Expense's picture" and connect it to Control Flow. Connect "Take a Picture" value to "Set Expense's picture" picture and "Get UI Property" (Expense Picture.Expense) value to "Set Expense's picture" Object (Expense)
- Add "Dispatch Event" and set Event to Expense Picture's "On Picture Taken"

Finally, since we want to go back to the Home screen we need to add a transition in the app's screen flow editor.

1. Go back to Expense App (Screen Flow Editor)
2. Create a transition between Expense Picture screen and Home Screen and select event "On Picture Taken"

5.5 Expense Details Screen#

So we have covered most of our application: we can create new expenses, attach receipts to them, and view the list of expenses created. The final step is to be able to view the details of an expense when we click on it.

We can therefore now go back to the Home Screen and configure the "View" button to trigger an event when clicked, and record which expense is being viewed.

In the Context Editor of the Home Screen:
1. Add an "Event" and name it "On View Expense"
2. Add a "Property", name it "Selected Expense" and set its type to "Expense"
3. Go to "Visual Editor" tab and open the list item renderer (by clicking on Edit on the list)
4. Select the button and on the 5th tab configure its "On Click" action:
- Under UI Property Picker, drag'n'drop Item Renderer, select "Current Value (Object)" property and click on "Get Value"
- Under UI Property Picker, drag'n'drop Home Screen, select "Selected Expense (Expense)" property and click on "Set Value"
- Connect "Get UI Property" value output to "Set UI Property" value input
- Connect Action Control flow input to "Set UI Property" Control Flow input
- Add "Dispatch Event" and set Event to Home screen's "On View Expense"
- Close the action

We now build a new screen to view the details of an expense, the Expense Details screen. This screen is displayed when clicking on one of the "View" buttons in Home screen. It contains:

  • A header
  • A label to display the description
  • A label to display the amount
  • A label to display the currency
  • A picture to display the receipt picture.

View Expense Screen

Like we did between the New Expense screen and the Expense Picture screen, we need to provide the Expense Details screen with the expense that we clicked on in the Home screen.

1. Add a new Screen, name it Expense Details and open it
- Click on tab "Context Editor"
- Add a "Property", name it "Expense" and set its type to Expense
2. Go back to Expense App (Screen Flow Editor)
- Create a transition between Home Screen and Expense Details Screen
- Set the event to "On View Expense" and map the property "Selected Expense" to "Expense"

Let's now build the UI.

1. Open Expense Details Screen
2. Add a "Header" UI Component and configure it as follow:
- 2nd tab: X = Left, Y = Top, Height = 90, Width = 100%
- 4th tab: Title = A function that retrieves the expense's Description from the screen's Expense property
3. Add a "Label" UI Component and configure it as follow
- 2nd tab: X = Center, Y = 120
- 4th tab: Horizontal Align = Center, Text = Function which displays the summary of the expense (using "Format Expense Summary")
4. Add an "Image" UI Component and configure it as follow
- 2nd tab: X = Center, Y = 180, Width = 90%, Height = 400
- Background Image = Function which calls "Get Expense's attributes" to retrieve the "Picture" property

And finally we allow the user to go back to the Home screen.

1. Go back to Expense App (Screen Flow Editor)
2. Create a transition between Expense Details Screen and Home Screen. Create a new event (+ Button), click on Header and select "On Back (Action)"