MDown: My First Windows 8 App

I have been focusing a lot on HTML5 games lately but have always loved application development. I figured I would take a short break from my games and focus on an app I have been wanting to build for a long time. MDown is a Markdown editor written entirely in HTML/JavaScript for Windows 8. I just submitted it to the Windows Store in order to make it in before Windows 8 launches at the end of the month, so I thought I would do a walkthrough of the app and point out some cool things I was able to do with JS by taking advantage of the WinJS Library.

About MDown

Markdown is a great way to format text in a way that can easily be converted into HTML. I quickly fell in love with using Markdown thanks to GitHub supporting it across the board from your project’s readme file to the wiki and GitHub Pages. Additionally, as I started digging into Jekyll when I built gamecook.com as a GitHub Pages site, I quickly realized how much I needed a solid Markdown editor. There were a few on the Mac, and after switching over to Windows 8 full time, I figured it was a perfect opportunity to create my own editor.

At its core, MDown is a very simple application. Here is a quick diagram to show the flow of how the application works:

When you think about it, an app like this really boils down to two modes: loading files and editing them. When it comes to loading in data, you are either starting with a blank file or opening an existing file. The second mode is editing, which is self-explanatory. As you can see from the main screen, you are presented with several options in order to create a new document such as new, open, or pick a template.

Because I had identified this pattern early on, I was able to architect the application around the concept of always opening an “existing” file. So, if you use the open option, you pick your own file from the computer. If you use the new option or template, you actually open a template file, which is stored in the application package. The new button actually happens to just be a blank template file. This allowed me to greatly speed up development of my app and simplify the core logic to help scale the application later on as needed.

At the core of MDown is the editor. It’s actually based on an old Markdown library called WMD. I found a modified version of it on GitHub by ChiperSoft here. There were a lot of options out there, including some newer Markdown editor libraries, which are being developed for use on StackOverflow, but the older WMD was easy to set up and only required minor modifications. Here is a quick preview of MDown’s editor:

As you can see, it’s a standard-looking, split-pane view. The Markdown editor is on the left, the preview on the right, and I have an AppBar at the bottom with formatting options that appear when you highlight text or manually open the AppBar tray. The only modification I had to make to MDown was to change the built-in logic that created a toolbar with formatting options to output AppBar commands to better integrate with Windows 8. Other than that, the rest of the code was completely untouched.

Outside of using WMD, I didn’t feel the need to add any additional third-party JS libs to the project. I started out using JQuery but decided, in the end, that it wasn’t worth having an extra library and did all of my DOM manipulation by hand, which worked out just fine. Finally, I leveraged the Grid App template in Visual Studio as much as possible, which took care of roughly 70 percent of my total application’s UI, layout, and screen management.

Designing for Win8

For someone with an extensive design background, I really struggled with creating a logo and design I was happy with. For a few days I just wasn’t feeling creative, and my first round of logos and layouts were really bad. Designing for the new Modern UI is challenging in some ways and liberating in others. It took a lot of sketches and rethinking until I realized I was just over-complicating it and went back to something simple and clean. You’ll hear “less is more” a lot when it comes to designing Modern UI apps, and it’s totally true. Here is the logo I ended up with for the loading/splash screen:

The one thing I learned through this exercise is that you need to keep your designs simple. I have seen some very nice designs that push Modern UI, but for an app that I wanted to build in a few days, I realized I should leverage as much of the built-in style as possible to cut down my development time. In the end, I am very happy with how the entire app looks, and as you can see, the logo looks great on the splash screen.

Outside of the logo/splash screen, I also tried to reuse the Grid template’s look and feel as much as possible. While I won’t win any creativity awards for simply changing the color palette, at least I was able to make a good looking app with very little work. I did get to play around with MS Grid (Grid Layout), which is really helpful but took some time to wrap my head around. Once you understand how it works, laying out UI is incredibly easy and takes away all of the pain I used to feel by doing this kind of stuff with CSS alone. The upside of building an app specifically for Windows 8 is not having to worry about cross-browser compatibility issues. This is something I have a hard time letting go since I had been conditioned to build Web apps across several different browsers for years, but it’s also liberating to know that my CSS will work exactly as I expect it to on all Windows 8 devices as long as I test it properly.

