I did some research and found that Amazon provides a service that does exactly what the client was asking for. The service, called Amazon Translate, is available as one of many services that are available through Amazon Web Services.

In this post, I’ll walk you through the process of getting signed up for Amazon Translate, and then share some code that you can use to add language translation to your own Xojo projects. We’ll use the MBS Xojo CURL Plugin, which makes calling the Amazon Translate API easy. But first, let’s learn a little about Amazon Translate.

Amazon Translate

Amazon Translate is an API that can be used to translate text on demand. You send it text in a “source language,” tell the API what that source language is, as well as the “target language” that you want the text translated to. The API responds with the translated text.

Amazon Translate uses machine learning and neural networks that have been designed specifically for language translation. When performing a translation, the service reads the text one sentence at a time, and reads each word individually, to determine the meaning of a sentence. In other words, the service doesn’t just translate words. Instead, it’s acting as an interpreter. This results in translations that are extremely accurate.

In order to use Amazon Translate, you’ll need an AWS account. If you already have an AWS account, log into the account.

Next, you’ll need to create an “Identity and Access Management” (IAM) user. To do so, under Services, select “IAM” (which can be found in the “Security, Identity, & Compliance” category). This will present you with the IAM Dashboard.

Under Groups, create a new group and give it a recognizable name. For example, you might call the group “translate.” As you are creating the group, give it the “TranslateFullAccess” permission.

Next, create an IAM user. Under Users, click the “Add user” button. Give the user a name such as “XojoTranslater.” For the “AWS access type” be sure to select “Programmatic access.” Add the user to the “translate” group that you created above. There’s no need to assign any tags to the user, so you can skip that step.

And finally, create an Access key for the user. Be sure to make note of both the “Access key ID” and “Secret access key” values that are automatically assigned. You’ll need these in order to make API calls.

The MBS Xojo CURL Plugin

If you don’t already have the MBS Xojo CURL Plugin, download it and install it. To install the plugin, simply drag it into the Xojo “Plugins” folder.

The project will work with an unlicensed version of the MBS Xojo CURL Plugin. In this case, you’ll occasionally see a popup message reminding you to purchase a license. However, I highly encourage you to purchase a license. You can license the plugin individually, or as part of the MBS Complete plugin bundle.

The Xojo Example Project

To demonstrate the Amazon Translate service, I’ve put together an example Xojo desktop project (project file). Before running the application, be sure to set the three App-level properties: AWSAccessKeyId, AWSSecretAccessKey, and the AWSRegion. For the AWSAccessKeyId and AWSSecretAccessKey properties, use the values that you set when you created the Access key for the user. For the AWSRegion, refer to this and use the value that makes the most sense for you.

Once you’ve configured the app, run it, and it will look something like this.

The Xojo Code

Let’s take a look at some of the code.

The AWSTranslator class is a subclass of the CURLSMBS class. The class does two important things: It provides access to a list of the languages that are supported, and provides a method for calling the Amazon Translate API.

The “Languages” property is a dictionary that you can use to get the names of the languages that Amazon Translate supports and the corresponding language codes. The example app uses this dictionary to populate the “Translate From” (SourcePopupMenu) and “Translate To” (TargetPopupMenu) popup menus.

The Translate method creates the payload that gets sent to the Amazon Translate API, and sets special HTTP headers that are needed in order to call the API. But most importantly, it uses the CURLSMBS class’s “SetupAWS” method to configure the CURL instance so that all of the steps that are required to “sign” the API request are done automatically. This is an amazingly convenient function of the MBS Xojo CURL Plugin. You can get a sense of what’s involved in signing the request here.

To translate text using the AWSTranslator class, you create an instance, configure it with your IAM credentials and AWS region, pass it the source language text, the source language code, and the target language code. In the example app, this all handled in the Window1.Translate method. The values are pulled from the App-level properties, as well as the various window controls. Finally, you call the AWSTranslator instance’s Translate method. If the translation is successful, the translated text will be available via the TranslatedText property. If any errors occur, the ErrorType and ErrorMessage properties will be set.

The “Estimated Translation Cost” is calculated whenever the Source Text changes. The value is calculated by taking the length (number of characters) of the Source Text and multiplying it by 0.000015 (the average cost for translating a single character).

