| Comments

In my working with Windows Store apps, I’ve become increasingly fond/aware of the advantages for app localization.  There are a lot of resources out there for you to localize your app using a good-better-best approach as well.  I’ve previously written about localizing a Windows Store app using some of these methods and what the WinRT platform supports to make this easier in most cases.

Now that you’ve localized your app, you may be faced with the question of how you might want to respond to language choice changes by the user.  Remember that the Windows Store app model is that it honors the user’s language choice preferences matching that with the available languages the app indicates it supports.  This may not always map to the user’s installed OS language.  For instance I can have an English OS install but prefer German in my apps and set my language preference to: de-DE, en-US.  If a Windows Store app was localized in German, then I would see that version instead of English because my preferences say so, regardless of my OS install.

Language switching problem

Now, I’m not as proficient in German as I’d like to be, so there may be times where I need to flip back to English to understand certain areas of an app.  I can do this easily by going to the languages panel and switching my order of preference:

But when I go back to my app, it is still in German…until I terminate/restart the app.  Let’s say I started the app and it honors my language preference:

Now I go and change back to English and click the button to take me to page 2.  It is still in German even though my language preference list is now: en-US; de-DE.

The XAML framework doesn’t automatically re-evaluate the resource cache in response to these changes.  This is something the developer has to manage and luckily there are some easy steps you can do to make this experience better for your users.

We should point out that this is likely a rare case that a user of your app is constantly switching languages and switching back to your app, but having your app support this is a delighter for your users when it does happen.

Solution: listening to qualifier updates

There are APIs to the rescue here!  When you switch your language preferences, the system actually is aware of it, however the context that your app already had at launched has been cached…and thus it will still be delivering the original context-aware resources.  Good for us is that the APIs can let us know when this happens and we can respond.

Since most apps have only a single Window object and since this change is likely rare, we should manage this call and not put it on every Page load, for example, but rather higher up in the App because it will likely be rare that it happens.  In our activation code path we can listen for the resource context to change

   1: protected override void OnLaunched(LaunchActivatedEventArgs args)
   2: {
   3:     ...
   4:     ResourceManager.Current.DefaultContext.QualifierValues.MapChanged += QualifierValues_MapChanged;
   5:     ...
   6: }

In this snippet we are using the default ResourceContext and listening for when its qualifier map changes.  The qualifier map is the set of context for resources like language, but also scale, phonetics (for Japanese), high contrast, etc.  Once that map changes we can force a refresh of the cache essentially:

   1: void QualifierValues_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
   2: {
   3:     ResourceManager.Current.DefaultContext.Reset();
   4: }

This simple flow basically says “hey, when a qualifier has changed, reset the context map so that I get the new data” and our app in subsequent calls to the resources will get the updated resources.

Here’s a video demonstrating the completed before/after approach.

There is a big caveat to this approach.  The change doesn’t automatically affect your current view.  So your page has rendered and is in German.  If I go and change it to English, then go back to my page…it isn’t automatically in English.  Subsequent view loads (and even going back to this page) will get the new resources, but already-rendered ones do not.  The developer can, of course, implement way more logic to refresh the view, traverse the tree, etc. to manage this, but that experience is up to the app developer to determine what is most appropriate for the app itself.

This is a little subtle but helpful tip in enabling your localized apps to be flexible to these types of changes by users when that happens.

Hope this helps!

| Comments

In some of our internal discussion lists there was some questions about how to host certain content for their application.  Most of the discussion came up from apps needing a privacy policy (Rule 4.1 from the Windows Store App Certification Requirements).  Some folks had apps they just developed, but no “site” or service they were using.  But they needed to host a privacy policy.  Lots of thoughts were floated around and I suggested Azure Free Web Sites as an option.  I originally suggested it as a simple way you could just have a URL to a privacy policy, but…duh, you could easily use it as a very quick marketing site for your app.

Creating a web site in Windows Azure

If you didn’t know, Windows Azure allows you to create a free web site!  It is very quick and simple to set up once you have your Azure account set up.  After doing that go to the portal and choose to create a new Web Site.  I recommend picking from the gallery and choosing WordPress.  There is such a vast ecosystem around WordPress as a CMS system that it is simple to use and set up. 

NOTE: Of course you can use others, even a static web site using the TFS/Git deploy feature even.  Do whatever you want.  I just think WordPress is great and allows you to scale your site features without writing code, etc.

Choose to create a site from the gallery:

Azure Find Apps image

This will walk you through a wizard to pick some names and options.  It is pretty self explanatory.  Once completed you will see your site provisioned in the portal.

Azure web sites image

Just click that link and you will be taken to your site…which for WordPress will be the initial setup page to choose your login.

Choosing a WordPress Theme

Once in the WordPress admin site, choose the Appearance option on the left, then the Themes sub-menu.  Once there, go to the Install Themes tab to pick a theme from the gallery.  Optionally you can grab a premium theme from various sites.  There is one called “Responsive” (search for that term) that is in the built-in gallery, free, and actually serves the basic needs well.  We’ll choose that one:

Responsive theme install image

