In last month's release of Office Developer Tools for Visual Studio 2012, the app for Office project templates were redesigned―adding better styling, better structure, and better code to newly-created projects. This post will highlight the benefits offered by the new templates, along with tips for using the templates more effectively.

When creating the new templates, we want new projects to look great and work great. Note that the new structure is certainly not a requirement. Once a project is created, developers can customize the structure their web projects. Existing projects will continue to work with the new tooling.

This post includes the following sections:

• Better user experience
• Better structure
• Better code
• Tips & Tricks

Better User Experience

The documentation on dev.office.com provides a comprehensive set of user experience guidelines for apps for Office. In the past, however, it was up to individual developers to implement these guidelines – which was not necessarily an easy feat. Now, with the new project templates, the UX guidelines are built in!

Here is the task pane project you get when you choose “File>New Project”, select “App for Office”, and press F5.

Figure 1. New task pane app template

Note that:

• The template is pre-configured with a header and a scrollable section for the main content.
• All the padding, fonts, and control styling is in place.
• When you choose “Get data from selection” you get a notification toast, just as described in the UX guidelines.

Mail apps are similarly styled, and likewise give an example of showing a toast notification (in this case, exposing more detail when I choose the “from” field of the sample content).

Figure 2. Mail app template that demonstrates the notification functionality

Finally, content apps provide additional UI features and built-in functionality that is custom-tailored to their use pattern. Content apps are typically bound to some data, so two screens were created: one for displaying the data, and another for generating sample data or binding to existing cells. As you’ll see in a later section, helpful boilerplate was added code that tracks data-bindings, handles navigation, and responds to errors.

Figure 3. New content app template with navigation between the home page and the “Bind to Data” page automatically built-in

Better Structure

In the past, project code was scattered across multiple directories: “Pages” held the HTML, “Content” held the CSS, and “Scripts” held the JavaScript. Unfortunately, with a client-side programming paradigm like in apps for Office, I always found myself jumping back and forth between the HTML and JavaScript files, and getting rather lost in the Solution Explorer. Moreover, any time I would add a NuGet package, my Scripts and Content folders would get a half-dozen files added to it, making it hard to find just my code. If I added a secondary task pane or content app to the same project, things would get even more confusing.

Enter the new project structure design. When you create a new project, your app-specific code will be generated in an “App” folder, which serves as a place for just your code, away from references to external libraries and other miscellaneous files. If you do add another app to the same project, another root-level node will be created (e.g., “SecondTaskPane”) for that app, so that code belonging to different apps stays self-contained.

Figure 4.New project structure with all app-specific code residing under one folder

The code inside the App folder is also organized in a convenient, modular way. App.js and App.css are the “common” files: they represent code that is common to your app irrespective of what page you’re on. Each individual page, meanwhile, is composed of an HTML/JS/CSS trio that is grouped like JavaScript Windows Store app pages.

For task pane and mail apps, a single “Home” page is created; for content apps, a “DataBinding” page is added. Note that navigating to an entirely new page (as opposed to loading content dynamically) does take an extra moment due to the network lag, so the convenience of modularizing the code does need to be balanced with performance considerations. In the case of a data-binding page, this is something that is separate enough from the normal flow (normally a one-time operation per document) that keeping it in a separate page made sense. If something were more common (e.g., an “Add Item” dialog box for a task-list app), keeping the code in the same HTML/JS/CSS trio would provide better performance and hence a better user experience.

The new project structure is something we hope will be helpful for most users – but, if you’d rather use a different layout, that is your option. Just delete the “App” folder, and you’ve got yourself an empty project that you can use as you like. Just remember to update the Source Location in the project manifest to reflect any structural changes to the project.

Better Code

In re-designing the templates, we took time to ensure that the sample code created in new projects is helpful, follows best practices, and is easy to work with. To this end:

• The “app.showNotification” method is exposed for displaying notifications on screen.
• Content apps provide a lot of the boiler-plate structure.
• Sample code is either useful to keep, or simple to delete – the distinction between real code and content-placeholders should be pretty self-evident. Code under App.js and App.css is meant to be expanded upon, but is generally something we expect users to keep and use.
• All code is wrapped in self-executing functions, to prevent polluting the global namespace.
• The code follows general JS/CSS best practices and naming conventions.
• Office.css is clean and well-documented.

Tips & Tricks

When you’re using the new templates, here are some handy tips:

1. Use the structure
   The new template is set up to keep your code easily organized and accessible. So, when you add new code to your project, keep the following in mind:

• Is the new code a script you copied from the Internet? If it’s just a few lines, you could add it to App.js, but in most cases, you’re better off keeping it in a separate file under the Scripts folder.
• Is the new code something you’re writing yourself? If it relates to just a single page, place it the JS or CSS file belonging to the page. If it’s more global to the app, place it in App.js or App.css.
• If you add any new files, remember to add references to them in the HTML pages that use those files.
• Are you modifying Office.css? Don’t. Remember that files under Scripts and Content are best treated as “external”, so that you can replace them with newer versions without having to make any local changes. Any changes you’re making to Office.css can be made in App.css, but this will ensure the conceptual separation between external code and your own code.

Figure 5.Debug mode: Visual Studio DOM Explorer attached to an app for Office

Happy coding with the new app templates! If you have any questions or suggestions for future improvements to the templates – please leave us a comment.

- Michael Zlatkovsky | Program Manager, Visual Studio Tools for Office & Apps for Office