Wrapping Up

I’ve been amazed at the speed and accuracy of the Amazon Translate service. And after developing the AWSTranslator class, I was able to quickly and easily add language translation to my client’s middleware app.

I hope you’re equally impressed by the Amazon Translate service, and that you find the AWSTranslator class to be helpful in your own Xojo projects.

Tim Dietrich is a custom software developer based in Richmond, Virginia. To learn more, visit: https://timdietrich.me

In this second post on the topic we will focus on the client side desktop app that will be in charge of creating the requests using the web service published API. This desktop app will send new data to our web server app so it can be added to the backend database.

The main topics are:

• Creating a subclass from the URLConnection class
• Dealing with the data received from the server as result for the request
• Encoding a JSONItem for sending data to the web service

As stated in the previous entry, the example doesn’t include the normal (and recommended) verifications on the data provided and received or the check on possible errors; we are only focused on the main topic.

Creating an URLConnection subclass

Let’s start by creating a new desktop project. Add a new Class using Insert > Class and use the Inspector to assign URLConnection as the Super Data Type as shown in the picture:

With the just added class still selected in the Navigator (the leftmost column in the IDE Window), add a new property to it (Insert > Property). We will use this property so it points to a DesktopListBox in our user interface, and so we can update it with the data received from our web service. With the just added property still selected, use the Inspector to set its Data Type and Name (text label used from our code to refer to such property) as follows:

• Name: List
• Type: DesktopListBox
• Scope: Private

Note that we set the scope as Private. This means that this property can be accessed only from the instances of the class, and not those that are created from other data types or even those created as subclasses from this class.

URLConnection: Asynchronous communications

Why would we want to maintain a reference to a ListBox control in our URLConnection class? As with any kind of problem, we can take several approaches in order to solve it. In this case, is a very convenient way to get a reference to the control we want to update as we will be using the URLConnection asynchronously.

Once we call the request against our web service, the execution of the app will not be paused until we receive a response, this allows the user to do other operations if they want. In this case the class instance, via the ContentReceived event, will be responsible to receive the new data from the web service, so we can use it.

In fact, this is our next step. With our URLConnection subclass still selected in the Navigator, add a new Event Handler to it (Insert > Event Handler…). In the resulting window, choose the PageReceived option from the list and confirm the selection, so the event will be added to the class under the Event Handlers section.

Now, with the just added Event Handler still selected, write the following snippet of code in the associated Code Editor:

#Pragma Unused url

If HTTPStatus = 200 Then // We received an OK as the status for our request
  If Content.Length <> 0 Then // And we have data to process as part of the reply
    List.RemoveAllRows // So we delete previous existing entries in the associated ListBox Control
    content = content.DefineEncoding(Encodings.UTF8) // We set the encoding for the received data
    
    Var items As Dictionary = ParseJSON(content) // And proceed to create a new dictionary from the received data in JSON format
    items = items.Value("AllAlbums") // We get all the items for the key 'AllAlbums'…
    For Each item As DictionaryEntry In items // …iterating on them…
      Dim tempDict As Dictionary = item.Value // …and retrieving the dictionary (JSON item) for it…
      Dim title As String = tempDict.Value("title") // …so we finally access the desired value
      list.AddRow title
    Next
  End If
End If

The code is commented so you can follow what happens in each line in the process; but it is worth it to point out that the ContentReceived event gives us all the parameters we need in order to work with the data sent from the web service:

• URL: The URL returned as the reply for our request
• HTTPStatus: The HTTP status code that you should read to verify the success of the request
• Content: This is a String that can contain the data associated with the reply.

In addition, you can also add an extra event handler to our subclass: Error. This will be fired when an error is produced while dealing with requests sent from the instance.

With the events and property already set, it is time to add a couple of methods in charge of commanding our URLConnection subclass to launch the requests. For our example, those method names are directly related to the operations we want to do on the web service API created on the first part of this tutorial.

So, with our URLConnection class still selected in the Navigator, add a new method (Insert > Method), using the following data in the associated Inspector. This is the method in charge of requesting our web service for the name of all the available albums. Of course, we expect to receive the reply through the ContentReceived event:

