GettingStarted

Difference between revisions of "Web Tutorial"

From Xojo Documentation

(Created page with "= Learn the Basics: Xojo Web Tutorial = This Web Tutorial is for people who are new to programming and new to Xojo. It is an introduction to the Xojo development environment...")
 
 
(113 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= Learn the Basics: Xojo Web Tutorial =
+
= Learn the Basics =
  
This Web Tutorial is for people who are new to programming and new to Xojo. It is an introduction to the Xojo development environment and will lead you through the development of a real web app. It should take you about an hour to complete this tutorial.
+
Xojo is a cross-platform integrated development environment (IDE) that is made up of a rich set of graphical user interface objects, the modern object-oriented Xojo programming language, an integrated debugger, and a multi-platform compiler. With the IDE, you can build your app's interface simply by dragging and dropping interface objects onto the app's web pages and dialogs.
  
If you are already familiar with Xojo and would like a shorter introduction to making web apps with Xojo, jump to the [http://www.xojo.com/docs/quickstart/web/ Web QuickStart].
+
Once you have completed the [http://www.xojo.com/docs/quickstart/web/ Web Quickstart], this tutorial will walk you through creating a more intermediate web app, a Task Manager. This is what the completed app will look like:
 +
[[File:Finished Web Tutorial App.png|none|457x457px]] 
  
 +
= Task Manager Tutorial =
  
 
== Getting Started ==
 
== Getting Started ==
If you haven’t done so already, now is the time to launch Xojo. After it finishes loading, the Project Chooser window appears.
+
# Launch Xojo. After it loads, the Project Chooser window appears.
 +
# Choose Web, since we're building a web app, and press OK. A new Xojo project window will appear.
  
[[File:Xojo Project Chooser Web.png]]
+
[[File:Xojo Project Chooser Web.png|700px]]
 +
== The Xojo Project Window ==
 +
This window has three basic parts:
  
Xojo lets you build several different types of apps (Desktop, Web, Console and iOS). For this Tutorial, you are building a web app, so click on Web.
+
[[File:Web Layout Editor.png|700px]]
  
You will now see three fields that need values: Application Name, Company Name and Application Identifier.
+
'''Navigator''': The area on the top left shows you all the items in your project. By default you can see WebPage1 (which is selected), the App object and the Session object. Use the Navigator to navigate within your project.
  
* '''Application Name''' is the name of your app. This will be the filename of the actual app file that gets created.
+
'''Editor''': The center area is the Editor Area. Currently it's showing the Layout Editor. You use the Layout Editor to design the user interface for the web pages in your app. It shows the web page and previews how it looks when the app runs in a web browser. In this image, the web page is blank because you haven't yet added any user controls. The Editor Area however can also show other kinds of editors for editing code, icons and other things you might use in a project.
* '''Company Name''' is the name of your company. You may choose to leave this blank.
 
* '''Application Identifier''' is a unique identifier for this app. It will automatically populate using what you enter for the Application and Company Names, but you can also change it to whatever you want.
 
  
# Enter TaskManager as the Application Name. You can leave Company Name as it is or change it.
+
'''Library''': The area on the right is the Library and shows the controls and interface elements that you can add to a web page. You design the web page by dragging controls from the Library to it. You can also add a control to the web page by double-clicking it.
# Click OK. The main Xojo window (called the Workspace) opens. This is where you will begin designing your app.
 
  
 +
{{Information|If your Library looks different than mine, that's because I like mine showing icons only. You can customize yours by clicking on the small gear icon near the top-left corner of the Library and then choosing a different setting.}}
  
== Workspace ==
+
If the Library is not visible, click the Library button on the toolbar to show it.
Xojo opens the Workspace with the default web page for your app selected in the Navigator and displayed in the Layout Editor.
 
  
[[File:Web Layout Editor.png]]
+
'''Inspector''': Not shown in the above image is the Inspector, which allows you to see and change the various attributes (the height, width, name and more) of any control you've added to your webpage. This area of the window is shared with the Library. You can show the Inspector by clicking the Inspector button on the toolbar. The Inspector shows information about the selected item in the Navigator or Editor. The contents of the Inspector changes as you click on different items.
  
'''Navigator''': The area on the top left shows you all the items in your project. By default you can see WebPage1 (which is selected), the App object and the Session object. Use the Navigator to navigate within your project.
+
== About the App You Are About to Create ==
 +
In this tutorial you will create an app to track tasks, called "Task Manager." When finished, the Task Manager app will let you enter tasks in a field then click the Add button to add them to the Task list. You can click on individual tasks in the list to delete them or mark them as complete.
 +
 
 +
[[File: Finished Web Tutorial App.png|700px]]
 +
 
 +
==Designing the User Interface==
 +
===Creating The Task List===
  
'''Layout Editor''': The center area is the Layout Editor. You use the Layout Editor to design the user interface for the web pages in your app. It shows the web page and previews how it looks when the app runs in a web browser. In this image, the web page is blank because you haven't yet added any user interface controls from the Library.
+
WebPage1 is open in the Layout Editor. First, you need to add a TaskList (ListBox) to the web page.
  
'''Library''': The area on the right is the Library and shows the controls and interface elements that you can add to a web page or to the project. You design the web page by dragging controls from the Library to the web page. You can also add a control to the web page by double-clicking it. You can change how the controls display in the Library by clicking the small gear icon and choosing a different setting.
+
# In the Library, click on the ListBox and drag it to the top-left corner of the Layout Editor. As you get close to the edges of the web page, you will see alignment guides that help you position the control to leave the right amount of space between the edge of the browser window and the control.
 +
#:[[File:ListBox Library Icon.png|30px]]
 +
#:[[File:Web Tutorial Listbox Alignment Guides.png|300px]]
 +
# When the alignment guides appear, drop the ListBox.
 +
# Click on the Listbox to select it and then use the handles to resize it. Leave about 1/4th of the webpage blank for the other controls you're about to add. Your project should now look like this:
 +
#:[[File:Web Tutorial Resized ListBox.png|300px]]
  
If the Library is not visible, click the Library button on the toolbar to show it.
+
===Adding the Buttons and TextField===
 +
Now add the Delete and Add buttons.
  
'''Inspector''': Not shown in the above image is the Inspector, which allows you to see and change the properties for the selected control. This area of the Workspace window is shared with the Library. You can show the Inspector by clicking the Inspector button on the toolbar. The Inspector shows information about the selected item in the Navigator or Editor. The contents of the Inspector changes as you click on different items.
+
# In the Library, click on the Button control [[File:Button control icon.png|30px]] and drag it to the lower-left corner of the web page.
 +
# Now drag a Default Button control [[File: Default Button control icon.png|30px]] to the lower-right corner of the web page. This button is labeled, "OK" by default but we will change it to "Add" later.
 +
# Last but not least, drag a TextField control [[File:TextField control icon.png|30px]] from the Library and drop it next to the Delete button.
 +
# Resize the Textfield so that its right side is aligned with the left side of the OK button.
  
== About the App ==
 
In this tutorial you will create an app to track tasks.
 
[[File: Finished Web Tutorial App.png]]
 
  
=== Task Manager ===
+
After adding all the controls, your web page in the Layout Editor should look like this:
  
For the Task manager app, you enter tasks in the text field and then click the Add button to add them to the list. You can click on individual tasks in the list to delete them or mark them as complete.
+
[[File:Web Tutorial Layout.png|700px]]
  
Task Manager uses three controls:
+
{{Information|If on your computer the browser frame of the web page looks different from what you see in this tutorial, that's because Xojo draws a frame that is similar to the default browser of the OS upon which you are running Xojo.}}
  
* TextField: A TextField control is used to enter text. In this project, the task to add is entered into a TextField at the bottom of the window.
+
==Customizing Controls with Properties==
* Button: A Button is used to trigger an action. This project uses several buttons to perform different actions.
+
Controls have various values associated with them such as their caption, height, and width. Because they help describe the control, they are called Properties. Changing property values allows you to change the look and behavior of the control.  
* ListBox: A ListBox is used to display a list of data. In this project, it is what displays the tasks entered in the TextField.
 
The next sections walk you through creating the user interface and adding the necessary code to make the app work.
 
  
==Designing the User Interface==
+
===Inspector===
===Task List===
+
The Inspector is used to change web page and control properties. It shares the same area as the Library on the right side of the window.
  
You should have WebPage1 open in the Layout Editor. You are now going to add a Listbox to the web page. The Listbox is used for storing the tasks.
+
{{Information|The instructions in this tutorial enclose values you will type in quotation marks. When you enter values in the Inspector, don't type the quotation marks. }}
  
#. In the Library, click on the Listbox and drag it to the top-left corner of the Layout Editor. As you get close to the edges of the web page, you will see alignment indicators that help you position the control.
+
===Web Page Properties===
#. Drop the Listbox when you are happy with its position on the web page.
+
You need to change the Name and Title properties of the web page:
#. Click on the Listbox so that the resizing handles appear.
 
#. Grab the handle in the bottom-right corner and drag it to enlarge the Listbox to fill the top 2/3 of the web page.
 
  
===Buttons===
+
# Click the Inspector button [[File:Inspector Toolbar Button.png|30px]] on the toolbar.
 +
# In the Layout Editor, click anywhere on the web page where there is no control to select the page itself. The Inspector pane now shows the properties for the web page.
 +
# In the Name field (located in the ID group), change the name from “WebPage1” to “TaskManagerPage”. Press Return to see the name change in the Navigator.
 +
# In the Title field (located in the Frame group), change the name from “Untitled” to “Task Manager”. Press Return to see the name change in the title bar of the web page.
  
Now you will add the three buttons needed by Task Manager to the web page.
+
{{Information|The labels the user sees such as the title of a page or the caption of a button, can have spaces. The names of controls, however, are used to refer to them in code and cannot have spaces in their names. If you add a space, Xojo will get confused because controls prefer to have single names like [https://en.wikipedia.org/wiki/Madonna Madonna], [https://en.wikipedia.org/wiki/Sting_(musician) Sting] and [https://en.wikipedia.org/wiki/Prince_(musician) Prince].}}
  
The '''Delete''' button removes tasks from the Listbox, the '''Add''' button adds tasks to the Listbox and the '''Complete''' button marks tasks in the Listbox as completed. Let's add those three buttons to WebPage1:
+
===ListBox Properties===
 +
So the ListBox can properly display Tasks, we need to customize the properties.  
  
#. In the Library, click on the Button control and drag it to the web page below the lower-right corner of the Listbox. Use the alignment indicators to help you position the button so that it lines up with the right edge of the Listbox.
+
# In the Layout Editor, click on the ListBox to select it. The Inspector pane now shows the properties for ListBox.
#. In the Library, click on the Button control and drag it to the web page near the bottom-left corner. Again, take advantage of the alignment indicators to help you position the button.
+
# In the Name field (located in the ID group), change the name from “ ListBox 1” to “TaskList”.
#. In the Library, click on the Button control and drag it to the web page near the bottom-right corner.
+
# The ListBox has two columns, one to show the completed status and another to show the name of the task. In the ColumnCount field, change the value from “1” to “2” and press Return. The ListBox will not show two columns in the Layout Editor but it will when you run your app.
 +
# In the Inspector, turn on the Has Header button.
 +
# You want to change the column headers to "Completed" and "Task". In the Inspector, click the pencil button to the right of the Initial Value property. This will bring up the Initial Value Editor.
 +
# In the Initial Value editor type "Completed", press the Tab key and then type "Task." Click the OK button when you're finished editing.
 +
# Since the Completed column is only going to contain a simple checkmark when the task is marked as completed, it can be narrow. In the ColumnWidths field, enter “30,*” and press Return. Using “30,*” tells the ListBox that the first column should always be 30 pixels wide and that the rest of the columns share the remaining width.
 +
# Lock the edges of the ListBox to the edges of the webpage so the ListBox gets larger or smaller as the web page size changes. Click the locks so that top, left, bottom and right are all locked.<br>[[File:Web Tutorial ListBox Locking Properties.png|100px]]
  
 +
===Changing Buttons===
 +
Next let's add properties to the Delete and Add buttons.
  
===Text Field===
+
===The Delete Button===
 +
The button in the lower-left corner will become the Delete button.
  
The Text Field is where the user types the Task to add to the list.
+
# Click on the button in the lower-left corner to select it. The Inspector now shows its properties.
 +
# In the Name field (located in the ID group), change the name from “Button1” to “DeleteButton” and press Return.
 +
# In the Caption field (located in the Appearance group), change the name from “Button” to “Delete”. 
 +
# Now you need to make changes to the locking properties so that the Delete button stays in the lower-left corner of the web page when the web page resizes. In the Locking group, click the Top lock to unlock it and the Bottom lock to lock it.<br>[[File:Web Tutorial Delete Button Locks.png|100px]]
  
#. In the Library, click on TextField and drag it to the web page so that it is between the delete and add buttons.
+
===The Add Button===
#. Resize the Task field. Select the rightmost drag handle and drag the TextField so that it is the same width as the Listbox.
+
The button in the lower-right corner will become the Add button. It's a default button which means that pressing the Return key will active it.  
Use the alignment indicators as guides to help you line everything up correctly.
 
After adding all the controls, your web page should now look like this:
 
[[File:Web Tutorial Layout.png]]
 
  
==Properties==
+
# In the Layout Editor, click the button in the lower-right corner to select it.
What is a Property?
+
# Change the Name property from “Button2” to “AddButton” and press Return.
 +
# Change the Caption property from “OK” to “Add” and press Return.
 +
# Now you need to check the locking properties so the Add button stays in the bottom-corner of the web page when the web page resizes. Click the locks so that the right and bottom are locked and top and left are unlocked.<br>[[File:Web Tutorial Add Button Locking.png|100px]]
  
Controls have various values associated with them such as their caption, height, width and more. Because they help describe the control, they are called ''Properties''. Changing property values allows you to change the look and behavior of the object. For this project, let's change various properties of the webpage and the controls you added. Some of the things you need to do are:
+
===TextField Properties===
 +
The TextField is where your user will type the task to add to the list.  
  
#. Rename all controls (and the web page) so that they describe their behavior and are easy to refer to in code.
+
# In the Layout Editor, click on the TextField to select it.
#. Add a Caption to each Button.
+
# Change the Name property from “TextField1” to “TaskField” and press Return.
#. Make the controls resize properly when the window is resized by setting the locking properties.
+
# To TaskField get wider/narrower as the webpage is resized, click the locks so that left, bottom and right are locked and top is unlocked.<br>[[File:Web Tutorial TextField Locking.png|100px]]
  
===Inspector===
+
===Final Layout===
The Inspector is used to change web page and control properties. It shares the same area on the right of the Workspace as the Library. In order to show the Inspector, click the Inspector button on the toolbar or press ⌘-I (Ctrl+I on Windows and Linux).
+
After adjusting all the properties for the web page and its controls, your layout should look like this:
  
===Web Page Properties===
+
[[File:Web Tutorial Layout.png|700px]]
  
If you haven’t already, display the Inspector by clicking the Inspector button on the toolbar. You need to change the Name and Title properties of the web page:
+
==Saving the Project==
 +
Before we run the app to test it, it’s a good idea to save your project so should something go wrong you don’t lose your work:
 +
# Choose File > Save.
 +
# Name the project “Task Manager” and click Save.
  
#. First, in the Layout Editor, click on the title bar of the web page to select it.
+
==Running the App==
The Inspector pane now shows the properties for the web page.
+
Your user interface layout is now complete, so it’s time to try it out. Remember, you haven't added any code yet, so the app won't "work".
#. In the Name field (located in the ID group), change the name from “WebPage1” to “TaskManagerPage”. Press Return to see the name change in the Navigator.
 
#. In the Title field (located in the Frame group), change the name from “Untitled” to “Task Manager”. Press Return to see the name change in the title bar of the web page.
 
  
===ListBox Properties===
+
# Click the Run button in the toolbar to run the project. Because this is a web project, it runs in your browser. If your browser wasn't already running, Xojo launches it for you.
 +
# When the Task Manager is displayed, you can interact with the buttons by clicking on them, you can type in the TextField and you can resize the web page to see the buttons and TextField reposition themselves.
 +
# Close the browser tab or window to return to the Layout Editor. Xojo won't know that you closed the browser window or tab for several minutes.
 +
# To stop the app, click the Stop button in the Debugger (which we will talk about more later).<br>[[File:Web Tutorial Debugger Stop Button.png|300px]]
  
The Listbox is where the tasks that your user enters are displayed and stored. You need to change the following properties: Name, ColumnCount, Initial Value, ColumnWidths and Locking.
+
==Adding Functionality With Code==
 +
===Add Button===
 +
The Add button adds tasks to the list. The code you add to the button needs to take what was typed in TaskField and add it as a new row to the TaskList ListBox.
  
#. First, in the Layout Editor, click on the Listbox to select it. The Inspector pane now shows the properties for Listbox.
+
Follow these steps to add the code:
#. In the Name field (located in the ID group), change the name from “Listbox1” to “TaskList”. Press Return to see the name change in the Navigator.
 
#. The Listbox has two columns, one to show the completed status and another to show the name of the task. In the ColumnCount field, change the value from “1” to “2” and press Return.
 
#. You want to change the column headers to describe the data in the list. In the Inspector, click the pencil button for the Initial Value property. This will bring up the Initial Value editor.
 
#. In the Initial Value editor type "Completed", press the Tab key and then type "Task." Click the OK button when you're finished editing.
 
#. Since Completed is only going to contain a simple checkmark when the task is marked as completed, it can be narrower. In the ColumnWidths field, change the value from “*” to “100,*”. Press Return to see the column widths change on the web page. Using “100,*” tells the Listbox that the first column should always be 100 pixels wide and that the rest of the columns share the available width.
 
#. Lastly you need to make changes to the locking so that the Listbox gets larger or smaller as the web page size changes. In the Locking group, look at the image that shows the web page with small locked icons for the top and left and small unlocked icons for bottom and right. Click the locks so that top, left, bottom and right are all locked.
 
  
==Button Properties==
+
1. In the Layout Editor, double-click the AddButton control. The Add Event Handler window appears. When a user presses a button, the Pressed event handler is called.
The three buttons are used to perform actions. You need to change the following properties for each button: Name, Caption and Locking.
 
  
===Delete Button===
+
2. The Pressed Event Handler is already selected so just click the OK button to accept it.
The Delete button is used to remove tasks from the TaskList.
 
  
#. In the Layout Editor, click on the Delete button to select it (this is the button directly below the Listbox).
+
This displays the Code Editor. Now you need to get the task that was typed into the TaskField. You might think you could get the task just by using "TaskField", the name of the field. That is close, but not quite enough. The name of the control represents the entire control with all of its properties. What you want is just the text in the TaskField. To do that you type the name of the control, followed by a dot, followed by the name of the property. In other words, you use this syntax: ControlName.PropertyName. This is something called “dot” notation and is commonly used in object-oriented programming. In this case the control is named TaskField and the property you want is Text (use the [[WebButton]] to find out about all the properties available to TextFields). The syntax looks like this: TaskField.Text
The Inspector now shows the properties for WebButton.
 
#. In the Name field (located in the ID group), change the name from “Button1” to “DeleteButton”. Press Return to see the name change in the Navigator.
 
#. In the Caption field (located in the Appearance group), change the name from “Untitled” to “Delete”. Press Return to see the name change on the button in the web page.  
 
#. Now you need to make changes to the locking so that the Delete button stays on the right side of the web page when the web page resizes. In the Locking group look at the image that shows the web page with small locked icons for the top and left and small unlocked icons for bottom and right.
 
#. Click the locks so that right and bottom are locked and left and top are unlocked.
 
  
===Button===
+
The ListBox control has a built-in function for adding a row to itself. That function is appropriately called AddRow. Functions like this in Xojo are more generally referred to as methods. The AddRow method can take multiple values allowing you to fill in as many columns as you want with a single call.  
The Add button is used to add the task entered in the TextField to the Task List.
 
  
#. In the Layout Editor, click on the Add button to select it (this is the button on the far left of the web page below the TextField). The Inspector now shows the properties for PushButton.
+
The first column contains the completed status  of each task, so it is initially set to blank. The second column contains the name of the task.
#. In the Name field (located in the ID group), change the name from “Button2” to “AddButton”. Press Return to see the name change in the Navigator.
 
#. In the Caption field (located in the Appearance group), change the name from “Untitled” to “Add”. Press Return to see the name change on the button in the web page.
 
#. Now you need to check the locking so that the Add button stays on the bottom of the web page when the web page resizes. In the Locking group look at the image that shows the web page with small locked icons for the top and left and small unlocked icons for bottom and right.
 
#. Click the locks so that left and bottom are locked and top and right are unlocked.
 
  
===Complete Button===
+
3. Add this code to the Pressed event:<br>
The Complete button is used to mark a task as completed.
+
<rbcode>
 +
TaskList.AddRow("", TaskField.Text)
 +
</rbcode>
 +
4. Run the app to test it out.
  
#. Click on the Complete button to select it (this is the button directly below the TextField on the right). The Inspector now shows the properties for WebButton.
+
5. Type tasks in the TaskField and click the Add button to see them appear in the TaskList ListBox.
#. In the Name field (located in the ID group), change the name from “Button3” to “CompleteButton”. Press Return to see the name change in the Navigator.
 
#. In the Caption field (located in the Appearance group), change the name from “Untitled” to “Complete”. Press Return to see the name change on the button in the web page.
 
#. Now you need to make changes to the locking so that the Complete button stays on the right side of the web page when the web page resizes. In the Locking group look at the image that shows the web page with small locked icons for the top and left and small unlocked icons for bottom and right.
 
#. Click the locks so that right and bottom are locked and left and top are unlocked. In the Project List, the newly renamed controls show under the Controls for TaskManagerPage.
 
  
===Text Field Properties===
+
6. Close the browser tab or window.
The TextField is where your user will type the task to add to the list. You need to change the following properties: Name and Locking.
 
  
#. In the Layout Editor, click on the TextField to select it. The Inspector now shows the properties for the TextField.
+
7. The app is still running in Xojo, so click the Stop button to return to the Code Editor.
#. In the Name field (located in the ID group), change the name from “TextField1” to “TaskField”. Press Return to see the name change in the Navigator.
 
#. Now you need to make changes to the locking so that the TextField gets larger or smaller when the web page resizes. In the Locking group look at the image that shows the web page with small locked icons for the top and left and small unlocked icons for bottom and right.
 
#. Click the locks so that left, bottom and right are locked and top is unlocked.
 
  
==Final Layout==
+
===Marking Tasks As Complete===
After adjusting all the properties for the web page and its controls, your layout should look like this:
+
When the user clicks in the Completed column of the TaskList, the selected task should toggle between being displaying a checkmark (✓) and displaying nothing.
 +
 
 +
Let's add code to the TaskList in the same way we added code for the Add button:
  
[[Fiile:Web Tutorial Final Layout.png]]
+
# Click on TaskManagerPage in the Navigator.
 +
# Double-click the TaskList control on your layout.
 +
# In the Add Event Handler dialog box, select the Pressed event and click the OK button.  
  
==Running the App==
+
Notice that the name of the event (Pressed) appears at the top of the Code Editor. Along with it are the names of two values (row and column) that are automatically populated when the Pressed event is called. It also indicates they are both integers. Values that are passed into a method or event are called parameters. Like AddRow, the ListBox control has another method that lets you get and set the value in a cell. This method is called CellValueAt and it expects you to tell it which row and column to access. In this case, the Pressed event's row parameter provides us with the row number. Columns in a ListBox are numbered starting at 0 so that's the number of you Completed column in this project.
Your user interface layout is now complete, so it’s time to try it out. But before you go further, you should first save your work.
 
  
===Saving the Project===
+
Enter this code for the TaskList's Pressed event. And then I will explain what's going on here.
  
#. Choose File > Save.
+
<rbcode>
#. Name the project “TutorialWeb” and click Save.
+
If column = 0 Then
 +
  If Me.CellValueAt(Me.SelectedRowIndex, 0) = "" Then
 +
    Me.CellValueAt(Me.SelectedRowIndex, 0) = "✓"
 +
  Else
 +
    Me.CellValueAt(Me.SelectedRowIndex, 0) = ""
 +
  End If
 +
end If
 +
</rbcode>
  
Now you can test your app:
+
This code uses IF (a conditional operator) to make a decision. On the first line, it checks to see IF the column that was pressed was the first column (column 0 AKA the "Completed" column). If it is, then it continues to the next line that checks to see if column 0 of the selected row is blank. Let's dissect this line a bit further: Me.CellValueAt(Me.SelectedRowIndex, 0) = ""
  
#. Click the Run button in the toolbar to run the project.
+
Remember that to call a method, you need to start with the name of the control. A shortcut for this is a function appropriately titled, "Me". It simply means the control from which Me was called. This is convenient as well because if you change the name of a control you won't have to update any code in the control's events that refers to itself. Next is CellValueAt, the method already discussed. It takes two parameters: a row and a column. For the column, we are once again using Me and then calling a property of the ListBox called SelectedRowIndex. As you may have already deduced, SelectedRowIndex returns the number of the selected row. That value is then being passed as the first parameter to CellValueAt. The second parameter is 0 because the only column we care about is column 0 (the Completed column). Finally we compare the value from the cell at the intersection of Me.SelectedRowIndex and 0 to "" (which means an empty text value). If it's empty, we use nearly the same code to assign it a checkmark. If it's not, we go to the ELSE part of the code and set it to empty ("").
#. When Task Manager is displayed, you can interact with the buttons by clicking on them, you can type in the TextField and you can resize the web page to see the buttons reposition themselves.
 
#. Close the browser tab or window to return to the Layout Editor.
 
  
Of course, Task Manager doesn’t do anything yet! For that you need to add some code, which is what you'll do next.
+
Now if you've never written a line of code before, that may seem like a long explanation for some code that simply toggles a cell. I can only say that computers can't think for themselves and need a lot of details to get the job done. The good news is that the more code you write, the easier it will get.
  
==Adding Code==
+
# Since you've already entered the code, run the app and add a few sample tasks.
===Add Button===
+
# Now try toggling the Completed column by clicking in that column for one of your tasks.
The Add button adds tasks to the list. The code you add to the button needs to take what was typed in TaskField and add it as a new row to the list.
+
# When you're done, close the browser tab or window.
 +
# The app is still running in Xojo. Press stop in Xojo.
  
Follow these steps to add the code:
+
===Delete Button===
 +
The code you add to the delete button needs to determine which row is selected in the list and remove it.
  
1. In the Layout Editor, double-click the AddButton control. The Add Event Handler window appears. When a user presses a WebButton, the Pressed event handler is called.
+
Add code to the Delete button in the same way you added code for the Add button:
2. The Pressed Event Handler is already selected so just click the OK button.
 
  
This displays the Code Editor. Also notice the Navigator updates to show the Pressed event underneath the AddButton control.
+
# In the Navigator, click the the TaskManagerPage to select it and show the Layout Editor.
Now you need to get the task that was typed into the TaskField. You might think you could get the task just by referring to the name of the field, TaskField. That is close, but not quite what you want. What you instead need is a property of TaskField. When you need to refer to a property of an object, you use the name of the object, followed by a dot, followed by the name of the property. In other words, you use this syntax: ObjectName.PropertyName. This is something called “dot” notation and is commonly used in object-oriented programming. In this case the object is TaskField and the property you want is Value (use the Language Reference to find out about all the properties available to TextFields). The syntax looks like this:
+
# In the Layout Editor, double click on your Delete button to add the Pressed event handler.  
 +
# Once again we will be using a method of the ListBox. This one is appropriately named, "RemoveRowAt." Since it's removing an entire row, it only needs to know which row is getting the axe. Once again, we will be using the SelectedRowIndex method. This time, however, we can't use Me because we are calling the method from an event of the Delete button not the ListBox:
 +
<rbcode>
 +
TaskList.RemoveRowAt(TaskList.SelectedRowIndex)
 +
</rbcode>
 +
5. For a good user experience, the Delete button should be enabled only when the user has a row selected in the TaskList ListBox and disabled when no row is selected. To make that happen, add the following code to the ListBox's SelectionChanged event:
 
<rbcode>
 
<rbcode>
TaskField.Value
+
If Me.SelectedRowIndex = -1 Then
 +
  DeleteButton.Enabled = False
 +
Else
 +
  DeleteButton.Enabled = True
 +
End If
 
</rbcode>
 
</rbcode>
 +
6. Save the project.
  
To actually add a row to a Listbox, you use the AddRow method. You already know how to get the text in the TaskField from step 2. As you have seen before, objects can have properties. And as you now see with TaskList, objects can also have methods. AddRow is one of many methods available to Listboxes and it adds values to the two columns in TaskList. The first column contains the completed status, so it is initially set to blank. The second column contains the name of the task.
+
7. Run the app and add and delete some tasks to test it out.
  
3. Add this code to the Pressed event: TaskList.AddRow("", TaskField.Value)
+
==Finding and Fixing Bugs: The Fine Art of Debugging==
4. Save the project by choosing File > Save.
+
No matter how experienced you get at writing code, you're going to create bugs.  
5. Run the app to test it out.
+
{{Information|Remember, computers can only do exactly what we tell them to do. If you tell them to do something, they will do it without complaint. Some bugs are obvious and easy to find, others are are sneaky and love to hide in the dark corners of your projects so you can spend your time looking for them instead of creating new ones.}}
6. Type tasks in the TaskField and click the Add button to see them appear in the task list.
 
7. Close the browser tab or window.
 
8. The app is still running in Xojo, so click the Stop button in the toolbar to return to the Code Editor.
 
  
===Complete Button===
+
Although your app works just fine, believe it or not there is a bug that needs addressing. Do you know what it is?
When the user clicks the Complete button, the selected task in the Listbox should be marked as completed. This is indicated by showing a checkmark (✓) in the Completed column.
 
  
Let's add code to the Complete button in the same way we added code for the Add button:
+
Here’s a hint: What happens if you you click the Delete buttons but have not selected a task? Let's find out!
  
1. On the web page, double-click the CompleteButton control, labelled “Complete”.
+
1. Run the app and click on the Delete button without selecting a task, observe what happens.
2. The Pressed event is already selected so click the OK button.
 
Notice the Navigator updates to show the Pressed event underneath the CompleteButton control. To change a row, you first need to know what row is selected. In a Listbox, the currently selected row is contained in the ListIndex property. To set the value in a particular cell of a Listbox, you use the Cell property, specifying the row and column.
 
3. In the Pressed event handler, add this code to put the checkmark character in column 0 (the completed column) of the currently selected row: TaskList.CellValueAt(TaskList.SelectedRowIndex, 0) = "✓"
 
  
4. Run the app and add a few sample tasks.
+
[[File:Web Tutorial OutOfBounds Exception.png|700px]]
5. Now click on a task and click the Complete button.
+
 
A checkmark appears in the Completed column.
+
Xojo has switched to its Debugger and has highlighted a line of code where an error occurred.
6. Close the browser tab or window.
+
 
7. The app is still running in Xojo, so click the Stop button in the toolbar to return to the Code Editor.
+
[[File:Web Tutorial Debugger Error.png|600px]]
 +
 
 +
You can tell where this error occurred but you can also tell by looking at the Stack pane of the Debugger. Notice that it indicates it's in the DeleteButton's Pressed event:<br>[[File:Web Tutorial Debugger Stack.png|300px]]<br>
 +
 
 +
The error occurred because you attempted to remove a row that does not exist. When no row is selected in the ListBox, the SelectedRowIndex property returns -1. Since this is not a valid row number, the CellValueAt method caused an error. Specifically, the value passed was out of bounds and thus the error is called an OutOfBoundsException. It's called an Exception because it's something exceptional that happened. You can tell it's OutOfBoundsException by looking at the Debugger's Variables pane:
 +
 
 +
<br>[[File:Web Tutorial Debugger Variables.png|600px]]<br>
 +
 
 +
2. Close the browser tab or window.
  
===Delete Button===
+
3. Click the Stop button in the toolbar to return to the Code Editor.
The Delete button is used to remove tasks from the list. The code you add to the button needs to determine the selected row in the list and remove it from the list.
 
  
Let's add code to the Delete button in the same way we added code for the Complete button:
+
Luckily, it is easy to prevent this bug from occurring. We are just going to prevent the user from even pressing the Delete button if they don't have a row selected. That way SelectedRowIndex can never be out of bounds.
  
1. On the web page, double-click the DeleteButton control. The Add Event Handler window appears.
+
4. Click the TaskManager page in the Navigator.
2. The Pressed event handler is already selected so click the OK button.
 
Since the selected row will be deleted, you again want to use the SelectedRowIndex property.
 
3. Use the Listbox method RemoveRowAt to remove a row from the Listbox. You pass RemoveRowAt the row number to remove as a parameter. # Add this code to the Pressed event handler:
 
<rbcode>
 
TaskList.RemoveRow(TaskList.SelectedIndex)
 
</rbcode>
 
4. Save the project by choosing File > Save.
 
5. Run the app and add a few sample tasks.
 
6. Click on a task in the Task List then click the Delete button. The task is removed from the list.
 
  
=Debugging==
+
5. Select the Delete button and then in the Inspector, turn off the Enabled property. Now the Delete button is disabled by default.
Finding Bugs is part of creating apps. A bug is when your code or app does something unexpected, often leading to a crash. Although your app works just fine, there are a couple of lingering bugs that need addressing. Have you figured out what the problem is?
 
  
Here’s a hint: What happens if you you click on the Complete or Delete buttons but have not selected a task? Try it.
+
6. Now select the TaskList to add another event. This time, click the Add button [[File:Web Tutorial Layout Editor Add Button.png|30px]] in the Layout Editor's toolbar and select Add Event Handler from its menu. You have to add the new event this way because you've already added the Pressed event so double-clicking on the TaskList would take you there instead of adding a new event.
  
1. Run the app and click on the Complete button without selecting a task.
+
7. Add the SelectionChanged event.
Xojo has switched to its Debugger with a line of code highlighted because an error has occurred. The error occurred because you attempted to remove (or complete) a row that does not exist. When no row is selected in the Listbox, the SelectedRowIndex property returns -1. Since this is not a valid row in the Listbox, the CellValueAt method caused an error. Specifically, the value passed was out of bounds and thus the error is called an ''OutOfBoundsException''. It's called an ''Exception'' because it's something that is the unusual case.
 
2. Click the Resume button in the Debugger toolbar, to see the actual error message.
 
3. Close the browser tab or window.
 
4. Click the Stop button in the toolbar to return to the Code Editor.
 
Nobody wants buggy code. Luckily it is easy to prevent this bug from occurring. Essentially, you want to make sure a row is selected before you attempt to Delete or Complete a task.
 
The code to do this uses what you have already learned.
 
  
1. Edit the code for Pressed event handler of the DeleteButton as follows:
+
8. In that event, add the following code and then I'll explain, though perhaps you have figured it out on your own:
 
<rbcode>
 
<rbcode>
If TaskList.SelectedRowCount > 0 Then
+
If Me.SelectedRowIndex = -1 Then
   TaskList.RemoveRowAt(TaskList.SelectedRowIndex)
+
   DeleteButton.Enabled = False
 +
Else
 +
  DeleteButton.Enabled = True
 
End If
 
End If
 
</rbcode>
 
</rbcode>
5. Edit the code for the Complete button as well:
+
 
<rbcode>
+
When the user changes which row is selected (which includes selecting no row at all), the SelectionChanged event is called. This code checks to see if the SelectedRowIndex is -1 which means no row is selected. If that's the case, we set the Enabled property of the button to False or otherwise to True. Your code can't fail if it can't be called in a situation where it could fail.
If TaskList.SelectedRowCount > 0 Then
+
 
  TaskList.CellValueAt(TaskList.SelectedRowIndex, 0) = "✓"
+
9. Run your app again and you'll observe that this bug is no longer an issue. When you're done, return to Xojo and hit the Stop button.
End If
 
</rbcode>
 
In both cases, the code verifies that a row is selected by checking the SelectedRowCount property to ensure that a row is selected before the actual method is called.
 
6. Save the project by choosing File > Save.
 
7. Run the project again and click the Complete button without selecting a row in the task list. No more bug!
 
  
 
==Finishing the App==
 
==Finishing the App==
===Testing===
 
Just because your app seems to work, doesn’t mean you are finished with it. A good developer always thoroughly tests their apps to look for possible problems.
 
 
You already found and fixed one problem (pressing the Completed or Delete button when no row was selected). Do you think there are other problems to fix? Run the app and play around with it a bit. Make a note of things you want to change. In the next section, you will add some improvements to Task Manager.
 
  
 
==Improvements==
 
==Improvements==
Did you notice that there are times when the buttons in Task Manager probably should be disabled? For example, the Complete button should not mark a task as completed if one is not selected. Right now you can click it, but nothing happens. Also, you are not going to want to add a task to the list if nothing has been entered in the Taskfield.
+
Did you notice that the Add button is enabled even when you haven't entered a task? The user probably doesn't want to accidentally enter an empty task. And after you click it, the task you just entered is still in the TaskField. So first, we need to disable the Add button when there's no text in the TaskField and second, unless you're the type to do the same task over and over, we will need to remove the last one from the TaskField after we add it to the TaskList.
  
There are several ways to accomplish this, but one way is to disable the buttons when they should not be used.
+
# Click TaskManager page in the Navigator to get back to the Layout Editor.
 
+
# When the text is changed in the TaskField, we decide whether or not to Enable the Add button. Double click on the TaskField to add the TextChanged event.
Follow these steps to add this improvement:
+
# Now enter the following code:
 
 
1. On the web page, select the Complete button.
 
2. In the Inspector, turn off the Enabled property (in the Appearance group).
 
3. Select Add Button.
 
4. In the Inspector, turn off the Enabled property (in the Appearance group).
 
5. Select the DeleteButton.
 
6. In the Inspector, turn off the Enabled property (in the Appearance group).
 
Now you will add code to enable the Add button when there is text in the TaskField.
 
7. On the web page, double-click the TaskField control.
 
The Add Event Handler window appears. Here you are seeing yet another list of event handlers. Every control type has its own specific list of event handlers. In this case, we want to disable AddButton when there is no value in the Taskfield and enable it when there is a value. The ValueChanged event is called whenever the value in the Taskfield is changed, either by the user typing or by your code changing the Value property.
 
8. ValueChanged is already selected so press the OK button.
 
You now need code that checks the Value property of the TaskField (Me.Value) to see if anything is there. If there is a value there, then the AddButton is enabled by setting its Enabled property to True. If there is no value, then it is disabled by setting its Enabled property to False.
 
9. Enter the following code:
 
 
<rbcode>
 
<rbcode>
If Me.Value <> "" Then
+
If Me.Text = "" Then
 +
  AddButton.Enabled = False
 +
Else
 
   AddButton.Enabled = True
 
   AddButton.Enabled = True
Else
 
  AddButton.Enabled = False
 
 
End If
 
End If
 
</rbcode>
 
</rbcode>
You already added code to prevent the Delete and Complete buttons from doing anything if no row is selected in the Task List. Now you can also make those buttons enable when a row is selected and disable when no rows are selected. This is accomplished with the SelectedRowCount property of the Listbox.
+
Let's make the Add button remove the text from the TaskField after it creates a task out of it:
10. Double-click the TaskList control.
+
 
The SelectionChanged event is called whenever the selection in the TaskList control changes.
+
# Select the AddButton in the Navigator to both display the TextManagerPage in the Layout Editor and select the AddButton at the same time.  
11. SelectionChanged is already selected so press the OK button.
+
# In the Inspector, turn off the AddButton's Enabled property.
12. Add this code:
+
# Next we need to update the Add button's Pressed event handler so double-click it to get to the Pressed event.
 +
# Now you should be staring at the first line of code you wrote. Press Return to create new line.
 +
# On that brand new line, enter this code to set the Text property of the TaskField to an empty text value.
 
<rbcode>
 
<rbcode>
If Me.SelectedRowCount > 0 Then
+
TaskField.Text=""
  DeleteButton.Enabled = True
 
  CompleteButton.Enabled = True
 
Else
 
  DeleteButton.Enabled = False
 
  CompleteButton.Enabled = False
 
End If
 
 
</rbcode>
 
</rbcode>
14. Save the project by choosing File > Save.
+
 
15. Run the app to test it out.
+
Go ahead and save your code. Run your app to test out this newest version.  
Notice that the Add button is initially disabled. But try typing some text in the TaskField. The Add button immediately become enabled. And if you remove the value from the TaskField, the buttons again become disabled. Similarly, when you click on a row in the Task List, the Delete and Complete buttons become enabled.
 
  
 
==Deploying the App==
 
==Deploying the App==
There are several ways to deploy a Xojo web app. The easiest way is to use Xojo Cloud so that you can just click "Deploy" on the main toolbar to send your app to web server where it can be used.
+
There are several ways to deploy a Xojo web app. The easiest way is to use [https://www.xojo.com/cloud Xojo Cloud] so that you can just click "Deploy" on the main toolbar to send your app to a web server where it can be used. You can also deploy your app yourself as a <nowiki>''</nowiki>standalone application<nowiki>''</nowiki> that is a self-contained app and web server which can be run on any computer or server. Users can access the app by using the computer's URL and port number.
 +
 
 +
To learn more about these options, refer to [[UserGuide:Web_App_Deployment_Overview|Web App Deployment Overview]] in the User Guide.
  
You can also deploy apps yourself as a ''standalone application'' that is a self-contained app and web server which can be run on any computer or server. Users can access the app by using the computer's URL and port number.
+
==Next Steps==
 +
Congratulations, you have successfully completed the Web Tutorial and now have a fully functional web app. Watch [https://youtu.be/X2Q0iZjAEWM this video tutorial] to learn how to connect this app to a SQLite database. To continue on your journey of learning Xojo, you should next move on to the [[User Guide]], which covers Xojo in its entirety. You will also want to refer to the [http://docs.xojo.com/Category:Language_Reference Language Reference] Guide, which covers the specifics of language elements, classes and other details of Xojo.  
  
To learn more about these options, refer to [Web App Deployment|Web_App_Deployment_Overview] in the User Guide.
+
Go to the documentation when you run into trouble, check out the example projects included with Xojo and hop on over to the [https://forum.xojo.com Xojo Community Forum] and start asking questions. There are lots of experienced Xojo users eager to help.
  
==Next Steps==
+
==Feedback==
Congratulations, you have successfully completed the Web Tutorial and now have a fully functional app. To continue on your journey of learning Xojo, you should next move on to the [UserGuide|User_Guide], which covers Xojo in its entirety. You will also want to refer to the [Language Reference|language_reference], which covers the specifics of language elements, classes and other details of Xojo.
+
What did you think of this tutorial? We'd appreciate your feedback, [mailto:hello@xojo.com write to us].

Latest revision as of 17:47, 30 April 2021

Learn the Basics

Xojo is a cross-platform integrated development environment (IDE) that is made up of a rich set of graphical user interface objects, the modern object-oriented Xojo programming language, an integrated debugger, and a multi-platform compiler. With the IDE, you can build your app's interface simply by dragging and dropping interface objects onto the app's web pages and dialogs.

Once you have completed the Web Quickstart, this tutorial will walk you through creating a more intermediate web app, a Task Manager. This is what the completed app will look like:

Finished Web Tutorial App.png

Task Manager Tutorial

Getting Started

  1. Launch Xojo. After it loads, the Project Chooser window appears.
  2. Choose Web, since we're building a web app, and press OK. A new Xojo project window will appear.

Xojo Project Chooser Web.png

The Xojo Project Window

This window has three basic parts:

Web Layout Editor.png

Navigator: The area on the top left shows you all the items in your project. By default you can see WebPage1 (which is selected), the App object and the Session object. Use the Navigator to navigate within your project.

Editor: The center area is the Editor Area. Currently it's showing the Layout Editor. You use the Layout Editor to design the user interface for the web pages in your app. It shows the web page and previews how it looks when the app runs in a web browser. In this image, the web page is blank because you haven't yet added any user controls. The Editor Area however can also show other kinds of editors for editing code, icons and other things you might use in a project.

Library: The area on the right is the Library and shows the controls and interface elements that you can add to a web page. You design the web page by dragging controls from the Library to it. You can also add a control to the web page by double-clicking it.

fa-info-circle-32.png
If your Library looks different than mine, that's because I like mine showing icons only. You can customize yours by clicking on the small gear icon near the top-left corner of the Library and then choosing a different setting.

If the Library is not visible, click the Library button on the toolbar to show it.

Inspector: Not shown in the above image is the Inspector, which allows you to see and change the various attributes (the height, width, name and more) of any control you've added to your webpage. This area of the window is shared with the Library. You can show the Inspector by clicking the Inspector button on the toolbar. The Inspector shows information about the selected item in the Navigator or Editor. The contents of the Inspector changes as you click on different items.

About the App You Are About to Create

In this tutorial you will create an app to track tasks, called "Task Manager." When finished, the Task Manager app will let you enter tasks in a field then click the Add button to add them to the Task list. You can click on individual tasks in the list to delete them or mark them as complete.

Finished Web Tutorial App.png

Designing the User Interface

Creating The Task List

WebPage1 is open in the Layout Editor. First, you need to add a TaskList (ListBox) to the web page.

  1. In the Library, click on the ListBox and drag it to the top-left corner of the Layout Editor. As you get close to the edges of the web page, you will see alignment guides that help you position the control to leave the right amount of space between the edge of the browser window and the control.
    ListBox Library Icon.png
    Web Tutorial Listbox Alignment Guides.png
  2. When the alignment guides appear, drop the ListBox.
  3. Click on the Listbox to select it and then use the handles to resize it. Leave about 1/4th of the webpage blank for the other controls you're about to add. Your project should now look like this:
    Web Tutorial Resized ListBox.png

Adding the Buttons and TextField

Now add the Delete and Add buttons.

  1. In the Library, click on the Button control Button control icon.png and drag it to the lower-left corner of the web page.
  2. Now drag a Default Button control Default Button control icon.png to the lower-right corner of the web page. This button is labeled, "OK" by default but we will change it to "Add" later.
  3. Last but not least, drag a TextField control TextField control icon.png from the Library and drop it next to the Delete button.
  4. Resize the Textfield so that its right side is aligned with the left side of the OK button.


After adding all the controls, your web page in the Layout Editor should look like this:

Web Tutorial Layout.png

fa-info-circle-32.png
If on your computer the browser frame of the web page looks different from what you see in this tutorial, that's because Xojo draws a frame that is similar to the default browser of the OS upon which you are running Xojo.

Customizing Controls with Properties

Controls have various values associated with them such as their caption, height, and width. Because they help describe the control, they are called Properties. Changing property values allows you to change the look and behavior of the control.

Inspector

The Inspector is used to change web page and control properties. It shares the same area as the Library on the right side of the window.

fa-info-circle-32.png
The instructions in this tutorial enclose values you will type in quotation marks. When you enter values in the Inspector, don't type the quotation marks.

Web Page Properties

You need to change the Name and Title properties of the web page:

  1. Click the Inspector button Inspector Toolbar Button.png on the toolbar.
  2. In the Layout Editor, click anywhere on the web page where there is no control to select the page itself. The Inspector pane now shows the properties for the web page.
  3. In the Name field (located in the ID group), change the name from “WebPage1” to “TaskManagerPage”. Press Return to see the name change in the Navigator.
  4. In the Title field (located in the Frame group), change the name from “Untitled” to “Task Manager”. Press Return to see the name change in the title bar of the web page.
fa-info-circle-32.png
The labels the user sees such as the title of a page or the caption of a button, can have spaces. The names of controls, however, are used to refer to them in code and cannot have spaces in their names. If you add a space, Xojo will get confused because controls prefer to have single names like Madonna, Sting and Prince.

ListBox Properties

So the ListBox can properly display Tasks, we need to customize the properties.

  1. In the Layout Editor, click on the ListBox to select it. The Inspector pane now shows the properties for ListBox.
  2. In the Name field (located in the ID group), change the name from “ ListBox 1” to “TaskList”.
  3. The ListBox has two columns, one to show the completed status and another to show the name of the task. In the ColumnCount field, change the value from “1” to “2” and press Return. The ListBox will not show two columns in the Layout Editor but it will when you run your app.
  4. In the Inspector, turn on the Has Header button.
  5. You want to change the column headers to "Completed" and "Task". In the Inspector, click the pencil button to the right of the Initial Value property. This will bring up the Initial Value Editor.
  6. In the Initial Value editor type "Completed", press the Tab key and then type "Task." Click the OK button when you're finished editing.
  7. Since the Completed column is only going to contain a simple checkmark when the task is marked as completed, it can be narrow. In the ColumnWidths field, enter “30,*” and press Return. Using “30,*” tells the ListBox that the first column should always be 30 pixels wide and that the rest of the columns share the remaining width.
  8. Lock the edges of the ListBox to the edges of the webpage so the ListBox gets larger or smaller as the web page size changes. Click the locks so that top, left, bottom and right are all locked.
    Web Tutorial ListBox Locking Properties.png

Changing Buttons

Next let's add properties to the Delete and Add buttons.

The Delete Button

The button in the lower-left corner will become the Delete button.

  1. Click on the button in the lower-left corner to select it. The Inspector now shows its properties.
  2. In the Name field (located in the ID group), change the name from “Button1” to “DeleteButton” and press Return.
  3. In the Caption field (located in the Appearance group), change the name from “Button” to “Delete”.
  4. Now you need to make changes to the locking properties so that the Delete button stays in the lower-left corner of the web page when the web page resizes. In the Locking group, click the Top lock to unlock it and the Bottom lock to lock it.
    Web Tutorial Delete Button Locks.png

The Add Button

The button in the lower-right corner will become the Add button. It's a default button which means that pressing the Return key will active it.

  1. In the Layout Editor, click the button in the lower-right corner to select it.
  2. Change the Name property from “Button2” to “AddButton” and press Return.
  3. Change the Caption property from “OK” to “Add” and press Return.
  4. Now you need to check the locking properties so the Add button stays in the bottom-corner of the web page when the web page resizes. Click the locks so that the right and bottom are locked and top and left are unlocked.
    Web Tutorial Add Button Locking.png

TextField Properties

The TextField is where your user will type the task to add to the list.

  1. In the Layout Editor, click on the TextField to select it.
  2. Change the Name property from “TextField1” to “TaskField” and press Return.
  3. To TaskField get wider/narrower as the webpage is resized, click the locks so that left, bottom and right are locked and top is unlocked.
    Web Tutorial TextField Locking.png

Final Layout

After adjusting all the properties for the web page and its controls, your layout should look like this:

Web Tutorial Layout.png

Saving the Project

Before we run the app to test it, it’s a good idea to save your project so should something go wrong you don’t lose your work:

  1. Choose File > Save.
  2. Name the project “Task Manager” and click Save.

Running the App

Your user interface layout is now complete, so it’s time to try it out. Remember, you haven't added any code yet, so the app won't "work".

  1. Click the Run button in the toolbar to run the project. Because this is a web project, it runs in your browser. If your browser wasn't already running, Xojo launches it for you.
  2. When the Task Manager is displayed, you can interact with the buttons by clicking on them, you can type in the TextField and you can resize the web page to see the buttons and TextField reposition themselves.
  3. Close the browser tab or window to return to the Layout Editor. Xojo won't know that you closed the browser window or tab for several minutes.
  4. To stop the app, click the Stop button in the Debugger (which we will talk about more later).
    Web Tutorial Debugger Stop Button.png

Adding Functionality With Code

Add Button

The Add button adds tasks to the list. The code you add to the button needs to take what was typed in TaskField and add it as a new row to the TaskList ListBox.

Follow these steps to add the code:

1. In the Layout Editor, double-click the AddButton control. The Add Event Handler window appears. When a user presses a button, the Pressed event handler is called.

2. The Pressed Event Handler is already selected so just click the OK button to accept it.

This displays the Code Editor. Now you need to get the task that was typed into the TaskField. You might think you could get the task just by using "TaskField", the name of the field. That is close, but not quite enough. The name of the control represents the entire control with all of its properties. What you want is just the text in the TaskField. To do that you type the name of the control, followed by a dot, followed by the name of the property. In other words, you use this syntax: ControlName.PropertyName. This is something called “dot” notation and is commonly used in object-oriented programming. In this case the control is named TaskField and the property you want is Text (use the WebButton to find out about all the properties available to TextFields). The syntax looks like this: TaskField.Text

The ListBox control has a built-in function for adding a row to itself. That function is appropriately called AddRow. Functions like this in Xojo are more generally referred to as methods. The AddRow method can take multiple values allowing you to fill in as many columns as you want with a single call.

The first column contains the completed status of each task, so it is initially set to blank. The second column contains the name of the task.

3. Add this code to the Pressed event:

TaskList.AddRow("", TaskField.Text)

4. Run the app to test it out.

5. Type tasks in the TaskField and click the Add button to see them appear in the TaskList ListBox.

6. Close the browser tab or window.

7. The app is still running in Xojo, so click the Stop button to return to the Code Editor.

Marking Tasks As Complete

When the user clicks in the Completed column of the TaskList, the selected task should toggle between being displaying a checkmark (✓) and displaying nothing.

Let's add code to the TaskList in the same way we added code for the Add button:

  1. Click on TaskManagerPage in the Navigator.
  2. Double-click the TaskList control on your layout.
  3. In the Add Event Handler dialog box, select the Pressed event and click the OK button.

Notice that the name of the event (Pressed) appears at the top of the Code Editor. Along with it are the names of two values (row and column) that are automatically populated when the Pressed event is called. It also indicates they are both integers. Values that are passed into a method or event are called parameters. Like AddRow, the ListBox control has another method that lets you get and set the value in a cell. This method is called CellValueAt and it expects you to tell it which row and column to access. In this case, the Pressed event's row parameter provides us with the row number. Columns in a ListBox are numbered starting at 0 so that's the number of you Completed column in this project.

Enter this code for the TaskList's Pressed event. And then I will explain what's going on here.

If column = 0 Then
If Me.CellValueAt(Me.SelectedRowIndex, 0) = "" Then
Me.CellValueAt(Me.SelectedRowIndex, 0) = "✓"
Else
Me.CellValueAt(Me.SelectedRowIndex, 0) = ""
End If
end If

This code uses IF (a conditional operator) to make a decision. On the first line, it checks to see IF the column that was pressed was the first column (column 0 AKA the "Completed" column). If it is, then it continues to the next line that checks to see if column 0 of the selected row is blank. Let's dissect this line a bit further: Me.CellValueAt(Me.SelectedRowIndex, 0) = ""

Remember that to call a method, you need to start with the name of the control. A shortcut for this is a function appropriately titled, "Me". It simply means the control from which Me was called. This is convenient as well because if you change the name of a control you won't have to update any code in the control's events that refers to itself. Next is CellValueAt, the method already discussed. It takes two parameters: a row and a column. For the column, we are once again using Me and then calling a property of the ListBox called SelectedRowIndex. As you may have already deduced, SelectedRowIndex returns the number of the selected row. That value is then being passed as the first parameter to CellValueAt. The second parameter is 0 because the only column we care about is column 0 (the Completed column). Finally we compare the value from the cell at the intersection of Me.SelectedRowIndex and 0 to "" (which means an empty text value). If it's empty, we use nearly the same code to assign it a checkmark. If it's not, we go to the ELSE part of the code and set it to empty ("").

Now if you've never written a line of code before, that may seem like a long explanation for some code that simply toggles a cell. I can only say that computers can't think for themselves and need a lot of details to get the job done. The good news is that the more code you write, the easier it will get.

  1. Since you've already entered the code, run the app and add a few sample tasks.
  2. Now try toggling the Completed column by clicking in that column for one of your tasks.
  3. When you're done, close the browser tab or window.
  4. The app is still running in Xojo. Press stop in Xojo.

Delete Button

The code you add to the delete button needs to determine which row is selected in the list and remove it.

Add code to the Delete button in the same way you added code for the Add button:

  1. In the Navigator, click the the TaskManagerPage to select it and show the Layout Editor.
  2. In the Layout Editor, double click on your Delete button to add the Pressed event handler.
  3. Once again we will be using a method of the ListBox. This one is appropriately named, "RemoveRowAt." Since it's removing an entire row, it only needs to know which row is getting the axe. Once again, we will be using the SelectedRowIndex method. This time, however, we can't use Me because we are calling the method from an event of the Delete button not the ListBox:
TaskList.RemoveRowAt(TaskList.SelectedRowIndex)

5. For a good user experience, the Delete button should be enabled only when the user has a row selected in the TaskList ListBox and disabled when no row is selected. To make that happen, add the following code to the ListBox's SelectionChanged event:

If Me.SelectedRowIndex = -1 Then
DeleteButton.Enabled = False
Else
DeleteButton.Enabled = True
End If

6. Save the project.

7. Run the app and add and delete some tasks to test it out.

Finding and Fixing Bugs: The Fine Art of Debugging

No matter how experienced you get at writing code, you're going to create bugs.

fa-info-circle-32.png
Remember, computers can only do exactly what we tell them to do. If you tell them to do something, they will do it without complaint. Some bugs are obvious and easy to find, others are are sneaky and love to hide in the dark corners of your projects so you can spend your time looking for them instead of creating new ones.

Although your app works just fine, believe it or not there is a bug that needs addressing. Do you know what it is?

Here’s a hint: What happens if you you click the Delete buttons but have not selected a task? Let's find out!

1. Run the app and click on the Delete button without selecting a task, observe what happens.

Web Tutorial OutOfBounds Exception.png

Xojo has switched to its Debugger and has highlighted a line of code where an error occurred.

Web Tutorial Debugger Error.png

You can tell where this error occurred but you can also tell by looking at the Stack pane of the Debugger. Notice that it indicates it's in the DeleteButton's Pressed event:
Web Tutorial Debugger Stack.png

The error occurred because you attempted to remove a row that does not exist. When no row is selected in the ListBox, the SelectedRowIndex property returns -1. Since this is not a valid row number, the CellValueAt method caused an error. Specifically, the value passed was out of bounds and thus the error is called an OutOfBoundsException. It's called an Exception because it's something exceptional that happened. You can tell it's OutOfBoundsException by looking at the Debugger's Variables pane:


Web Tutorial Debugger Variables.png

2. Close the browser tab or window.

3. Click the Stop button in the toolbar to return to the Code Editor.

Luckily, it is easy to prevent this bug from occurring. We are just going to prevent the user from even pressing the Delete button if they don't have a row selected. That way SelectedRowIndex can never be out of bounds.

4. Click the TaskManager page in the Navigator.

5. Select the Delete button and then in the Inspector, turn off the Enabled property. Now the Delete button is disabled by default.

6. Now select the TaskList to add another event. This time, click the Add button Web Tutorial Layout Editor Add Button.png in the Layout Editor's toolbar and select Add Event Handler from its menu. You have to add the new event this way because you've already added the Pressed event so double-clicking on the TaskList would take you there instead of adding a new event.

7. Add the SelectionChanged event.

8. In that event, add the following code and then I'll explain, though perhaps you have figured it out on your own:

If Me.SelectedRowIndex = -1 Then
DeleteButton.Enabled = False
Else
DeleteButton.Enabled = True
End If

When the user changes which row is selected (which includes selecting no row at all), the SelectionChanged event is called. This code checks to see if the SelectedRowIndex is -1 which means no row is selected. If that's the case, we set the Enabled property of the button to False or otherwise to True. Your code can't fail if it can't be called in a situation where it could fail.

9. Run your app again and you'll observe that this bug is no longer an issue. When you're done, return to Xojo and hit the Stop button.

Finishing the App

Improvements

Did you notice that the Add button is enabled even when you haven't entered a task? The user probably doesn't want to accidentally enter an empty task. And after you click it, the task you just entered is still in the TaskField. So first, we need to disable the Add button when there's no text in the TaskField and second, unless you're the type to do the same task over and over, we will need to remove the last one from the TaskField after we add it to the TaskList.

  1. Click TaskManager page in the Navigator to get back to the Layout Editor.
  2. When the text is changed in the TaskField, we decide whether or not to Enable the Add button. Double click on the TaskField to add the TextChanged event.
  3. Now enter the following code:
If Me.Text = "" Then
AddButton.Enabled = False
Else
AddButton.Enabled = True
End If

Let's make the Add button remove the text from the TaskField after it creates a task out of it:

  1. Select the AddButton in the Navigator to both display the TextManagerPage in the Layout Editor and select the AddButton at the same time.
  2. In the Inspector, turn off the AddButton's Enabled property.
  3. Next we need to update the Add button's Pressed event handler so double-click it to get to the Pressed event.
  4. Now you should be staring at the first line of code you wrote. Press Return to create new line.
  5. On that brand new line, enter this code to set the Text property of the TaskField to an empty text value.
TaskField.Text=""

Go ahead and save your code. Run your app to test out this newest version.

Deploying the App

There are several ways to deploy a Xojo web app. The easiest way is to use Xojo Cloud so that you can just click "Deploy" on the main toolbar to send your app to a web server where it can be used. You can also deploy your app yourself as a ''standalone application'' that is a self-contained app and web server which can be run on any computer or server. Users can access the app by using the computer's URL and port number.

To learn more about these options, refer to Web App Deployment Overview in the User Guide.

Next Steps

Congratulations, you have successfully completed the Web Tutorial and now have a fully functional web app. Watch this video tutorial to learn how to connect this app to a SQLite database. To continue on your journey of learning Xojo, you should next move on to the User Guide, which covers Xojo in its entirety. You will also want to refer to the Language Reference Guide, which covers the specifics of language elements, classes and other details of Xojo.

Go to the documentation when you run into trouble, check out the example projects included with Xojo and hop on over to the Xojo Community Forum and start asking questions. There are lots of experienced Xojo users eager to help.

Feedback

What did you think of this tutorial? We'd appreciate your feedback, write to us.