Getting Started

Welcome to WebRx! This tutorial will take you through creating a simple application and briefly explain its main concepts. We assume you are familiar with JavaScript, HTML, and CSS.

To get a quick overview, we recommend you skip down to the section titled Setting Up The HTML Page so you can see how to use WebRx straight away.

Then, when you are ready to actually build something, come back and read about Setting Up a Project and installing WebRx.

Setting Up a Project and installing WebRx

This tutorial assumes that you’ve already created a project skeleton in your favorite IDE or Code-Editor. Let’s continue with installing the WebRx Framework.

Depending on the type of project you are working on, there are multiple ways to install WebRx.

NPM Installation

npm install webrx

WebRx and its dependencies will be installed to the following locations:

  • WebRx: <project-folder>/node_modules/webrx/dist
  • RxJS: <project-folder>/node_modules/rx/dist

Bower Installation

bower install WebRx

WebRx and its dependencies will be installed to the following locations:

  • WebRx: <project-folder>/bower_modules/webrx/dist
  • RxJS: <project-folder>/bower_modules/rx/dist

NuGet Installation

PM> Install-Package WebRx

WebRx and its dependencies will be installed to the following locations:

  • WebRx: <project-folder>\content\Scripts
  • RxJS: <project-folder>\content\Scripts

Note: This should be the preferred installation method for developers working with Microsoft Visual Studio.

Manual Installation

If you prefer to work without a package manager you can download the latest WebRx Distribution Archive from here.

Typescript

WebRx is written in Typescript and as such ships with a complete Typescript Definition File which willweb.rx.d.ts get installed alongside WebRxs main script files.

When WebRx is installed using NuGet, this file will be located in <project-folder>\content\Scripts\typings

Setting Up The HTML Page

If you’ve followed along this far, you now have all the libraries, build configuration and tools you need to create amazing JavaScript apps with WebRx. The next thing to do is create the index.html file in the root of your project folder. This example file provides a good template for new WebRx-based apps.

index.html

<!doctype html>
<html>
  <head>
    <title>WebRx</title>
  </head>
  <body>
    <div data-bind="view: main"></div>

    <script src="bower_modules/rx/dist/rx.all.js"></script>
    <script src="bower_modules/webrx/dist/web.rx.js"></script> 
    <script src="js/app.js"></script>
  </body>
</html>

Yes, that’s it. This is the only HTML page in our application. The head of the document is pretty straight forward. So let’s ignore that and proceed to the body.

The lonely div element at the very top of the body defines a view slot for WebRxs router. The view-slot will spring to life when defining our first component in one of the upcoming sections.

Lets now focus on the script tags:

  • First, we have a reference to thatrx.all.js loads the RxJS-Library which is a powerful set of libraries for processing and querying asynchronous data streams.
  • The second script tag loads web.rx.js – the WebRx framework.
  • The third script tag loads app.js which we are about to create in the next section

Note: This example assumes that WebRx and its dependencies have been installed using Bower and therefore the scripts reside inside.<project-folder>/bower_modules/ If you chose one of the other installation methods outlined above you should have no problems correcting the script references accordingly.

Bootstrapping the application

Now, that set up our HTML page it’s time to get things rolling.

Inside your project create a folder js and inside that folder a file named app.js with the following contents:

app.js

wx.applyBindings();

The call to will wx.applyBindings WebRx that is now responsible for controlling the contents of our page via a concept called declarative data-binding. So far our page contains just a single binding, namely the view binding on the sole div element of the body.

You could now navigate to index.html> inside your browser and would see – well, a blank page. Not very exciting. Let’s fix this.

Defining our first Component

In WebRx, user interface elements are composed of view and view-model pairs that are referred to as Components. The view is written with HTML and is rendered into the DOM. The view-model is written with JavaScript and provides data and behavior to the view. WebRxs powerful data binding links the two pieces together allowing changes in your data to be reflected in the view and vice versa. This separation of concerns is great for developer/designer collaboration, maintainability, architectural flexibility and even source control.

Lets now focus on the div element at the very top of the body:

<div data-bind="view: main"></div>

When we’ve invoked in the wx.applyBindings() previous step we basically turned this element into a content placeholder.

In order to bring these placeholders to life we need to accomplish two things:

  • First, we need to create a Component that will provide the content to for the placeholder
  • Next, we need to map the component to a placeholder slot (WebRx supports unlimited optionally nested placeholders per page).

To do that let’s go back to the script we app.js‘ve created in Step 3.

app.js

wx.app.component(hello, {
  viewModel: function() {
    this.firstName = Bart;
    this.lastName = Simpson;
  },
  template: The name is <span data-bind="text: firstName + \ \ + lastName"></span>
});

wx.router.state({
  name: "$",
  views: { main: "hello" }
});

wx.router.reload();

wx.applyBindings();

Let’s examine the final version of the script line by line:

Line 1-7: Here we define a very simple component that goes by the moniker.hello Given a firstName and a lastName property the component will display the resulting full-name.

Even though we’ve now defined a component for our placeholder, it will be still not visible on the page because we haven’t told the framework where to display it. In WebRx it is the Routers responsibility to map components to views. We just have to tell it.

Line 11: This line tells the Router to display the component inhello placeholder whenever the application is main in its default state ($).

Line 14: Here we reload the router after configuring it in the previous step

The result

If you have implemented everything correctly, refreshing your browser windows should yield the following output:

The name is Bart Simpson 

Conclusion

Even though this example like very basic on the surface, it has touched quite a lot of WebRxs core concepts. Throughout the tutorial we’ve learned:

  • How to set up a basic HTML page that hosts our application
  • How to bootstrap the application
  • How to define a basic component consisting of a view-model and a template
  • How to display a component using the Router

Next: Introduction