• Method Name: GetRequest
• Parameters: theList As DesktopListBox, theURL as String
• Scope: Public

As you can see, this method expects to receive the reference to a DesktopoListBox control, and the text to the URL that should be the end point of our web service. Now put the following code in the associated Code Editor for the just added Method:

List = theList
self.send("GET", theURL)

Simple, isn’t? As you can see, we save the reference to the DesktopListBox control in the instance property so we can use it later for updating its contents with the received data. Then we use the Send method from the class with the GET verb and the URL where our web service should be listening for incoming requests. As previously stated, this is an async operation, so we will let our object to react through the ContentReceived or Error events.

URLConnection: Sending data as part of a request

Add a new method to the subclass, using the following values in the resulting Inspector. This is the method allowing us to send data to the web service so they can be added to the backend database:

• Method Name: SendItem
• Parameters: Item As JSONItem, theURL As String
• Scope: Public

This time, the method expects to receive and JSONItem object (pointed via the variable Item) and a String instance that should be the web service endpoint URL. Put the following code in the associated Code Editor for the method:

Self.SetRequestContent( item.ToString, "application/json" )
self.Send("POST", theURL)

The URLConnection instances allow us to associate additional information (data) for a request sending, in addition to those added through the HTTP headers (Head), using for that the SetRequestContent method. This method expects two parameters: a String with the real data to attach, and the definition of the type of data we are sending (this is, the MIME Type) as a String instance.

Finally, we launch the request in the second line of code, using for that the URL assigned to the theURL parameter and using the verb POST.

Designing the User Interface

We have already finished all the logic behind our example app, via our URLConnection subclass. So now it’s time to design a minimal user interface so we can verify the correct functionality of our client agains the web service.

Select the Window1 object and add the required control so it looks like the one displayed here (from top to bottom): a DesktopListBox, a couple of DesktopTextFields in addition of two DesktopLabels, and two DesktopPushButtons named “Request” and “Send”.

Next, add an instance of the created URLConnection subclass. For that, simply drag the created subclass from the Project Browser to the Window Layout Editor and a new instance will be added to the Tray in the lower section of the Editor, as shown in the following picture:

The only code present in the user interface is the one that we will add to both PushButtons. Double click the one labeled “Request”, and add the following line of code to its Pressed Event Handler:

MyConnection1.getRequest(AlbumListbox, "http://127.0.0.1:8081/GetAll")

It calls the getRequest method on the instance based on our subclass, sending as parameters the control “ListBox1” and the text for the (local) URL where the web service should be listening.

Double click the PushButton labeled “Send” in order to add the Pressed Event Handler and write the following fragment of code into the associated Code Editor:

Var d As New Dictionary
d.Value("Title") = TitleField.Text
d.value("ArtistId") = ArtistIDField.Text
Var item As New JSONItem
item.Value("newAlbum") = d

MyConnection1.sendItem(item,"http://127.0.0.1:8081/AddAlbum")

As you can see, there is nothing magic in it. We simply create a new dictionary using the keys expected from our web server to access the underlaying data for the record. In addition, you can see how easy it is to create a new JSONItem from a Dictionary!

Then, we simply call the sendItem method on our URLConnection subclass instance, passing along the expected parameters: a JSONItem instance and the web service endpoint URL that should include the method we want to call in the remote API.

Ready to listen for your requests!

We have finished our client app! Launch the web service created in the first part of the tutorial (make sure it is listening using the port 8081). Then, run the desktop client app and push the buttons for “sending” or “requesting” the information. You will see how with the request you’ll receive all the albums available in the example database, while with the “Send” button you’ll be able to add new records to the database with the data provided in both TextFields.

In conclusion, Xojo allows us to create both the backend and the multiplatform clients in record time and in a really easy way! Obviously, the examples used in these two articles are not, by far, complete solutions you can use “As Is”, but they give the basics you can use to construct more robust and complete solutions for your own needs.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish

In this two part tutorial you will see how easy it is to create a basic web service using Xojo Web. In the second part, we will create a Desktop client to talk with the web service (you may want to add iOS to the list).

