One of the things we live at EclipseSource is efficiency. This is true for IDE usage, code and development lifecycles. This is why we made the Tabris.js development lifecycle as fast as possible with the Tabris.js 0.9.3 release. The mission for this release was that we wanted to enable you to:
Today we can proudly say: “Mission accomplished!“. In this post we will show you how to get started with Tabris.js, how to create your first app, how to build your first app and how to integrate your own set of Apache Cordova plugins. So, let’s get our hands dirty.
What you need to follow this tutorial is…
- a mobile device like a smartphone (iOS or Android),
- a GitHub account
- a text editor
- a npm installation
To see your first app and hack around you only need two things. First you need to sign in to tabrisjs.com using your GitHub account. Right after the signin you will see your personal “Scratchpad” – an online editor containing your first executable Tabris.js app.
When you start the app you can also sign in to tabrisjs.com right within the app. After doing so you will see an entry in the “My Scripts” tab called “My Scratchpad”. Clicking on this entry will launch your Scratchpad. This is it, your first app is running! Go ahead an change some code in your Scratchpad within your browser (it saves automatically). To see your changes on the device the only thing you need to do is to swipe from the right border of the Tabris.js app to the left. You will see a “reload” button on the top right and press it! Done? Awesome… So, what happens in the background and how does this work?
The Scratchpad is cool to see your first small app, but how do you develop a bigger and more advanced app?
Your own project
What the Scratchpad does can also be done easily on your local computer. Just create a folder called
my-tabrisjs-app with two files:
- The app itself comes first. Create a file called
app.jswith the following content:
- Describe the app with a
package.jsonfile. Tabris.js is fully compatible with npm and thus every app needs to describe itself in a
my-tabrisjs-app folder and execute
npm install. After this has finished you just need to make the
my-tabrisjs-app folder available via HTTP. You can use an Apache Web-Server, Jetty or (our preferred) npm http-server. Simply install the http-server executing
npm install http-server and execute
http-server afterwards. This makes the current folder available via HTTP on port 8080.
After the server is up and running you can open the Tabris.js app on your mobile device and select the “URL” tab. Just enter the IP of your computer with port 8080 e.g. http://192.168.1.1:8080. Congrats, your app is up and running :).
You may think: “This is nice, but I also want to see my own app ID, logos and use own plugins in the app”. That’s not a problem at all and you can go even further! Tabris.js has full support for Apache Cordova Plugins. So, instead of developing new features on your own, you may want to use one of hundreds of freely available Cordova Plugins. And the coolest thing is, you can achieve all this without the need to use your own hardware (and no, you don’t even need a Mac to build your iOS app).
Build your app
You may have already spotted it after you signed in to tabrisjs.com. Not far from the “My Scratchpad” menu entry is an entry called “My Apps”. Under “My Apps” you can build your Tabris.js apps. To build our app we need to do two things.
First we need to change the project structure. As mentioned before, Tabris.js has full support for Apache Cordova Plugins. This support goes even further. Tabris.js apps can be build using the Cordova CLI which also means you can script all kinds of Cordova build hooks. Anyway, to be able to build an app on tabrisjs.com the project needs to have a Cordova project structure. Basically this means two things:
package.jsonneed to be in a folder called
www. So, create the
wwwfolder in your
my-tabrisjs-appfolder and move all files created so far into this folder.
- You need to create a
config.xmlfile that describes the app. You may think: “Another app description, wtf?”. But hold on, the
config.xmldescribes the native artifacts that will be built (.ipa/.apk) while the
config.xmlfile in the
my-tabrisjs-appfolder right beside the
wwwfolder with the following content:
<pre lang="xml"> <?xml version='1.0' encoding='utf-8'?> <widget id="my.first.app" version="1.0.0" xmlns:gap="http://phonegap.com/ns/1.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0"> <name>My App</name> <description> My first Tabris.js app </description> <author email="email@example.com" href="http://www.me.me"> Me </author> <access origin="*" /> <preference name="EnableDeveloperConsole" value="true"/> </widget> </pre>
Second, we need to make this app available on GitHub to be able to activate it on tabrisjs.com. Go ahead and create a GitHub repository called
my-tabrisjs-app and push all files to this repository (for the experienced JS developers: yes, you can
node_modules folder). After you have pushed it, go to “My Apps” on tabrisjs.com and press “Create App”. Now you can select your
my-tabrisjs-app repository in the list of repositories (if it’s not visible you may need to press the “synchronize” button).
After you have selected your repository it’s going to be validated. The validation checks if the selected repository contains a valid Tabris.js app. If you have done all steps as described before, your app should become valid shortly. If it’s invalid, the site will tell you what went wrong. In this case please follow the instructions displayed or double check the previous steps.
After your app has become valid, you are ready to execute your first build. Just select the newly created app and click the “Start Build” button. A few minutes later you will get an Android .apk file which is ready to be installed on your device. Yay! But what about iOS? What about production builds? And what about signing?
To answer these questions we need to take a look at the settings of your app. Let us take a detailed look on every option.
- Repository URL: This is the URL pointing to your repository. In your case it should point to the
my-tabrisjs-appGitHub repository. Users who are on the Developer plan can also use private GitHub repositories and custom repository locations.
- SSH Private Key: The SSH private key to use when cloning your repository. Only relevant if you have the developer plan and using a custom git repository URL.
- Branch: The git branch to build from. The default value of this is
master. But sometimes you may also want to build a feature branch or something similar. So, go ahead and configure it here.
- iOS Signing Key: iOS apps can not be deployed to a mobile device without being signed. If you want to build an iOS app you need an Apple Developer account and provide the certificate together with the provisioning profile. A very good tutorial how to get these files can be found in the Phonegap Build documentation.
- Android Signing Key: Android apps needs to be signed with a certificate only if you want to deploy them to Google Play. If this is the case you can find a very good tutorial in the Phonegap Build documentation as well.
- Tabris.js Version: This is the Tabris.js version the app should use. In your
- Debug: The debug flag tells the build service which “version” of the app should be built. Debug
ONmeans your app will be built including debug symbols and it will be packaged into the Tabris.js app you have used before. This allows you to use all the benefits like the fast development lifecycle also with your own app. Please be aware that debug versions can not be submitted to the app stores. Debug
Add Cordova Plugins
To add any set of Apache Cordova Plugins the only thing you need to do is to change the
config.xml. We support the
tag as you might know it from Phonegap Build. This means you can add the plugins using an ID, HTTP or git URL. A sample
config.xml including two Cordova plugins can look like this:
<pre lang="xml"> <?xml version='1.0' encoding='utf-8'?> <widget id="my.first.app" version="1.0.0" xmlns:gap="http://phonegap.com/ns/1.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0"> ... <gap:plugin name="org.apache.cordova.camera" /> <gap:plugin name="org.apache.cordova.dialogs" /> </widget> </pre>
Please Note: If not already included like in the examples above, you also need to add the gap XML namespace in the root element of your
To see how to brand your app checkout our blog tomorrow. If you want to know more about Tabris.js checkout the documentation, snippets and examples. Please feel free to leave a comment or any kind of feedback.