If you don’t follow the various ALM Rangers Solutions, you should! If you do, then you already realize there is a lot of content put out by the various ALM Rangers project teams. In fact, there is so much information provided by the ALM Rangers that they have provided a Windows 8 app to help navigate the ever-changing waters of available content – the ALM Readiness Treasure Map.
[If you’re running Windows 8, click the above image to install the app now]
Coming Enhancements
Although version 1 of the app has seen a lot of use, there is much room for improvement. That said, there is currently a team of ALM Ranger pirates currently hard at work on implementing many of the proposed enhancements for version 2. One enhancement in particular is the ability to track the status of each guidance document (referred to as jewels within the app) as you make your way through the treasure map.
If you take a look at one of the proposed screen mock-ups below (click here if you’re interested in seeing the rest of the mock-ups), you’ll notice just after the title the text “1/15 completed”. This implies that you have flagged one of the guidance documents within this section as having been read. With this update, we plan to track three states in regards to document status, including:
- Not Started – you have not yet viewed the document
- Started – you have started viewing the document but have not yet completed it, depicted graphically by an open, yet empty, treasure chest (as seen below)
- Completed – you have completed viewing the guidance document, depicted graphically by a filled treasure chest (as seen below)
QUESTION: We have gone back and forth on whether or not a guidance document should be automatically flagged as having been “Started” once you click on the link within the app to view it. As you can see in the mock-up above, there is a context menu that allows you to manually flag a document as having been “Started” (amongst other states). We are considering making this an app preference where you get to decide how it works. However, we don’t want to make something that should be simple, complex. If you have a strong opinion one way or the other, let us know in the comments below.
As a document’s status is updated, the app will utilize the built-in data roaming features of Windows 8 to synchronize the status across your Windows 8 devices. So, if you start viewing a document on your Windows 8 laptop and move to your Windows 8 tablet, the correct document status will appear on the tablet as well (assuming you’re using the same Microsoft Account on both devices).
Design Details
The following details outline the changes to be made to the source code to support the tracking features described above.
Data Layer (Data Providers)
TreasureMapDataModel.xml
- Add ID attribute to <guidance/> element and populate with unique integers (consider grouping by category - e.g. "Prepare" = 0-999, "Quick Intro" = 1000-1999, and so on...). The ID is currently assigned dynamically when the data structure is loaded. However, since we'll be syncing up document Status each time the app is ran, we need to ensure the IDs don't change. For this reason, we need to add them to the data.
DB.cs
- In LoadDB method, replace uniqueGuidanceCounter with newly added ID attribute from above.
Business Logic Layer (View Models)
Status.cs
- Create Status.cs which simply contains a new enum:
public enum Status {
NotStarted = 0,
Started = 1,
Completed = 2
}
Guidance.cs
- Add a read-only Status property of type Status. This property will be read only to force updates to go through the StatusManager (below) where the overall status values will be kept up to date.
StatusManager.cs
This is a new class used to encapsulate some of the logic necessary to set guidance status as well as return various guidance status based on categories and projects. This class would be surfaced through the DB class because a) it is always in scope (via the App class) and b) this would allow the StatusManager class to be provided with a reference to the DB class which has references to the categories and projects needed for status counts.
Properties:
These properties would be calculated once (via the private methods below), during the initialization of the StatusManager class. After initialization, they would be kept up to date as the SetStatus method is called. This alleviates the need to continually walk the data hierarchy as the counts are displayed via data binding.
- int CompletedProjectCount
- int CompletedDocumentCount
- int ProjectDocumentCount
- int TotalCompletedCount
Methods:
[-] = Private; [+] = Public
- -GetCompletedProjectCount(int category) - gets the total number of projects, for a given category, where all guidance documents have a Status of Complete (2). Used for displaying completed ratio on the "category" page.
- -GetCompletedDocumentCount(int project) - gets the total number of guidance documents, for a given project, that have a Status of Complete (2). Used for displaying completed ratio on "projects" page.
- -GetProjectDocumentCount(int project) - gets the total number of guidance documents for a given project. Used for displaying completed ratio on "projects" page.
- -GetTotalCompletedCount() - gets the total number of guidance documents, across all categories and projects, that have a Status of Complete (2). Used for displaying overall percentage (on tile).
- +SetStatus(int guidance, Status status) - sets the current status for the specified guidance ID. Used by the "Mark as" menu for "Not started", "In progress", and "Completed".
- -Save() - saves the current state of the various document Status values to "roaming" storage. This would be simply serializing a List<Dictionary<GuidanceID, Status>> for simplicity. This method would be called, asynchronously, each time the SetStatus method is called.
- -Load() - loads the current state of the various document Status values from "roaming" storage. This would happen during initialization of the StatusManager class.
UI (Views)
Projects.xaml
- Capture Tapped event for "jewel" hyperlinks and set Status for selected guidance document to Started (1) unless it's already been marked as completed. Question - do we want to automatically mark something as Started the first time it is opened or do we want to purely rely on the user to mark it via the menu option?
More Information
