Nobody Puts Filtermama in a Corner

How hybrid apps work

Built for BlackBerry

Conception

Capturing an image

Once the file is picked and cropped, it’s prepared to be added to the app. This is where the web layer comes in to play. To prepare the photo, Canvas is used. The photo is resized, and added to the html document.

This is where the magic first happens. To talk to the web layer from Cascades we use the postMessage function.

// file: Filtering.qml  
   var msg = {     
      'cmd': 'loadPhoto',     
      'data': imgData 
   };  

   var message = JSON.stringify(msg); webview.postMessage(message); 

Web Side

In the webview, Filtermama is listening for commands from Cascades via navigator.cascades.onmessage.

// file: index.js  
navigator.cascades.onmessage = function onmessage(message) {     
   message = JSON.parse(message);      
   // load photo     
   if (message.cmd === 'loadPhoto') {         
      thePhoto.src = message.data;         
      prepareImage();     
   } 
}; 

This back-and-forth communication is the core of how the hybrid app works. Again, check out Anzor’s hybrid app blog series if I’ve lost you.

One of the biggest factors for handling the filtering in web is that Canvas is absolutely awesome to work with. There are many libraries out there to do this exact thing, and I’ve tested out most of them.

For Filtermama, I decided to go with Filter.me by Matthey Ruddy. It’s dual licensed under the MIT and GPL licenses, coded cleanly, and is optimized for performance.

Native side

To apply a filter we simply post a message to the webview that contains the filter’s settings. These settings all originate from a JSON fileassets/filters/filters.json.

// file: Filtering.qml  
var msg = {     
   'cmd': 'filter',     
   'data': filterData 
};  
var message = JSON.stringify(msg); webview.postMessage(message); 

Web side

In the webview the filter data is parsed, and passed to Filter.me, which performs all the hard work for us.

Here’s a sample of what an actual filter object looks like, from the filters.json file.

// file: filters.json 
{
   "id": "1980",     
   "type": "default",     
   "title": "1980",     
   "thumbnail": "filters/1980.png",     
   "filter": {         
      "curves": {             
         "a": "[alpha channel values]",             
         "r": "[red channel values]",             
         "g": "[gren channel values]",             
         "b": "[blue channel values]"         
      },         
      "desaturate": false,         
      "vignette": false     
   } 
} 

The actual call to the Filter.me library is super easy because it is making use of jQuery (shh, don’t hate). As you can see, an effect object (which contains the JSON data) called filter is passed to Filter.me, and the rest is handled by the library.

// file: index.js  
var process = function(effect) { 
   filterId = effect.id;  
   jQuery(document).ready(function($) {     
      $('#the-photo').filterMe(         
         filter     
      ); 
   });
} 

Native side

Once Filter.me is finished, a message is posted back to the native layer and received by the webview’s onMessageReceived listener, which in this case, tells Cascades to turn off the activity spinner and give focus back to the user.

// file: Filtering.qml  
onMessageReceived: {     
   if (data.message === 'filter-done') {         
      spinner.off();     
   } 
} 

Photo sharing and saving is handled by the native layer, but remember we’re filtering the image in the web layer so we need to get the Base64 data from the canvas into Cascades and C++. Since Filter.me is replacing the image source with a Base64 string, we simply grab that data, and post it to Cascades.

Web side

var savePhoto = function() {     
   var b64 = thePhoto.src;     
   navigator.cascades.postMessage(b64); 
}; 

Native side

Once Cascades receives the message, again via the onMessageReceived handler, it passes the Base64 string to C++ via app.savePhoto() which saves it.

data = data.replace('data:image/png;base64,', ''); 
savedFilePath = app.savePhoto(data); 

Now that the file is saved, and we have the savedFilePath, we detect if the user wants to share or just save the photo.

If they choose to save, a toast is displayed telling the user the photo is saved.

If the user wants to share the photo, we use the Invocation Framework to do so by passing it to the savedFilePath. A Share Card is displayed, and the user can now choose where they want their photo posted.

I used the Social Invocation sample app to add this functionality to the app. Below is a snippet from the shareFile() method.

C++

void ApplicationUI::shareFile(QString fileName) {   
   invocation = Invocation::create(   
      InvokeQuery::create().parent(this).uri(    
      QUrl::fromLocalFile(fileName)));   
      connect(invocation, SIGNAL(armed()), this, SLOT(onArmed()));            
      connect(invocation, SIGNAL(finished()), invocation, SLOT(deleteLater()));   
} 

Filtermama has been open-sourced as “Filtermama Lite” under the Apache 2.0 license. Feel free to modify, and adapt it to meet your needs.

If you find it useful in any way, please show your support by following me on Twitter, and letting me know!

Check-out the latest version of Filtermama Lite on GitHub.

• Filtermama in BlackBerry World
• Hybrid Apps for BlackBerry 10 by Anzor Bashkhaz
• Built for BlackBerry Boilerplate for BlackBerry 10.1
• Filter.me by Matthey Ruddy