Écriture/lecture/modification de fichiers dans un projet Universel app/UWP et cordova

Dans nos applications, nous avons pris le parti d’écrire nos fichiers en JSON. Nous avons donc conçu une abstraction (en WinJS, avec un système de promises) qui nous permet d’utiliser des méthodes claires et simples sur toutes les plateformes (WinRT/UWP ou Cordova (iOS/Android) )

Ce module « DataContainer » est disponible dans notre libraire WinJSContrib (Github)

Dans WinJSContrib.DataContainer, nous avons 4 fichiers qui exposent les mêmes méthodes avec des implémentations différentes :

  • read : lecture d’un élément
  • save : enregistrement d’un élément
  • remove : suppression d’un élément
  • list : liste des fichiers d’un container
  • child : création/accès container enfant

Dans une application WinRT/UWP nous allons naturellement utiliser la couche WinRT/UWP pour écrire/lire les fichiers. Pour cela il suffit d’inclure le fichier « winjscontrib.datacontainer.winrt.file.js »

Dans une application cordova IOS ou Android, nous avons plusieurs choix :

  • Utiliser une base de données : winjscontrib.datacontainer.cordova.database.js
  • Utiliser le système de fichiers avec le plugin file : « winjscontrib.datacontainer.cordova.file.js »
  • Utiliser le localStorage : « winjscontrib.datacontainer.localstorage.js » (utilisable en WinRT aussi)

Ensuite, il faut instancier un container parent et l’utiliser partout dans l’application.

Dans le JS des applications Windows 8/Phone il suffit d’instancier le container (dossier) parent :

MyApp.Data.container = new WinJSContrib.DataContainer.WinRTFilesContainer(undefined, { logger: WinJSContrib.Logger });

Et changer WinRTFilesContainer par notre choix (CordovaDatabaseContainer par exemple) pour l’application cordova en faisant attention de ne l’appeler qu’après l’enclenchement de l’évènement deviceready.

Et c’est tout, la magie s’opère à l’intérieur de notre librairie 🙂

Quelques exemples d’utilisation :

  • Pour lire un fichier :
  • Data.container.read("objKey").then(function (data) { }, function (error) { });
    
  • Supprimer un fichier :
  • Data.container.remove("objKey").then(function () { }, function (error) { });
    
  • Enregistrer un fichier :
  • Data.container.save("objKey",obj).then(function () { }, function (error) { });
    
  • Accès à un container enfant (sous dossier) avec la lecture d’un fichier fichier :
  • Data.container.child(folderid).read("subObjKey").then( function (subObjInFolderID) { }, function (error) { }));
    
  • Liste des fichiers dans un container :
  • Data.container.list().then(function (res) {}, function (error) { });
    

Débuguer une Universal Windows app et d’une application Cordova dans Visual Studio

Petit rappel : Vu l’architecture du projet (Applications natives en Universal App + application cordova) il faut bien penser à ajouter les fichiers copiés depuis le shared project en as link dans l’application cordova. C’est le seule moyen de débuguer/modifier le bon fichier.

 

Dans les applications universelles aucune configuration spéciale n’est nécessaire, Visual Studio gère parfaitement le debug. Il suffit de lancer l’application en mode debug et avoir accès dès le lancement au dom ainsi qu’aux points d’arrêts. Les choses se compliquent légèrement avec les applications cordova. En effet Visual studio met plusieurs secondes (voir minutes) avant d’attacher correctement et d’une façon stable le debugger. Et si on souhaite débuguer les premières lignes qui s’exécutent lors du lancement de l’application, cela devient rapidement compliqué, voir impossible.

Deux solutions existent :

  • La première (mais qui ne marche que si l’application s’initialise correctement = pas de crash au démarrage) c’est simplement via la console JavaScript de Visual Studio d’appeler la méthode window.location.reload() la page index.html est rechargée = les scripts se ré exécutent et on a donc accès aux debug des premières lignes de code.
  • La deuxième c’est de créer un mode debug avec une étape intermédiaire qui consistera à avoir un fichier index.html qui charge le stricte minimum de fichiers qui contient un lien (button) qui va nous permettre de naviguer vers une deuxième page qui va charger le reste des fichiers. Avec cette formule on s’assure du démarrage de l’application, on peut attendre que le debugger Visual Studio soit correctement attaché pour pourvoir charger les autres fichiers.

 