Snap View

Another one of the more difficult things to work through is snap view and how to make your application usable with a width of only 360 pixels. The Grid template has some responsive design logic built in that I was quickly able to clean up and customize to fit my needs. I focused on making sure the two primary functions of the application were usable in snap view and hid what I felt was not needed.

Here is the main screen of my app in snap view, which shows you all of the options in list view:

For the start screen of my app, I had to programmatically change the layout container, but it wasn’t a big deal. I was trying to do this all via CSS, but by using code I was able to get exact control over how everything was viewable when in snapped mode while maintaining usability. Next up, here is how I handled the editor in snap view:

As you can see, I hid the preview window so you are left with the main controls needed to edit a document such as the editor itself, the word count, and the back button to close the document and save. In this case, I was able to do everything via CSS.

Leveraging WinJS

Now that I have covered the two main functions of the app, it’s time to go over the glue that holds everything together. WinJS is the JavaScript API that all HTML-based Windows 8 apps are built on and allows you to communicate directly with the OS. In MDown, I take advantage of WinJS’s File API, managing the contents of the AppBar, as well as the ability to add to the Settings charm. Let’s take a quick look at how I do this.

When it comes to loading and saving, I took advantage of some of the excellent code tutorials you can get inside of Visual Studio. There are actually online samples that cover all of the core features needed to build Windows 8 apps. To see these templates, simply open up Visual Studio and create a new project.

Next, select Online from the left-hand list of options, and under Samples, you can choose your language of choice. I was able to find a great example under JavaScript covering how file access worked.

From there, it was a matter of abstracting the code I needed and integrating it into my application. In MDown, I wanted to make saving simple and unobtrusive, so I only show the save dialog box when you select back to exit editing the file.

In future versions of the app, I plan on having MDown create a temporary document to continuously save changes to while a user makes edits to the file. If they choose to save, it will use the contents of the temporary file, and that will also work as a backup in case the app crashes or the user exits it by accident. One of the blessings of Modern UI apps is the single-minded task focus, which funnels all user activity into one simple activity without distraction. I don’t have to worry about modifying multiple documents at the same time or anything very complex, so I can implement a very basic history management solution knowing that there will always be only one document being edited at any time. Use this to your advantage when designing your own app.

Likewise, integrating the file picker was very easy. As you can see, when you choose to open a new file or save a template, you are presented with the file picker, which is simply called via a WinJS API. Again, I used one of the Visual Studio samples to see how it worked then integrated it into MDown.

When it comes to the built-in Markdown templates, I have a directory in my application that contains a few Markdown files.

When the user selects a template or new file, I load the file up locally from the app, and when the user saves, I pop up the file picker to let them save a copy. This allowed me to greatly speed up my own development since I only have to manage one type of action to trigger the editor, which is open a file through the file picker or internally from one of the templates. In order to load any file compiled in with the app, you need to use the “ms-appx:///” file path along with calling:

Windows.Storage.StorageFile.getFileFromApplicationUriAsync(uri)

Simply supply the path to the file. For example, the URI of my untitled.md template, which is what I use when someone creates a new document, would be “ms-appx:///templates/untitled.md.” This is incredibly helpful when you are loading settings or other hard-coded configure files you don’t expect to change a lot in your application and make sense to package up with the distributed app.

Finally, I was able to add a Help section to the Settings charm. When you add new options to the Settings menu, they show up as clickable links that you can direct to an HTML file. Here is an example of the Help menu showing up in the Settings charm:

And, when you click on the Help option, you get a quick-reference guide for Markdown syntax.

This was actually really easy to set up; all I did was add the following to my default.js:

All of these WinJS features I added to my application can be found in the Visual Studio samples, so make sure you go through them and take a look at their code. It saved me a lot of development time, and they are an excellent resource for seeing how WinJS and other APIs work in Windows 8 apps.

