Professional Documents
Culture Documents
Web Tutorial
From Xojo Documentation
Contents
1 Learn the Basics
2 Task Manager Tutorial
2.5.1 Inspector
2.5.2 Web Page Properties
2.5.3 ListBox Properties
2.5.4 Changing Buttons
2.5.5 The Delete Button
2.5.6 The Add Button
2.5.7 TextField Properties
2.5.8 Final Layout
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:
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.
If your Library looks different than the one above, that's because it was set to
show 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.
1. In the Library, click on the Button control and drag it to the lower-left corner of the web
page.
2. Now drag a Default Button control 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 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:
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.
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.
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.
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 Elvis, Sting and
Usher.
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.
Changing Buttons
Next let's add properties to the Delete and Add buttons.
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.
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.
TextField Properties
The TextField is where your user will type the task to add to the list.
Final Layout
After adjusting all the properties for the web page and its controls, your layout should look like this:
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).
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.
TaskList.AddRow("", TaskField.Text)
5. Type tasks in the TaskField and click the Add button to see them appear in the TaskList ListBox.
7. The app is still running in Xojo, so click the Stop button to return to the Code Editor.
Let's add code to the TaskList in the same way we added code for the Add button:
Enter this code for the TaskList's Pressed event. And then I will explain what's going on here.
If column = 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. Run the app and add and delete some tasks to test it out.
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.
Xojo has switched to its Debugger and has highlighted a line of code where an error occurred.
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:
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:
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.
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 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.
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.
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. Click at the end of the line and
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.
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.