Durandal Framework

Durandal is a JavaScript-based client framework designed for building cross-device and cross-platform Single Page Applications (SPAs). It is intended to simplify the creation and maintenance of applications targeting PC, Mac, Linux, iOS, and Android.

Note: This project is no longer active and has been superseded by Aurelia.

When working with the Durandal Starter Kit, the project is organized into the following directories and files:

• App/: Contains the main application code, organized into AMD modules and HTML views.
• App/main.js: The entry point for application startup.
• Content/: Contains CSS, fonts, and images.
• Scripts/: Contains third-party script libraries.
• App_Start/DurandalBundleConfig.cs: Configuration for CSS and script library bundling.
• Durandal/Index: The host page containing the base HTML, links, and script references.

Durandal uses two types of composition to build applications:

1. Object Composition: Achieved via AMD/RequireJS. Modules can depend on other modules (e.g., Module B requires Module A), allowing for modularization of logic.
2. Visual Composition: Achieved via the compose binding. This allows developers to break views into reusable components and connect them to their corresponding viewmodels (modules). This is the central mechanism for rendering the UI, including widgets and modal dialogs.

Durandal uses a module-view pattern where modules (JavaScript files) provide the logic and data, and views (HTML files) provide the structure.

Key principles:

• Pairing: Modules and views are paired together by convention (e.g., customerList.js pairs with customerList.html). This pairing is managed by the view locator.
• Data Binding: Use Knockout.js bindings within the HTML view to synchronize the DOM with the module's properties. When a property in the module changes, the DOM updates automatically, and user interactions in the DOM can update the module.
• Root Element: Every view must have exactly one root element. If multiple root elements are present, Durandal will wrap them in a <div>. If comments are found at the root, they will be removed.

The compose binding is a powerful Knockout-based feature used to swap views dynamically. In a shell/layout, you can bind the compose instruction to an observable (like a router's active item). When the observable changes, Durandal:

1. Detects the change.
2. Uses the viewLocator to find the appropriate view for the new module.
3. Data-binds the new view and model together.
4. Inserts the result into the DOM at the binding location.
5. Applies an optional transition animation.

Syntax:

<!--ko compose: { 
    model: activeItemObservable,
    afterCompose: callback,
    transition: 'animationName'
}--><!--/ko-->

<!--ko compose: { 
    model: router.activeItem,
    afterCompose: router.afterCompose,
    transition:'entrance'
}--><!--/ko-->

Durandal's router and lifecycle management handle complex navigation scenarios:

Routing

The router supports:

• Mappings: Route-to-module mappings or convention-based routing.
• Navigation Modes: Support for both hash and pushState navigation.
• Data-Driven Routes: Support for parameters, optional parameters, splats, and query strings.
• Child Routers: Ability to encapsulate entire areas of an application with their own routing structures.

Screen Activation Lifecycle

To handle 'dirty' states (e.g., preventing a user from navigating away from an unsaved form), Durandal implements a screen activation lifecycle. This allows any screen, fragment, or component to synchronously or asynchronously control the flow into and out of a navigation event. This lifecycle is also used to manage the behavior of modal dialogs.

Durandal is designed around Promises to handle asynchronous data requests and resource loading.

• API Consistency: All potentially asynchronous Durandal APIs return promises.
• Promise Libraries: While jQuery provides the default promise implementation, you can switch this out for other libraries like Q.
• Observable Module: When targeting ES5 browsers, enabling the observable module allows the Knockout binding system to data-bind directly to promises. For example, you can use a foreach binding directly on a promise that resolves to an array of data, removing the need to manually resolve the promise in your application logic.