Le débogage/déploiement sous iOS requière un mac et l’installation des outils de build:

  • (Mac) Depuis le terminal lancer la commande désinstallation: sudo npm install -g vs-mda-remote –user=$USER ($user = l’utilisateur courant)
  • (Mac) Après l’installation lancer la commande: vs-mda-remote –secure false
  • Configurer Visual Sutdio: Tools => Options => Tools for Apache Cordova => remote Agent configuration:
    • Enable remote iOS processing = True
    • Host : adresse ip du mac de build.

Le déploiement peut se faire avec le simulateur ou un device.

Avec ces quelques notes vous avez maintenant les outils pour pourvoir débugger facilement votre nouvelle application.

Universal Windows app et Cordova avec WinJS

L’architecture que je conseil pour cibler les trois (quatres) plateformes, c’est de partir principalement d’un projet natif Universal app (Windows 8.1/ Windows Phone) en HTML5 et de créer un projet Cordova à l’aide du plugin Visual studio.

Ensuite pour brancher l’application Cordova avec le projet shared, il faut écrire un script (robocopy) à exécuter avant le build pour copier les fichiers du projet shared vers le projet cordova:

(robocopy ..\UniversalApp.Shared\ . /E /XF UniversalApp.Shared.*)^& IF %ERRORLEVEL% LEQ 1 exit 0

Et modifier le fichier de projet (jsproj) pour lancer cette exécution:

<Target Name= »BeforeBuild »>
<Message Text= »### BeforeBuild ### » Importance= »high » />
<Exec Command= »prebuild.bat » />
</Target>

Mais pour pouvoir débugguer les fichiers copiers, il faut aussi créer la structure des dossiers et ajouter les fichiers en as link.

Pour ajouter WinJS à vos projets vous pouvez passer par nuget (qui ne marche pas avec les projets shared pour le moment) ou récupérer directement la dernière version stable disponible depuis le repo github. Vous pourrez ensuite ajouter les fichiers WinJS.js, css ui-light.css ou ui-dark .css ainsi que la typo Symbols.ttf dans le dossier scripts du projet shared (cette version de WinJS sera aussi utilisée avec les Universel Apps)

Enfin il reste à inclure les références dans les fichiers default.html et index.html. Votre projet est ainsi prêt et on peut lancer le développement de notre application cross-plateforme.

Note importante: l’initialisation de l’application est différente en WinRT et en Cordova. Sous Windows on va conserver le fichier default.js, et pour le projet Cordova, on va modifier le fichier équivalent, index.js, pour initialiser correctement notre application.

Un exemple de solution est disponible ici

WinJS dans une application cross plateforme Cordova

Depuis avril 2014, WinJS le Framework SPA de Microsoft est devenu libre (disponible sur github) et  surtout cross-platform.
C’est avec ces nouvelles possibilités qu’on peut maintenant l’utiliser sur d’autres plateformes que Windows 8/Phone 8.1.

Dans cette série de posts, je vais donc aborder le développement multiplateforme d’application avec WinJS.

Build 2014 – Migration d’une application Windows Phone et Windows 8 vers les Universal Apps (Channel 9) : Stéphanie Hertrich, expert technique Microsoft France, reçoit John Thiriet, MVP client dev chez MCNEXT – via @ch9

Build 2014 – Applications Windows Phone 8.1 en HTML et en Javascript (Channel 9) : David Rousset, Microsoft France, reçoit Guillaume Leborgne, MCNEXT – http://bit.ly/1pX4SDs via @ch9

Best practices for WinJS applications

It’s a very exciting time for writing HTML5 native apps for Windows 8, and now for Windows Phone 8.1. WinJS is a very powerful framework but when you start using it, you may experience some trouble. This article will try to give you some advices on how to design your code, and how to avoid the most common pitfalls.

it’s HTML5 and javascript, but it’s not web