After you pick it you’ll want to Activate it as the current theme.  Now let’s do some simple configuration.

Configure the WordPress site

In order to serve the goal of making this more of a marketing site and to host our privacy policy we don’t need commenting on pages.  Additionally we want “nice” URLs for our site.  Let’s start with a few simple tweaks.

First (in the WordPress admin site) go to Settings->Permalinks.  Choose the “Post name” option.

WordPress permalink settings image

Next go to Settings->Discussions.  In the top uncheck the “Allow people to post comments on new articles” in the top:

WordPress discussion settings image

This will prevent commenting on content.  Next using the Responsive theme we can configure the home page.  Go to the Appearance->Theme Options section.  You’ll see a “Home Page” option for the Responsive theme.  You can set the main text, tagline and two other options.  This gives you the chance to set the URL for your app that is provided from the Windows Store. 

Here are some posts to help you find URLs for your app: Linking your apps on the web and Connect your web site to your store app.

Here is an example:

Responsive theme home page config image

Now go to Appearance->Widgets to modify some information on the home page for the 3 widget areas.  These could be simple things like a quick blurb about what the app is, maybe some top features, or whatever.  In the admin widget area you’ll see Home Page Widget 1,2,3.  Simply add the “Text” widget to these and you can add the title/text for this:

Home page widget image

You can also remove the theme logo to provide your own logo in the Appearance->Header section to provide your own image.  You can also specify a custom image on the main “hero” section of the home page instead of the default image and specify that.  Once all these quick tweaks are done, your home page is done.  Visit the site to see the quick changes.

Now let’s add our privacy policy so we have a permanent place for our privacy details.

Add a Privacy Policy page

From the WordPress admin site, go to Pages->Add Page.  Name it “Privacy Policy” and then type in your privacy policy text.  You can modify the text using HTML formatting to fit your needs.  Make sure to use the “Full Width Page” template so that it shows the entire page.  Notice the URL for the permalink.  I recommend keeping it simple with “privacy” or “privacy-policy” as the name (which should be default):

Privacy page editing image

Once you Publish the page, your site will now have a link to “Privacy Policy” on the home page and you can use that in your site, for your certification process and other areas you may need it.

You can now provide a link within your app to your privacy policy as well.  Andy has a simple method of adding it to the Settings charm and simply linking to your online site now.  You can visit the site to confirm it looks as you wish:

Privacy page image

Done!  You can see this example at http://timscoolapp.azurewebsites.net

Profit!

Now you have a free site on Azure to host marketing your app.  Of course this helps those getting over the hump with providing a nice place for a simple privacy page, but also enables you to have a way to provide other pages for your app.  You could provide more detail on features, have a form to collect feature requests, whatever.  WordPress is very flexible and the same process you used to create the privacy page can be used for other full-page content.  Or you can explore what WordPress has to offer you.  Again, there are many different ways you can do this and even within WordPress other themes you could choose.  However I think the Responsive one is a simple one to get started with as a base.

You may want to not have “azurewebsites.net” as your site URL as well.  If you wanted you can migrate to a shared instance (not free) and have custom domain name resolution on your Azure site as well.

Hope this helps!

| Comments

I’ve previously posted a few things about SQLite including a HOWTO on how to build from their source code.  If you still want to build your own DLL from their source code that is totally fine, but not necessary in most every single case I’ve seen in app usage.  One of the challenges I noted is that since SQLite is a native component and if you are a managed (.NET) app you can’t be architecture neutral anymore (AnyCPU).  What this means is that you have to build your app for each architecture you want to support: x86, x64 and ARM.  The flow of this using SQLite3.dll was that you would have to package, change the DLL, re-package. 

Not anymore.

In working with the great folks on the SQLite team, they’ve packaged the binaries up (for Windows 8 apps) in a nice installer using the Extension SDK format.  What this means is you now add a ‘reference’ to the SQLite binary and based on the architecture being built for your package, it will pull in the right DLL without you having to manage that yourself.  Here’s some step-by-step…

Installing the SQLite for Windows Runtime package

The first thing you want to do is install the package.  You can do this from within Visual Studio itself in all editions.  From the Tools menu, choose Extensions and Updates and then choose the Online section (on the left of the dialog) and search for ‘sqlite’ in the search term.  This will show you the SQLite for Windows Runtime package:

Visual Studio Extensions dialog

Click install my friends.  You will be prompted to restart Visual Studio which you should do.  Go ahead…I’ll wait.

Using the new package in your C#/VB app

Now that you have the SQLite for Windows Runtime package installed in your Visual Studio environment, you want to use it.  In a managed (.NET) app you would do the following steps.

First, create your app (e.g., a Blank XAML app is fine).  Once within your app, use the Add Reference mechanism to get to the next step.  Now you will not be browsing for any DLL directly like you would in a traditional .NET.  What we are adding here is a reference to the Extension SDK…not the library itself, a small but important distinction.  Once in the Add Reference dialog choose the Windows\Extensions view (see on left) and you’ll see SQLite for Windows Runtime.

To correctly use this in a managed app you’ll need to select that *and* the C++ runtime as seen below:

