How does OutSystems support mobile development?
You’ve browsed Cordova’s 2,880 plugins and you couldn’t quite find the one that you were looking for. You’ve scratched your head, you’ve scratched your chin, and you’ve even scratched your back only to learn that no amount of scratching will help you acquire the native functionality you’re looking for. You have to build the plugin from… scratch.
In this tutorial, we’ll show you how to do that step-by-step. You’ll go from nothing to a fully-integrated Cordova plugin that you can use in your mobile projects built with low-code - in this case, with the OutSystems platform.
- Native Android development
- Android SDK
- Apache Cordova
- OutSystems IDE
Because it’s not possible to personalize blog articles (yet), this tutorial will go through the steps for building and integrating a plugin that already exists. It’s an Android Cordova plugin that grants your application the ability to display Android’s Toasts. Toasts are the text messages that pop up at the bottom of the screen and then disappear. This plugin will repeat some of the work done by Eddy Verbruggen and Nuno Lopes — you can find the existing Toast plugin in the OutSystems Forge.
1. Create a CordovaTest Project
$ cordova create toasty-plugin-test com.stanleyidesis.toastyplugintest ToastyPluginTest
(Change the package name, if you like. Or boost my ego by giving me all the credit!)
$ cd toasty-plugin-test $ cordova platforms add android
$ cordova requirements
During my attempt, my path variable was missing the location of javac and I hadn’t installed the latest Android SDK platform: 26. I added Android Studio’s built-in JRE to my PATH variable and installed version 26 of the Android SDK using the SDK manager. Downloading required SDKs and system images can take a little while, so return to this tutorial after they’ve installed, and you’ll be ready for step 2.
2. Test Your Empty Cordova Project
To guarantee that you’ve set up your project and dependencies properly, let’s run your empty project in an Android emulator. Before proceeding, verify that you have an AVD (Android Virtual Device) installed and running. If you’ve never created an AVD before, follow this handy guide from Google, Create and Manage Virtual Devices. I used a Pixel with API version 25 as my base device configuration and left the remaining parameters untouched — you can do the same.
Tip: install Intel HAXM through the Android SDK manager to guarantee best performance during X86 emulation.
# Run all commands in your toasty-plugin-test project directory $ cordova build android
$ cordova emulate android
If you accidentally closed your emulator, don’t worry; Cordova will use the Android SDK’s command-line tools to start up a new one. After a bit of patience, you should see the following screen:
Now you can continue to the next step.
3. Create a Plugin Project
Note: Replace the repository URL, author, bugs URL, and homepage URL values with your own.
In this step, you’ve created a lot of placeholders for files that don’t yet exist, so let’s make them in the next one.
The original Toast plugin by Eddy Verbruggen adds a bit more functionality and supports custom positioning, but your plugin is going to remain simple by sticking to native Toast functionality found exclusively on the Android platform. In this case, you will support the show function that is capable of displaying a message for a period of time (either long or short). The cordova.exec function is what sends this simple command to the native platform code that you will create in the next step.
5. Implement ToastyPlugin for Android
You’ve constructed a simple API that will allow your Cordova project to tap into your native Toast functionality, but now you actually need to implement that native code. There’s a lot to know about Android, iOS, and the other native platforms, but I’m going to assume that you know enough to venture down this rabbit hole of custom plugin development. So you won’t find any elaborate detail about how Android works in this post. However, if you’re interested in learning more, I recommend Udacity’s Android Nanodegree program.
$ mkdir src $ cd src $ mkdir android $ cd android $ touch ToastyPlugin.java
Note: Again, make sure to use the package name you identified in plugin.xml.
If you’re unfamiliar with Android development, that’s okay. Most of the code is Cordova and JSON-focused. The only Android particulars we have here can be found between lines 40 and 43. The Toast API documentation explains the makeText and show methods, however, both of which are mostly self-explanatory. Ideally, if you’re building a native plugin, you’re familiar with Android (or you soon will be) and won’t require hand-holding to accomplish your task—just a little bit of help setting up!
6. Taste the Toast
$ cd toasty-plugin-test
$ cordova plugin add ..\toastyplugin\
$ cordova emulate android
Your next step is to commit and push changes made to your plugin repository. Make sure the version found on the master branch is identical to the version you tested.
7. Clone Template Plugin
This template OutSystems plugin will incorporate the Cordova plugin found at the provided repository address. However, OutSystems offers two additional ways to include a plugin: as a resource or by its unique npm identifier. For the purpose of this tutorial, I’m going to assume you have access to Github or similar and feel free to create temporary public repositories for test purposes.
Note: If you ultimately plan to build private plugins strictly for company use, I recommend including the plugin as a bundled resource.
8. Modify the Template Plugin
You still need to make plenty of modifications to the template before you can use it as an actual dependency. First, let’s delete stuff. Under the Interface tab, delete the Template_Plugin_Flow web block and delete the Template_Plugin script. These elements enable you to attach per-screen listeners to callbacks that bubble up from the plugin. We won’t need this capability to show Toasts.
This checks for both window.plugins and then verifies the presence of the toastyPlugin object. Assuming both are present, ToastyPlugin is ready to fire off Android Toasts. But first, you need to modify the generic plugin action to allow plugin users to show a Toast through an OutSystems action. First, create a static Entity that plugin users will pass as a duration, name it ToastDuration, and make the entity public. Then create two records under the static entity, one named Long and the other Short.
Pop back into the Logic tab and rename Template_PluginAction to ShowToast. This is the action plugin users will invoke to trigger a Toast message. Add two input parameters to the action: Message and Duration where Message is a text and Duration is a ToastDuration identifier type. Then add a local parameter named DurationText. You will pass DurationText as an argument into the TemplateJSAction script found inside ShowToast.
The last line invokes your plugin by passing the message, duration, success, and the failure callback to ToastyPlugin’s show() function. With the plugin template prepared, go ahead and publish to your OutSystems cloud.
9. Test It Out
This action checks for the availability of ToastyPlugin. It presents an error message if the plugin is inaccessible, but otherwise invokes the ShowToast action with a Long duration and a message that reads, “Mmm, toasty!” How you incorporate the plugin is up to you, but you can easily follow my example by creating a new mobile module, adding a single icon to the menu bar, creating an OnClick action, and repeating the logic I’ve concocted. After you’re done, publish your changes.
10. In Conclusion
Creating custom mobile functionality is not entirely straightforward, but once understood, becomes rather accessible to OutSystems developers. You can repeat this process for iOS plugins as well and even those that support multiple platforms. If you only want to gain access to an existing Cordova plugin that you can’t find in the Forge, skip to step 7. From step 7, you will build the interface that connects your OS project to the plugin’s unique requirements—and that’s all there is to it.
Thank you for following along with this tutorial and please feel free to leave feedback by dropping us a note on Twitter!
Stanley Idesis, a perennial American sweetheart, was on the direct path to become a mild-mannered power plant employee when he was bit by a radioactive programming spider! Overnight (and 6 years later), he's worked on dozens of native mobile applications. He applied those skills to mentoring students and writing courses for ed-tech.That was great and all, but then that blasted bug bit him again! Now he helps software organizations reach their developer audiences.See All Posts From this author