Submitting to the Windows Store

Finally, when you are ready to submit your app, you simply open the Project menu in Visual Studio and go to Store then select Upload App Packages.

From there, you can follow the wizards that will walk you through the upload process.

I had already set up all of my Windows Store apps ahead of time, so I could reserve the app names, and I was able to simply select the app I wanted to upload from a pre-populated list. If you don’t have an app already set up, you can select Reserve Name from the options as well. Visual Studio is totally integrated into the online Windows Store accounts making selecting, uploading, and updating Win8 apps incredibly easy.

From there, you can pick the platform to deploy your app to as well as set up automatic versioning, which is incredibly helpful.

Once you are ready to upload your app, you will need to run it through the Windows App Certification Kit. Funny enough, my app failed to pass on the first try. The problem was easy enough to fix, and the Certification app tells you exactly what the problem is.

I was getting an error that some of my files were “not properly UTF-8 encoded. Re-save the file as UTF-8 (including Byte Order Mark).” Apparently, all of the third-party JavaScript code I had added to my project needed to be re-saved with UTF-8 encoding. This is easy to do. Simply open up the files that caused the error and re-save them using Advanced Save Options. Once you select this option, you can choose Unicode (UTF-8 with signature) – Codepage 65001 from the options.

After I had corrected this, my app passed the App Certification Kit test. From there, you will be able to upload it to the Windows Store. As you can see below, my app’s version was automatically incremented since this was my second attempt at uploading it.

From here, you fill out all the standard details about an app such as how much you are going to charge for it, list its features, age restriction, declare if you use any type of Cryptography, a description, and all your promotional artwork. If you have ever submitted an app to a market before, this should all be familiar. If not, the wizard and descriptions will walk you through the entire process.

The one thing I suggest, even if you plan on doing a free app, is that you set a price upfront. If you ever decide to lower the price or do a free giveaway for a period of time, you can only do that if your app is initially set to be sold, which is similar to how the Android Market is (and which I made the mistake of doing with one of my more popular games by only setting it up to be free). So, think very carefully about how you decide to set up your selling details so you don’t lock yourself into something you may not want in the long run. You may have noticed I set the price to $1.99, which I plan on dropping to free once the app is approved.

Wrapping Up

As you can see, even with this simple app, there was a lot to cover. Building and publishing an app to any market is a daunting task but hopefully a rewarding one. This app took me a total of two weeks to complete. One week to just ramp up on Windows 8 development with HTML/JavaScript and the other week to add the Windows 8-specific features my app needed to work correctly. The best part of building this app was the ability to leverage existing Win8 code examples, third-party open source libraries, and my years of JavaScript/HTML/CSS experience to make a desktop app that truly feels and acts like it was native. This is something I was never able to do with any other platform or framework! Hopefully this inspires you to try and build your next Win8 app with JavaScript. My plan is to continue to build small Windows 8 utility/productivity apps that fill gaps in my own tools to help me build games. Next up, I plan on turning Impact’s level editor into a standalone Windows 8 tile map editor to assist with designing my own games. My take on app development is to build for yourself first, release it, and continue to iterate and add features others want/need. When you build apps you want and can actually use, you’ll have a better chance of completing them.

MDown was recently approved and you can download it from the Windows Store here.

Subscribe To My Mailing List

Want to learn how to make a game? Not sure where to start? Even if you are a seasoned game maker there is still a lot you can learn from my mailing list. I'll be covering tips and tricks for how to build, release and market games each month.

Simply sign up for my mailing list and also get access to a 50% off discount code for my eBooks and other content. I promise to not spam your inbox!

About Me

Jesse Freeman is a Developer Evangelist at Amazon focusing on HTML5 and gaming.

Jesse has been on the cutting edge of interactive development with a focus on the Web and Mobile platforms. As an expert in his field, Jesse has worked for Microsoft, MLB, HBO, the New York Jets, VW, Tommy Hilfiger, Heavy and many more. In addition to development, Jesse has a background in art with a masters in interactive computer art from the School of Visual Arts.