Add Reference dialog

The reason for this is to ensure that your app declares the right dependencies that are needed for the app to run.  The likelihood of the C++ runtime not being on a Windows machine where your app will be installed is extremely rare, but you need to declare this anyway.  Failure to do so will fail your app certification tests.

Now with this involved you can grab a managed wrapper to call the SQLite APIs as I’ve previously described in my HOWTO video.  I personally recommend the sqlite-net library (available via NuGet) to make this easier for you.

NOTE: sqlite-net is available as source in C#.  If you are using a VB app, you would first need to compile the sqlite-net source in a separate DLL so you can just add a reference to that in your VB project.

Using the sqlite-net library you can perform tasks using a model similar to LINQ2SQL where you can have types represent database entities:

   1: public sealed partial class MainPage : Page
   2: {
   3:     public MainPage()
   4:     {
   5:         this.InitializeComponent();
   6:         LoadData();
   7:     }
   8:  
   9:     public void LoadData()
  10:     {
  11:         var dbPath = Path.Combine(Windows.Storage.ApplicationData.Current.LocalFolder.Path, "db.sqlite");
  12:         using (var db = new SQLite.SQLiteConnection(dbPath))
  13:         {
  14:             db.CreateTable<Person>();
  15:  
  16:             db.RunInTransaction(() =>
  17:                 {
  18:                     db.Insert(new Person() { FirstName = "Tim", LastName = "Heuer" });
  19:                 });
  20:         }
  21:     }
  22: }
  23:  
  24: public class Person
  25: {
  26:     [SQLite.AutoIncrement, SQLite.PrimaryKey]
  27:     public int ID { get; set; }
  28:     public string FirstName { get; set; }
  29:     public string LastName { get; set; }
  30: }

Now you just need to specify your architecture for your app (x86, x64, ARM) and when you build, the appropriate sqlite3.dll will be packaged in your app automatically.  This also happens during the packaging step for the store so the right item is included for each architecture-specific package.

WARNING: Do not package in DEBUG mode as you will fail certification.  Ensure that you build/package in RELEASE mode prior to submitting to the store or running the app certification toolkit (also referred to as WACK in some places).  You will get false positives if you are compiled in DEBUG mode.

This should make your development much easier without having to  swap out DLL files each time.

Using the new package in your C++ app

If you are a C++ developer you will do the same steps for installing and adding as a reference to your app.  In the C++ project system there is no 'Add Reference’ menu on the project context menu, but you will choose References and then the Add Reference button shows up.

Once you have the reference to the SQLite SDK then as a C++ developer you can just #include the header and go to work:

   1: #include <sqlite3.h>

Since C++ projects are already architecture-specific you don’t have to worry about the AnyCPU situation because there isn’t one!  You’ll get IntelliSense on the API by just including the header.  The Extension SDK mechanism already includes the C++ props file to help the project system know where to get the header for development and the lib for linking when building.  Most C++ developers will interact with SQLite using the native APIs and not need any additional wrapper library.

Using the new package in your JavaScript app

If you are using JavaScript/HTML to developer your app, you will follow the same flow as the C#/VB flow.  Add a reference to both the SQLite SDK as well as the C++ runtime (to declare the dependency).  As to accessing SQLite in your app, you’ll need a WinRT wrapper library to do that.  The one that seems to be gaining favor is the SQLite3-WinRT library on GitHub.  I have not personally used this, but seen a lot of people using this.  It allows you to use the JavaScript programming model in a familiar way:

   1: var dbPath = Windows.Storage.ApplicationData.current.localFolder.path + '\\db.sqlite';
   2: SQLite3JS.openAsync(dbPath)
   3:   .then(function (db) {
   4:     return db.runAsync('CREATE TABLE Item (name TEXT, price REAL, id INT PRIMARY KEY)');
   5:   })
   6:   .then(function (db) {
   7:     return db.runAsync('INSERT INTO Item (name, price, id) VALUES (?, ?, ?)', ['Mango', 4.6, 123]);
   8:   })
   9:   .then(function (db) {
  10:     return db.eachAsync('SELECT * FROM Item', function (row) {
  11:       console.log('Get a ' + row.name + ' for $' + row.price);
  12:     });
  13:   })
  14:   .then(function (db) {
  15:     db.close();
  16:   });

If using JavaScript this might be the way to go for your app.

Summary

I’m very glad the SQLite team worked to get this deployment package out there.  I think for some Microsoft developers, using SQLite is fairly new and this SDK package will make it easier to ensure you have the right bits at the right time.  Of course you are free to do it your own way, but I think this will ease the process a little bit.

Why no NuGet? Well, the NuGet infrastructure right now doesn’t support some of these semantics around native components to deal with headers, linking and architecture-specific deployments.  We’ll continue to work with them to see if we can drive these changes into that platform.

So please feel free to download via the Visual Studio ‘Extensions and Updates’ option from within VS, download directly from the Visual Studio Gallery, or download from the SQLite site themselves.  Once installed, once an update is available, VS will notify you that an update is available and you can install it.

Hope this helps!