This is my first advice and you should take it very seriously ! You are using HTML5 to build native apps. It requires a different mindset, both in coding and user experience. If you are a web veteran, you might have some habits that you will have to lose. In such an application things are stateful, and you are composing screens based on fragments of html/javascript/CSS that should be independant. If you are familiar with single page applications, you are probably familiar with this mindset.
Another point to keep in mind is the security context. In a Windows application, you will not have to deal with CORS concerns, but you will have to be aware of other security or platform restrictions. Let’s name a few :

  • you are not able to use « alert » or « confirm », use system dialogs instead.
  • you are not allowed to inject anything through « innerHTML », HTML is fine, but adding scripts may trigger an error.

learn javascript

Many developpers, especially in the .NET world, tends to consider javascript as a 2nd rank language, something dirty. Others may think they know it because it ressemble C# or java (look, it has curly brackets…), and because they have used a jQuery plugin long ago.
The truth is that javascript is a very powerful language, and that it’s totally different from languages like C# or java (static, strongly typed, object oriented). Javascript is ascripting, functional, prototyped language.
There is beauty and horsepower in this language, but you also have some horrible things. A book like « javascript the good parts » from Douglas Crockford may help you understand which parts to use and why.

learn promises

If you enter Windows 8 and/or Windows Phone 8.1 application, you enter a world of asynchronous programming. In javascript asynchronous means callbacks and promises, at least until EXCMAScript 6 (which should introduce an equivalent of C# async/await). Many libraries uses promises to manage asynchronous calls, it is a very common pattern (jQuery, Angular, Node.js, …).

The principle is dead simple. When you call for an asynchronous operation, you don’t get a direct result like you would in an arythmetic operation :

var a = 12 + 42;

Instead, when calling an asynchronous operation you will get a promise that you will be notified for the result when it becomes available. To get notified, you will have to tell that promise what you want to do when the operation will succeed, or what to do if it fails. You will end up with something like this :

myFunkyAsynchronousCall().done(function successCallback(result){
  //what to do when successfull
}, function errorCallback(error){
  //what to do on error
});

In WinJS you can build promises with « done » or with « then ». Both functions has the same parameters (complete, error, and progress callbacks). The difference is that « then » is returning a promise, it’s a continuation operation, while « done » returns nothing and it’s the end of the asynchronous pipeline. The « then » is pipelining errors but not « done ». Be mindfull that pipelining errors make them hard to debug…

Generally speaking use « then » for chaining promises. Otherwise, use « done ». Just like this :

myFunkyAsynchronousCall().then(function successCallback(result){
  return anotherFunkyAsyncCall();
}).done(function secondSuccessCallback(2ndAsyncCallResult){
  //pipeline success
}, function pipelineErrorCallback(error){
  //what to do on error
});

benefit from HTML5, CSS3, and ECMAScript 5

You are in a place where you know which features you can use. Embrace it ! this is especially true for CSS3 layouts capabilities like flexbox, CSS grid, and properties like « box-sizing ». If all that does not sound familiar, go learn the benefits of CSS3. CSS grid alone can saves you hours of margin+padding nightmares.

you have fragments, use them to store your variables

If you look at what you get when you create a new WinJS project with Visual Studio, you will see a bunch of variables floating around. The Windows 8 samples are no better for that matter. Remember that those code portions are there to demonstrate Windows or WinJS capabilities, not javascript best practices.

You will compose your UI through independent peaces of HTML and javascript. With « WinJS.UI.Pages.define » or WinJS controls, you will define controllers attached to a fragment of HTML. If a variable belongs to a piece of UI, put it inside the code of this fragment.

For exemple, please, please, DON’T write code like this :

(function () {
    &quot;use strict&quot;;
    var myvariable;

    WinJS.UI.Pages.define(&quot;/pages/home/home.html&quot;, {
        ready: function(element, options){
        	myvariable = options.someNavigationParameter;
        }
    });
})();

In the exemple above « myvariable » clearly belongs to the page itself but it is static. Using it like this is bad for several reasons. I will just detail two of them :

  • if you have closure relying on this variable, you may end up with memory leaks because the variable will retain the whole page in memory.
  • you may end up with strange behaviors when you will navigate back and forth to this page, because the variable will still exist with a previous value. Combined with a few asynchronous calls, you will have a very exciting time debugging this kind of issues.

Avoiding those troubles is as easy as this :

(function () {
    &quot;use strict&quot;;

    WinJS.UI.Pages.define(&quot;/pages/home/home.html&quot;, {
        ready: function(element, options){
        	this.myvariable = options.someNavigationParameter;
        }
    });
})();

scope your DOM selectors

This one is also related to the fragment based approach. Imagine that you have a page called « detail ». From this « detail » page you navigate to the same « detail » page but with different parameters. If you are using DOM selectors based on document like « document.getElementById » you will end up with strange behaviors.
The reason is quite simple. When navigating to the second page, getElementById will return the first node with that Id. Depending on your code, the first instance of the page may still be in DOM at that point in time, so your selector will give you a soon to die DOM element. Another case when non-scoping DOM selectors can hurt you is when you are navigating fast in the application. For example opening a page and clicking as fast as possible on the back button. If your page use asynchronous call, and you leave the page before the asynchronous call returns, all your global selectors will return nothing.

Scoping your selector is very easy. First, the « init », « load » and « ready » functions are taking the fragment element as an argument. Secondly, the page object itself has a property called « element » that points to the DOM element of that specific page. Just call « page.element.querySelector(‘#myDomElement’) ». If you are using jQuery for your selectors, remember that jQuery allows you to use scope : « $(‘#myDomElement’, page.element).css(‘display’, ‘none’);

scope your CSS

For better maintainability, we tend to have a CSS document for each fragment. Those CSS are loaded on the fly when WinJS loads each fragment, but they are loaded only once. If you don’t scope your CSS selectors, you may end up with naming collisions. Let’s take an example : fragment A define a CSS class « .myButton » with color red, and fragment B define a CSS class « .myButton » with color green. You navigate to fragment A, the engine loads the associated CSS and the button is red. Now you navigate to fragment B. The engine loads the corresponding CSS and the button green. So far so good. Now if you return to fragment A, the button will stay green because the CSS for fragment A is already loaded and overriden with the one from fragment B. What is funny with this problems is that the resulting behavior will come after some time, and it will depends on the order in which you navigate. Fortunately, the DOM explorer in Visual Studio will help you to find out because you could see the file owning the styles applyed to an element.

As well as what we described for javascript selectors, the best thing to do is to scope your CSS. If you use something like « .fragmentA .myButton { background-color: red } », you lower considerably the risk for namespace collisions.
Using a CSS preprocessor like « .less » may help a lot because you will be able to nest elements instead of cloning selectors. For example, you will write :

.fragmentA {
  .myButton {
    background-color: red
  }
}

The good news is that you could use less today within Visual Studio, and enforce it with Visual Studio extensions like « Web essentials »

use javascript’s bind

The « this » context in javascript is something that is not always fun. Fortunately there are helpers that could help a lot, and the « bind » function is among the most interesting. It’s a function of the function object, that returns a function bound to a specific « this » context.
Well… it’s probably better to take an example :

(function () {
    &quot;use strict&quot;;

    WinJS.UI.Pages.define(&quot;/pages/home/home.html&quot;, {
        ready: function(element, options){
        	var page = this;
        	page.myButton = element.querySelector('#myButton');
        	page.myButton.addEventListener('click', page.buttonClicked.bind(page));
        }

        buttonClicked: function(arg){
        	var page = this;
        	//do something with your page
        }
    });
})();

The « .bind(page) » used when registering the event forces the « this » context to the page object inside the « buttonClicked » function. Without it, the « this » variable Inside « buttonClicked » would correspond to the button itselt.

use libraries

A Windows or Windows Phone apps written with WinJS is not web but it is still HTML / CSS / javascript. There are tons of libraries and jQuery plugins out there that will help you make great apps. There are also some librairies dedicated to WinJS, like WinJS Contrib that could help you a lot.

have fun !

WinJS is not perfect but I have a lot of fun writing applications with it, I hope you will have too.