Tutorial : Introduction to MVA

Page Status: Beta

Jump to: Neue Coins 2023, navigation, search

Goal: Introduce you to Bungee Connect's Model-View-Adapter architectural pattern, by using adapters to expose an application's underlying object model.

Result: After creating a simple task list application, you'll gain an initial understanding of how to use one of Bungee Connect's most powerful features, the MVA architectural pattern.

This tutorial is the second of three tutorials that comprise the "Bungee Essentials" tutorial series.

[edit] Objectives

By completing this tutorial, you will:

Understand how to create complex data models
Gain an initial understanding about how the data model of your applications relates to the presentation of the end user interface
Learn how to use the basic interface for programming with Bungee Logic

[edit] Prerequisites

Before starting this tutorial, we recommend you complete the following:

Tutorial: Hello Bungee Connect (10:00)
- Shows how to create and deploy an application with Bungee Connect
Print the Bungee Builder Layout image to use as quick reference while doing the tutorial.
If you get stuck at any point in the tutorial, post a question in the Bungee Connect Developer Network (BCDN) Forums thread for this tutorial.

[edit] Overview

Bungee Connect uses an architectural pattern called Model-View-Adapter (MVA) that is different from the traditional Model-View-Controller (MVC) pattern used by many other programming languages and development environments. MVA is particularly well-suited for creating on-demand applications that run in a web browser. Understanding this concept will enable you to create extremely powerful web applications with Bungee Connect. This tutorial starts you on the path to a rich understanding of how to exploit the full potential of the MVA architectural pattern.

The tutorial comprises two parts:

In Part 1, you design the foundation for a simple task list application. You first design a class for creating individual task objects, including Model elements (fields) and View elements (forms). You then create a collection of tasks for your task list.
In Part 2, you create the main user interface for your application, a simple task list interface that taps into the data model of your application. You also create a simple function, and get your first exposure to Bungee Logic.

The simple application you build in this tutorial is shown at right. You can click the screenshot, or this link to try out the application

[edit] Part 1: Create the Task List Data Model

Estimated Time to Complete: ~13 minutes

The MVA architectural pattern is model-driven. State changes within an application's data (Model) drive updates to the user interface (View). This means that you typically design the data model for your applications before you build your various forms, allowing you to continue refining an application’s user interface independent of the program logic. For seasoned developers who are accustomed to MVC, this may at first feel like working backwards. You can still create applications by starting with the user interface ("view first"), but the advantages of starting with the model ("model first") quickly start to emerge. As you become familiar with developing in a model-driven paradigm, you will discover how this approach enables you to quickly change user interfaces and extend the functionality of your applications without large-scale code overhauls.

In this section, you start by creating the fundamental object type, or class, for the task list applicaton: the task. To keep things simple, the task class has three fields: a description of the task, a due date, and a status for whether or not the task is completed. You also create two forms for this class, one for adding or editing a task, and another to provide a read-only view of a task. Next you create a second class (clsTaskList) with a collection for storing the list of tasks.

[edit] Create the Solution and Project

Create a new solution and a TypeLib project
1. In the Solution toolbar, click the New Solution icon (first one on the left)
2. In Solution Name, type MVA_Intro_Tutorial
3. Under Choose the Projects you would like to include in you new Solution, select only TypeLib Project (that is, clear the checkbox for AppProject)
4. Click Next
5. Under Name, change MyTypeLib to Task_List
6. Click Done
Save your solution (in the Solution toolbar, click the Save All icon—first one on the right)

[edit] Add a Class for Task Objects

The fundamental component of your Task List application is the individual task object. You will use a class to define the data structure for task objects, and add fields of appropriate data types for the description, date, and completion status.

Add a class to Task_List
1. Select Task_List, then right-click and select Add Class
2. Name: clsTask
3. Note In Bungee Connect tutorials, we often use cls as a prefix to class names. This convention is intended to help newcomvers differentiate between the various objects in the Solution Explorer while following the written tutorial. Normally, the recommended naming convention for classes is to capitallize the first letter of the class name as well as any conjoined words. For example, a class that defines duck objects might be called Duck or MallardDuck.
Add three fields to clsTask
1. Expand the Task_List typelib, select clsTask, then right-click and select Add Field for each field below
2. string description (to hold the description of the task)
  1. Name: description
  2. Type: string (default)
