Introduction

This tutorial explains the framework on the sample package "myPackage" which contains a sample view "SampleView". The directory structure of this sample Visto application can be seen in the following listing:
  • home.html: The entry page which loads the rest of the application
  • scripts
    • app.js: The application entry JavaScript file.
    • libs: Contains the Visto JavaScript Library, KnockoutJS, JQuery and other libraries
    • app: The application default package
    • myPackage: Sample package for this introduction
      • languages: Contains JSON files for each language
      • viewModels: Directory which contains the view models
        • SampleViewModel.js (optional): The view model for the view: The view's HTML is bound to this view model using KnockoutJS bindings
      • views: Directory which contains the views (HTML and "code-behind")
        • SampleView.js (optional): The "code-behind" of the view
        • SampleView.html: The appearance of the view defined as HTML
In the file "app.js" the application navigates to the first page. Each view can be used as page, the only difference is that a page supports more event methods. The next chapter shows how to develop a new view. For more information about pages go to the chapter Paging.

View HTML

First, let's have a look at the view's HTML declaration - the file views/SampleView.html:

<div>
	<!-- Bindings to view model -->
	<div>Firstname: <span data-bind="firstName"></span></div>
	<div>Lastname: <span data-bind="lastName"></span></div>

	<!-- Load other view (passing const value and observable as parameters) -->
	<div data-bind="view: { name: 'OtherView', observableParam: lastName }" />
	<!-- The same using custom tags: -->
	<vs-other-view observable-param="{lastName}" />

	<!-- Define HTML element with ID 
	(vId is automatically replaced by the view instance ID) -->
	<div id="vId_myDiv"></div>
</div>

As you can see in the HTML, it is possible to bind variables to the UI and instantiate other views declaratively. See View HTML for more information.

View Model

All bindable variables are declared and instantiated in the view model using KnockoutJS observables. The view model viewModels/SampleViewModel.js in JavaScript:

define (["exports"], function (exports) {
	function SampleViewModel() { };

	SampleViewModel.prototype.initialize = function() {		
		var self = this; 
		self.firstName = ko.observable();
		self.lastName= ko.observable();
		
		var param = self.parameters.getValue("param"); // read passed parameter
	};

	exports.SampleViewModel= SampleViewModel;
});

Of course, the same view model can be implemented using TypeScript and is thus strongly typed. The following listing shows the file viewModels/SampleViewModel.ts:

import ns = module("../views/SampleView");
export class SampleViewModel extends VistoDialog<ns.SampleView>  {
	firstName = ko.observable<string>();
	lastName = ko.observable<string>();
	initialize() {
		var param = this.parameters.getValue("param"); // read passed parameter
	}
}

The view's parameters which are passed from the view creator can be read using the view's or view model's "parameters" property:

var constParam = this.parameters.getValue("constParam"); // like a one-time binding
var observableParam = this.parameters.getObservable("observableParam"); // like a two-way binding

By calling getObservable or getObservableArray it is possible to pass an observable from the outer view into the sub view and let the sub view "write values back" to the outer view by modifying the observable (two-way binding).

Check out the page view model for more information.

View "code-behind"

If needed, it is possible to implement a "code-behind" class for the view in the views/SampleView.js file. All code which directly interacts with the HTML (e.g. JQuery widget creation, etc.) should be placed in this class.

define (["exports"], function (exports) {
	function SampleView() { };

	SampleView.prototype.loaded = function() {		
		var self = this; 
		// TODO add code which is run after view is visible in DOM
	};

	exports.SampleView = SampleView;
});

And like before, here the TypeScript version of the file views/SampleView.ts:

import ns = module("../viewModels/SampleViewModel");
export class SampleView extends VistoDialog<ns.SampleViewModel>  {
	loaded() {
		// TODO
		var vm = this.viewModel; // view model is fully typed
		var myDiv = this.getElement("myDiv");
	}
}

See View for more information.

Paging

The Visto library supports paging and navigation: It is possible to define a DIV element as page frame and navigate forward and backward between page views in this DIV element. It is even possible to implement onNavigatedTo, onNavigatedFrom and other event methods on views and view models which are automatically called by the framework.

The following code shows how to navigate to the first page in the body HTML element (full page navigation):

define(["exports", "libs/visto"], function(exports, visto) {
	// navigate to the view MainPage of the current package
	visto.navigateTo("MainPage");
	// navigate to the view MainPage of the myPackage package
	visto.navigateTo(["myPackage", "MainPage"]); 
});

To load the sample view as the entry page, the following code can be used in app.js:

require(["libs/visto"], function(visto) {
	visto.navigateTo(["myPackage", "SampleView"]); 
});

See Paging for more information.

Internationalization

The Visto JavaScript Library supports the implementation of multilingual applications. To translate an element you can simply use the data-translate attribute. The attributes defines a key which is looked up in the JSON file from the "languages" directory for the current language and package:

<div data-translate="labelSample"></div>

Because the mechanism also works with KnockoutJS observables, the language can be changed and the whole GUI is immediately changed to the new language. Additionally it is also possible to programmatically read language strings. Check out the page internationalization for more information.

Last edited May 11, 2015 at 8:31 PM by rsuter, version 35

Comments

No comments yet.