Before we start, let me point out that this tutorial leaves out some details related to error checking, validation, data sanitizing and other specifics related to inputs and outputs in order to focus on the central topic. In addition, if you want to follow and reproduce the steps of this tutorial, then you need to download the Chinook Database, named “test.sqlite” in this tutorial.

Services in practice

Let’s start creating a web service! Open the Xojo IDE, create a new Web project, and name it WebService. The first thing you’ll notice is that Xojo adds a web page to the project by default – even when our web service does not display a UI. The good part is that you can mix both worlds, adding the webservice part to your regular Web app!.

In fact this tutorial will put all the logic in the App object. Start by adding a new property in charge of the reference to our SQLite database (of course, it will work also with PostgreSQL or MySQL engines). Select the App object from the Navigator (the left panel in the Xojo IDE), choosing the Insert > Property option from the contextual menu. With the new property selected, go to the Inspector to set the name, type and scope using these values:

• Name: Database
• Type: SQLiteDatabase
• Scope: Private

Next, we will add the Chinook Database to the Resources folder of our Web App. For that, select the deployment target under Build Settings (it can be macOS, Windows, Linux or Xojo Cloud, for example), and add a Copy Files build step to it. In the resulting Editor, add the Chinook database SQLite file and make sure you select the “Resources Folder” entry in the Destination popup menu, and the “Both” entry in the Applies To popup menu.

Now is time to create a new SQLiteDatabase instance and assign it to this property, so it will point to the SQLite database file when the app is running. For that, make sure the App object is selected and add the Opening Event Handler to it using the Insert > Event option. Write the following code in the resulting Code Editor:

#Pragma Unused args

Var f As FolderItem = SpecialFolder.Resource("Chinook_Sqlite.sqlite")

If f.Exists Then
  
  Try
    database = New SQLiteDatabase
    database.DatabaseFile = f
    
    Call database.Connect
  Catch e As DatabaseException
    MessageBox "Error connecting to the database"
  End Try
  
End If

As you can see, it is pretty much the same code we already use when creating SQLiteDatabase instances in our Desktop apps, linking to our SQLite database file and stablishing the connection so we can operate with the database engine from our app.

All the Magic of HandleURL

Xojo Web projects offer a simple way to handle the request received. It is using the HandleURL event. This is the one that fires every time a client app (it may be a Web Browser, desktop or mobile app) connects to the URL associated with the IP address and port combination that is listening for incoming requests.

For example, a valid URL that can be trapped and processed by HandleURL is:

http://www.nice-web-domain.com/getCustomers

Where getCustomers is in this case one of our API methods.

So, with the App object selectd, choose Insert > Event in order to add the HandleURL event.

As we will see, once the event has been added to a web app, it will receive the Request parameter (a WebRequest data type), waiting from us to send back a Boolean value as response: True to process the request or False (the default value) to ignore the response.

Introducing Request, where the information lives!

In fact, we will find in the Request object everything we need to process and (if it is the case) respond to the request from our Web service. For example, through we can get the interesting component from the Path property. If we consider this URL:

http://www.nice-web-domain.com/getCustomers?spain

The Request.Path property will return the getCustomers string; so our web service can process it acordingly from this point on.

Receiving and Sending JSON data

In order to keep this tutorial brief, our web API only has two methods in it: GetAll and AddAlbum. Using the first one, the client app will get the album name in the database wrapped in JSON format. With the second method, our client app will ask the web service to add a new record (a new album) to the right table on our example database.

How can we process the request associated data inside the HandleURL event? Here is where we will find very useful another of the Request object properties. The Body property includes the sent data as part of the request that are not already present in the headers. Generally speaking, it includes additional data via the PUT and POST verbs.

Now we can put the following code into our HandleURL Event Handler:

Select Case Request.Path // What is the method received as part of the request? (URL)
Case "GetAll"
  Var output As JSONItem = GetAllAlbums // Assign the processed data to the output variable, if the received method is 'GetAllAlbums'
  
  Response.Header("charset") = "utf-8"
  Response.MIMEType = "application/json"
  Response.Status = 200
  response.write( output.ToString ) // And send it back to the client that made the request, converting the JSON to a String in first place
  
