This post was originally published at Tutorial: Integrating Swift and CoronaCards

For those who are not familiar with CoronaCards, it allows you to include Corona-based projects within existing native apps. In contrast to Corona Enterprise, CoronaCards does not own the entire application stack. Instead, it works similarly to embedding a WebView in an app, but instead of JavaScript/HTML, the CoronaCards view — usually referred to as the “CoronaView” — talks to Lua code. We won’t discuss everything that CoronaCards can do within this tutorial, so please visit the CoronaCards website to learn about the product and its capabilities.

Installing CoronaCards for iOS

Since this tutorial deals specifically with integrating Swift with CoronaCards, and Swift is an iOS and OS X programming language, we’ll focus on the iOS side of CoronaCards. The base system requirements include an Apple Mac running OS X 10.9 or above and Xcode 6.1 or later. New users can download a 30-day trial license, and current CoronaCards subscribers can download the latest build from the Daily Builds download page.

To install CoronaCards, please refer to the CoronaCards installation page.

Downloading a License File

CoronaCards expects to find a license file in the project folder alongside main.lua. Once you’ve downloaded the CoronaCards framework, follow the instructions on the installation page to obtain your license file. This file will be named license.ccdata.

Introducing CoronaCards Templates for iOS

Native development can be challenging and setting up CoronaCards within Xcode requires several steps. To help expedite this process, Corona Labs recently introduced some new templates which will create a new Xcode project that handles all of these steps for you. Note that these templates are intended for new projects — if you already have a native project underway, you should follow the steps in the CoronaCards setup guide instead of using a template.

Using a Template

If you opt to use a template, please download the entire ZIP file from the CoronaCards GitHub repository. Once downloaded and unzipped, you’ll need to copy the entire CoronaCards Apps folder to:

~/Library/Developer/Xcode/Templates

If this is your first foray into native development, you will probably need to create the Templates folder. Once the CoronaCards Apps folder is copied over, peek inside and notice that it contains these two folders:

  • Child CoronaView Application.xctemplate
  • Single CoronaView Application.xctemplate

Creating a New Project

Now, start (or restart) Xcode. Once it’s loaded, select FileNewProject…. You will be presented with a dialog box where it lists the various types of iOS projects which you can build.

Screen Shot 2014-12-07 at 5.48.16 PM

Choose CoronaCards Apps from the left sidebar and then choose the project type:

  • Child CoronaView — This option allows the CoronaView be a child of the native ViewController. An example of this is a complex native UI where you only need a portion of the screen to contain your interactive (Corona) content.
  • Single CoronaView — Apps built using this option are apps where the CoronaView portion takes up the entire screen and is the main ViewController for the app.

Once you’ve selected the desired project type, click Next.

On the next screen, you must provide a product name, define your organization name and identifier, and choose if this will be a Swift-based project or an Objective-C project. As always, it’s best to avoid spaces in the product name.

Screen Shot 2014-12-07 at 5.53.50 PM

Once you have this information filled in, press Next. At this point, you will have an opportunity to choose the folder where you want the project to reside. Do so and click the Create button to create the project.

Copying Over the License File

As mentioned earlier, CoronaCards expects to find the license file in the same folder as main.lua. Locate and open the new project folder that you just created, open the Corona folder within it, and copy your license.ccdata file into the folder alongside main.lua (this is where the licensing server will look for it).

Compiling and Testing the Project

At this point, you can press the Xcode Play button to compile and launch your app:

Screen Shot 2014-12-07 at 6.02.17 PM

In addition, to the right of this button, you can choose one of the Xcode iOS simulators or an actual iOS device if you have one tethered to the computer. During this process, there should not be any errors, and Xcode will copy the Corona folder from your project folder and start running your CoronaCards-based app. Of course, it doesn’t do much yet in regards to communication with Swift, but we’ll discuss that shortly.

Additional Notes

Before proceeding to the Swift sections, there are some important points to note:

  • The Xcode “Navigator” column doesn’t necessarily represent the actual physical file structure for the project — it’s primarily an organizational view in which you can add or remove item references without impacting the actual file system. This is essential to understand, because when you add new files (images, Lua files, etc.) to the project’s Corona folder, they won’t automatically be added to the Navigator view in Xcode. However, Xcode will copy/use these files during the compilation process.
  • If you want new files to be represented in the Navigator view, you must add them by either dragging them from the Finder to the proper place in the Navigator view, or by right clicking in the Navigator view and selecting the Add Files to “[Project]”… option. You’ll probably want to do this for any new Lua files so you can easily view their content within Xcode.
  • CoronaCards uses a config.lua file but not a build.settings file. Anything that would be part of build.settings in a typical Corona SDK project should be added directly to the project’s Info.plist entry in Xcode.

Communicating From Swift to Lua

Communication between Swift and Lua happens via event handlers. When sending events from Swift to Lua, you can define a Swift Dictionary containing the information that you want to send to Lua and then call the CoronaView’s .sendEvent() method:

In this case, the Dictionary is called event and has key-value pairs as strings. Corona events expect a name member which is simply the name of the event — in this example we use "nativeMessage". The other key-value pairs are relevant to the data being sent to Lua. In this example, we define a "phase" and a "message" key-value pair. Following this, we call coronaView.sendEvent() and pass in the Dictionary.

Now, on the Lua side, you can listen for the event and perform an action:

Since we told Swift that the "name" of our event is called "nativeMessage", we need to add a Runtime listener in Lua which listens for that specific named event. When it’s received, it calls the defined handler function ("handleNativeMessage"). At the same time, the Dictionary that you created in Swift is converted to a Lua table and passed to the handler function. Above, we simply check to see if the event "phase" is "loaded" and then update the text object to the event value of "message".

Communicating From Lua to Swift

Going in reverse from Lua to Swift, the process is basically the same — we just create an event in Lua and it gets picked up by the Swift receiveEvent method. Let’s look at the Lua code first:

The above code creates a text object and adds a basic tap event listener to it. Inside the tap event function (handleTap), a Lua table is created with two key-value pairs. The name key is set to "coronaView" and the message key is set to some message which we want to send to Swift. Naturally, more key-value pairs can be included to suit your needs. Following this, the table is dispatched to Swift via the Runtime:dispatchEvent() API call.

Now, on the Swift side, we need to make sure that the ViewController knows to use the CoronaCards delegate to process the event. The code should look something like this:

On the class definition, we add the CoronaViewDelegate. Several lines down, we assign self to the view’s .coronaViewDelegate. Next, we add a function to the view which handles the receiveEvent call —  this takes a required NSDictionary object that returns AnyObject. Then, inside this function, we process the received event Dictionary.

Conclusion

This tutorial should get you started in the world of Swift programming while utilizing all the power and ease of coding with Corona. Furthermore, this illustrates how to take advantage of Swift and Obj-C interoperability, and for the more adventurous developers out there, you can even use Swift with Corona Enterprise via similar techniques.

Continued here: 

This post was originally published at Tutorial: Integrating Swift and CoronaCards