3. dateTime dueDate (to hold the task's due date)
  1. Name: dueDate
  2. Type: dateTime (under the Type property, click the ellipsis button, click the Dependencies tab, and under TypeLib : Types, select Class: dateTime (not DateTimeObject))
4. boolean complete (to be linked to a checkbox showing whether completed when a task object appears on a form)
  1. Name: complete
  2. Type: boolean (select Class: boolean under TypeLib: Types)
Save your solution

[edit] Adding Forms and Form Adapters

In Bungee Connect, forms are members of a class, and allow you to provide different views for the data type that the class defines. For example, in the application you are currently building, you need to provide an editable interface for Task objects (objects based on clsTask), as well as a read-only interface for displaying Task objects. Both of these interfaces can be created as forms within the clsTask class.

Once created, these forms can be used over and over again throughout your application. Whenever you wish to display a field or an element in a collection, you can simply use one of the forms that you have already designed.

In order to assign which form (edit or read-only) to use for displaying an instance of clsTask, you use a form adapter in conjunction with a specialized control, such as the DynamicForm control or the FormList control. In this section and the next, you design two forms that you use in a later section of the tutorial.

[edit] Add a Form for Editing Task Objects

First you will add a form and form adapter for editing Task objects.

Add a form to clsTask
1. Select clsTask, then right-click and select Add Form
  1. Name: editForm
  2. Select Choose a Form Adapter
    1. Form Adapter Name: Edit (on the Runtime tab)
    2. Click OK
2. Select clsTask, then in the Solution Detail, double-click editForm to open it in the Design Editor
3. Change the form to have one row and three columns
  1. Click the dark grey area outside the form to select the entire form
  2. On the vertical ruler, click one of the green row edit buttons and select Remove Row
  3. On the horizontal ruler, click the green column edit button on the left and select Insert Before
  4. Click anywhere in the dark gray background to close the menu
4. Add controls to the form.
  1. Add a Checkbox for completion status
    1. In the Solution Detail, select boolean complete
    2. From the Toolbox, drag Checkbox to the left-most cell
    3. In the Property Editor select and delete the text (complete) in the Label property (General tab)
    4. Click anywhere in the dark gray background to select the top-level container
    5. On the horizontal ruler, drag the column sizing tool (the small gray triangle) to make the column 19 px wide
  2. Add a TextEdit for the task description
    1. In the Solution Detail, select string description
    2. From the Toolbox, drag the TextEdit control to the center cell of the form
    3. Click the gray area outside the form to select the top-level container.
    4. Resize the middle column to 280 px wide (on the horizontal ruler, drag the column sizing tool—the small gray triangle—to make the center column 280 px wide)
  3. Add a calendar edit control for the due date
    1. In the Solution Detail, select dateTime dueDate
    2. From the Toolbox, drag MonthCalendar to the right-most cell of the form
    3. Resize the right-most column to 120 px wide.
Your completed form will look like this in the Design Editor
Save your solution
(Optional) Simulate your form to test its functionality (use the Run button in the Toolbar).

[edit] Add a Form for Viewing Task Objects

For the task list application, you need a form to display each task object as a list. This form is similar to the edit form that you have already created, but does not have editable controls. Therefore, design the form to have a Label control for the description and due date, and a checkbox for the completion status.

Add a form to clsTask
1. Name: displayForm
2. Select Choose a Form Adapter
  1. Form Adapter Name: ReadOnly (on the Runtime tab)
  2. Click OK
Double-click displayForm to open it in the Design Editor
1. Change the form to have one row and three columns
  1. Make the leftmost column 19 px wide, and disable Stretchable
  2. Make the middle column 280 px wide
  3. Make the rightmost column 120 px wide
2. Add controls to the form
  1. Add a Checkbox control for completion status
    1. In the Solution Detail, select boolean complete
    2. From the Toolbox, drag Checkbox to the leftmost cell
      1. In the Property Editor select and delete the text (complete) in the Label property (General tab)
  2. Add a Label control for the task description
    1. In the Solution Detail, select string description
    2. From the Toolbox, drag Label to the center cell
  3. Add a Label control for the due date
    1. In the Solution Detail, select dateTime dueDate
    2. From the Toolbox, in the Selection category drag Label to the rightmost cell
    3. In the Property Editor, on the DateTime Format property, click the ellipsis button [...].
    4. In the DateTime Format dialog, select the fourth option in the list (<N> <D>, <Y>)
    5. Click OK
Your completed form will look like this in the Design Editor
Save your solution

[edit] Add a Main Class

Now that you have designed the basic data type for your task list application, you need a main class to bring the application together, including a collection of task objects and a primary interface. The primary interface will be a form that has three areas: an area used to enter new tasks, a small area for a button to perform the addition of a new task, and an area for the actual task list. You will also add a text label to help end users understand the form.

Add a class to Task_List
1. Name: clsMain
Add a field to the clsMain class
1. Name: taskList
2. Type: clsTask (on the MVA_Intro_Type tab of the chooser)
3. Select the Collection property
Save your solution

[edit] Summary of Part 1

At this point, you have created a basic data model consisting of a Task class, and a Main class that includes a collection of Task objects. You also created two forms in the Task class, one for editing task objects, and one for viewing them. In Part 2, you put these two forms to work as you explore how to expose this data model in an application view.

[edit] Part 2: Apply MVA Concepts to Create the Task List Application Interface

Estimated Time to Complete: ~12 minutes

Now you will use the two forms as re-usable interface components to construct your application. To do this, you create the main interface form for the application and then add controls to the form. Two of these controls will leverage the forms that you created in Part 1 by employing Adapters, which provides you with your first opportunity to put the Model-View-Adapter architectural pattern to work.

At the end of the procedure, you create a basic function, which provides a first look at how to construct programming instructions in Bungee Logic.

[edit] Build the Main User Interface

Add a form to clsMain
1. Name: frmMain (by default, the form is named Default, and the Default form adapter is selected—just click OK)
2. Double-click the form to open it in the Design Editor
  1. Adjust the left column of the form to 435 px wide (by clicking the green arrow at the top of the column and selecting the Edit Column... menu item)
  2. Adjust the right column to 100 px wide
  3. Insert a row at the top of the form
  4. Adjust the middle row to 30 px high
  5. Adjust the bottom row to 200 px high
  6. Merge the cells in the bottom row. (Mouse over the column divider line in the bottom row, then click the [-] symbol that appears in the divider.)
  7. In the Toolbox, expand Text and drag the Label control to the first column in the top row of the form
    1. Contract the Text area of the Toolbox (so you don't drag other controls from this area by accident)
    2. In the Property Editor, change the Text property from Label to Enter a new task:
  8. Click the gray background to select the form's topmost container
  9. In either ruler, click on one of the green column dividers, and select Edit Margins... from the popup menu
    1. Set the column margins as follows:
      1. Outer margins: 6
      2. Inner Row Margins: 3
      3. Inner Column Margins: 3
frmMain should now look like this:

[edit] Add a DynamicForm to Display the editForm

The first place to put one of the form adapters to work, is in the user interface for adding new tasks to the task list. To do this, you add a new field based on clsTask to act as temporary storage for new tasks. Then, you bind a DynamicForm to the new task field and assign the appropriate form adapter so that the DynamicForm uses editForm.

Add a field to clsMain
1. Name: newTask
2. Type clsTask
3. Tip: Because you previously used clsTask during this session with Bungee Connect, you can select it from Recent Selections in the Chooser
In the Solution Detail, select clsTask newTask
In the Toolbox, drag DynamicForm to the left cell, middle row of the frmMain form (this control is automatically bound to clsTask newTask because the field is selected)
At the top of the Property Editor, click the Adapter tab
1. In the left column, under the Forms section, select the Form property, then in the right column, next to Form Adapter, click the ellipsis button and select Edit (on the Runtime tab)
2. Click OK

Your frmMain form (on your clsMain class) should now display an instance of the clsTask class's editForm embedded within the second row. This is possible because clsMain has a field (newTask) of type clsTask, and editForm is a member of the clsTask.

As you develop further skill with Bungee Connect, you will learn how to make a DynamicForm control automatically select different forms based on different object types. This allows you to make powerful polymorphic user interfaces very quickly.

[edit] Add a FormList Control for Displaying the List of Tasks

To provide an end user view of the task list collection based on the displayForm that you created in Part 1, you can use a FormList control. The FormList control is similar to DynamicForm, but displays whole collections by using individual forms for each element in the collection.

You must assign the correct form adapter to the FormList control so the FormList can find the proper form to use for displaying each element in the collection. In the steps below, you assign the ReadOnly form adapter to the FormList control. This helps the FormList to locate the displayForm in the clsTask, so that the FormList can display each clsTask object in the taskList collection.

With clsMain selected in the Solution Explorer, in the Solution Detail, select Collection(clsTask) taskList
From the Toolbox, drag FormList to the bottom row of the form
1. In the Properties pane, click the the Adapter tab
2. In the left column, select the Element Form property, then in the right column, next to Form Adapter click the ellipsis button [...] and on the Runtime tab, select ReadOnly
3. Click OK
Save your solution

Unlike the DynamicForm control, FormList controls do not display their element forms at design time, because the Collection has no data until added by an end user. Your frmMain form should now look like this:

[edit] Add a Function (addTask)

The final step in your task list application is to create a function that adds new task entries to the collection of tasks. This requires you to create program logic, providing your first exposure to Bungee Logic. Bungee Logic is a C-family language designed specifically for the MVA-based environment of Bungee Connect.

The job of adding a task to the list requires you to move data entered in the user input form into the task list. The input task is stored in the newTask field, so you must add that data to the taskList collection, and then clear the newTask field to ready it for additional input. Once you have created the functional logic, you bind it to a button and place it on the form. Then you can simulate the application to see how it works.

Add a function (right-click clsMain and select Add Function)
1. Name: addTask
Double-click the function to open it in Design Editor
1. From the Toolbox, drag call function () and drop it on the line between the { }
  1. In the Property Editor, configure the following:
    1. Function Path: Path
    2. Click the ellipsis button [...] to set the path, then expand Collection(clsTask): taskList and select Function: add
      
      Note The add function is part of the collection type, providing a mechanism for adding new items to a collection.
    3. In the Parameters, click the ellipsis button for the [in] parameter's Path, and then select clsTask newTask and click OK (this parameter adds the current value of the newTask field to the taskList collection). Next you must clear the newTask field.
  2. Drag assignment from the Toolbox to the line below the previous call function( ) statement
    1. In the Property Editor, configure the assignment statement as follows:
      1. To: (left side)
        
        Type: Path
        
        Select clsTask newTask
      2. From: (right side)
        
        Type: Object (which declares a new instance of the newTask object, effectively clearing it to accept input for another task)
In the Solution Detail, double-click frmMain to open it in the Design Editor (or simply click the existing tab for frmMain in the Design Editor)
1. In the Solution Detail, select addTask
2. From the Toolbox, drag StyleButton to the right-most cell in the middle row
  1. Change the Text property's Data to Add (General tab)
  2. On the Property Editor's Behavior tab select Default in order to make this button the default action for the Enter key
Save your solution

Notice how the function is separate from the form. The actual logic that you use here is entirely contained in the application's data model (Model) rather than in the user interface (View). This separation is typical of Bungee Connect's Model-View-Adapter pattern, in which user interfaces update automatically according to changes in the underlying application data.

Click for larger image

[edit] Simulate the Main Form

With frmMain still open in the Design Editor, click the Run button in the Toolbar
Test the functionality of the application by adding a few tasks. Note how the FormList re-uses the displayForm for each task

[edit] Summary

In this tutorial you have:

Built a model for your data that involves more than one level of inheritance, and includes forms as part of the model
Applied adapters in order to expose your application's data model in the presentation of the end user interface
Used Bungee Logic to develop a simple function for manipulating program data in the model

[edit] What Next?

We recommend doing the following next steps to continue your learning of Bungee Connect:

Continue on to Tutorial 3 of 3: Integrating Web APIs.

[edit] Further Reference

The following resources will further increase your understanding of the concepts covered in this tutorial:

The documentation article for the DynamicForm control provides very thorough information to help you understand the relationship between adapters and the view of your data model.

Did we leave something out of this Bungee Connect Core Curriculum Tutorial? Get answers to questions, or make suggestions in the BCDN Forums thread for this tutorial.

Retrieved from "http://docs.bungeeconnect.com/wiki/index.php/Tutorial_:_Introduction_to_MVA"

Category: Bungee Essentials