Case "AddAlbum"
  Var data As String = Request.Body.DefineEncoding(encodings.UTF8) // We have to apply the right encoding to the received data
  Var Input As JSONItem = New JSONItem( data ) // Creating a new JSON object from it
  addNewAlbum( Input.Value("newAlbum") ) // In this case, the request is to add a new Album to the database; passing thus the received data as part of the input
End Select

Return True

The main point here is that we assign the received data to the data variable (if any), and define a known encoding to them so we won’t get into trouble while processing them afterwards. Of course, our example always expects to receive the additional data in JSON format, so this is why we create a new JSON instance from this data.

We use the Select…Case command to decide what method has to execute the web service, and that is based on the component stored in the Path property as you recall. So, if the request uses the GetAll method in the URL, we will call the real method GetAllAlbums in our Xojo code. After processing the information it will return a new JSONItem as the response we will send to the client.

How can we send the response to the request? Really simple: calling the Write method on the Response object, passing as parameter the text we want to send back. In our example, this is the JSONItem referenced by the Output variable. We also use the Response object to set the character encoding to UTF-8 and the MIME type to “Application/json”, in addition of setting the status value to 200 (that is, the request has been successfully handled).

If we receive a request with the AddAlbum method of our API, then we call the real addNewAlbum method in our Xojo code, passing as parameter the JSONItem object in charge of store the received data from the request (this is the one referenced by the input variable). In fact, the record structure is stored inside the newAlbum root node of the JSONItem.

When it comes to the Database

While HandleURL is in charge of processing the received request, we will use a couple of methods in our example app that will act as a link between the API and the database in the backend, both for retrieving and storing the requested information. (In a real world app it is very advisable to introduce checks and data sanitization before dealing with the database!)

Choose the App object again and use the Insert > Method option in order to add the GetAllAlbums method, using the following method signature for that:

• • Method Name: getAllAlbums
  • Return Type: JSONItem
  • Scope: Private

This is the code in charge of generating the JSONitem that we will write as part of the request response, including the node for every expected database record from the Album table in our example database:

Var rc As RowSet = database.SelectSQL("Select * from album order by title asc") // Get the Recordset as result of the SQL selection: all the records
Var item As New JSONItem

If rc.RowCount > 0 Then // We have records on the RecordSet
  
  While Not rc.AfterLastRow // so lets iterate them!
    Var d As New Dictionary // creating a new dictionary for each record, and that we will convert in a node
    d.Value("artistid") = rc.Column("artistid").StringValue // assingning the record ID to the name 'ArtistId' of the JSONItem
    d.Value("title") = rc.Column("title").StringValue // and the Title value to the 'Title' field of the JSONItem
    item.Value(rc.Column("albumid").StringValue) = d // You know you can assign a Dictionary as the value for a JSONItem node. Very useful!
    
    rc.MoveToNextRow
  Wend
  
  rc.Close
  
End If

var output As New JSONItem

output.Value("AllAlbums") = item // Then let's hang all these records form a main Node

Return output // And return it to the caller

Next, create a new method named addNewAlbum. This is the one our web service will use to add a new record to the database, using for that the received data as part of the request. Use the following signature for the method definition:

• • • Method Name: addNewAlbum
    • Paramters: item as JSONItem
    • Scope: Private

And put the following code in the associated Code Editor:

Var title As String = item.Value("Title") // get the data associated to the "Title" field
Var artistid As String = item.Value("ArtistId") // and the 'ArtistID'

database.ExecuteSQL("insert into album(title,artistid) values(?, ?)", title, artistid ) // and insert that data as a new record into the database table

As you can see, the code is very simple: it gets the values for the received keys in the JSONitem nodes and uses them as part of the SQL sentence in order to add a new record to the database.

A Web service… ready to serve!

As you have seen, the code and app structure are really minimal! Of course, this is just a simple example but it gives you a good idea of the kind of possibilities web services offer and how fast you can put it together using Xojo and OOP concepts you already know! Of course, you can run your web app (and services) right from the IDE (just make sure to select 8081 as the Debug Port)… what is probably the recommended way to follow this simple example. For other more complex web apps, remember that you can use the one click solution Xojo Cloud and of course any compatible Linux, Windows or Mac server.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish