This is an automated email from the ASF dual-hosted git repository.
carlosrovira pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 017e229 update application tutorial to use permalinks and revise text
to enhance visuals to make it easier to read
017e229 is described below
commit 017e229e62a296bb5f192e44889297b5abb252c4
Author: Carlos Rovira <[email protected]>
AuthorDate: Tue Sep 3 20:20:36 2019 +0200
update application tutorial to use permalinks and revise text to enhance
visuals to make it easier to read
---
create-an-application/application-tutorial.md | 23 ++--
.../application-tutorial/build.md | 147 +++++++++++----------
.../application-tutorial/controller.md | 14 +-
.../{data.md => data-model.md} | 69 +++++-----
.../application-tutorial/debug.md | 2 +-
.../application-tutorial/deploy.md | 16 ++-
create-an-application/application-tutorial/main.md | 12 +-
create-an-application/application-tutorial/view.md | 32 ++---
8 files changed, 172 insertions(+), 143 deletions(-)
diff --git a/create-an-application/application-tutorial.md
b/create-an-application/application-tutorial.md
index c7a7044..0a0d37b 100644
--- a/create-an-application/application-tutorial.md
+++ b/create-an-application/application-tutorial.md
@@ -20,33 +20,37 @@ description: A complete tutorial on how to build a simple
Royale application
permalink: /create-an-application/application-tutorial
---
-# Tutorial - GitHub Commit Log Application
+# GitHub Commit Log Application Tutorial
A complete tutorial on how to build a simple Royale application
This tutorial will take you through building an app that displays the commit
logs for the Royale project by connecting to the
[GitHub](https://github.com){:target='_blank'} servers.
-See the running example:
+At the end of this tutorial we'll get the following:
<iframe frameborder="no" border="0" marginwidth="0" marginheight="0"
width="100%" height="350"
src="assets/application-tutorial/index.html"></iframe>
-The steps in this tutorial start with a blank file and walk you through what
to add and why. Or you can get the complete source
[here](https://github.com/apache/royale-asjs/blob/develop/examples/express/GitHubCommitLogViewer){:target='_blank'}.
Note that Royale examples are set up to build with [Apache
Maven](https://maven.apache.org){:target='_blank'} so the folder structure
reflects that. There are other ways to organize your code.
+> This example uses [Basic](component-sets/basic) components to build the
interface. This components are build with very basic look and feel. For a more
advanced set with look and feel you should use instead
[Jewel](component-sets/jewel) or **MDL** sets
+
+The steps in this tutorial start with a blank file and walk you through what
to add and why. Or you can get the complete source
[here](https://github.com/apache/royale-asjs/blob/develop/examples/express/GitHubCommitLogViewer){:target='_blank'}.
+
+> Note that Royale examples are set up to build with [Apache
Maven](https://maven.apache.org){:target='_blank'} so the folder structure
reflects that. There are other ways to organize your code.
The first six segments will result in a functional application.
-1. [The Main Application
File](create-an-application/application-tutorial/main.html) This segment starts
filling in the main application file.
+1. [The Main Application
File](create-an-application/application-tutorial/main) This segment starts
filling in the main application file.
-2. [Data Model](create-an-application/application-tutorial/data.html) This
segment adds the code that manages the data in the application, including
network access to GitHub.
+2. [Data Model](create-an-application/application-tutorial/data-model) This
segment adds the code that manages the data in the application, including
network access to GitHub.
-3. [View (User
Interface)](create-an-application/application-tutorial/view.html) This segment
builds out the initial user interface.
+3. [View (User Interface)](create-an-application/application-tutorial/view)
This segment builds out the initial user interface.
-4. [Controller](create-an-application/application-tutorial/controller.html)
This segment hooks up the user interface to code that responds to the user's
interactions.
+4. [Controller](create-an-application/application-tutorial/controller) This
segment hooks up the user interface to code that responds to the user's
interactions.
-5. [Build](create-an-application/application-tutorial/build.html) This segment
gets the code to compile.
+5. [Build](create-an-application/application-tutorial/build) This segment gets
the code to compile.
-6. [Run](create-an-application/application-tutorial/deploy.html) This segment
discusses how to view the results.
+6. [Run](create-an-application/application-tutorial/deploy) This segment
discusses how to view the results.
The next four segments will discuss further improvements needed to make a
production-ready version.
@@ -69,4 +73,3 @@ The remaining segments will discuss further improvements
needed to add additiona
14. [Routing](create-an-application/application-tutorial/routing.html) This
segment shows how to map URL parameters to different initial values in the
application, and _vice versa_.
This is going to be fun!
-
diff --git a/create-an-application/application-tutorial/build.md
b/create-an-application/application-tutorial/build.md
index 8fcfc11..2a6b9ba 100644
--- a/create-an-application/application-tutorial/build.md
+++ b/create-an-application/application-tutorial/build.md
@@ -16,98 +16,99 @@
layout: docpage
title: Build the application
-description: building the application
+description: Building the application
+permalink: /create-an-application/application-tutorial/build
---
# Build the application
-building the application
+Building the application
-In many other HTML/JS/CSS development models, you write the JS and then just
view it in the browser. Royale uses a compiler to convert your MXML and
ActionScript code into HTML/JS/CSS. Why? Because there is a philosophy that the
sooner you catch a bug, the less expensive it is to fix it. The compiler scans
your source code to make sure that it makes sense. The compiler checks that
there aren't typos in property names, that if you are expecting a String you'll
probably get one, and more.
+In many other *HTML/JS/CSS* development models, you write the *JS* and then
just view it in the browser. Royale uses a compiler to convert your *MXML* and
*ActionScript* code into *HTML/JS/CSS*. Why? Because there is a philosophy that
the sooner you catch a bug, the less expensive it is to fix it. The compiler
scans your source code to make sure that it makes sense. The compiler checks
that there aren't typos in property names, that if you are expecting a `String`
you'll probably get one [...]
-The main MXML file should now look like this:
+The main *MXML* file should now look like this:
```mxml
<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009";
-xmlns:local="*"
-xmlns:js="library://ns.apache.org/royale/express"
-initialize="addEventListener('dataReady',
dataReadyHandler);configurator.send()"
->
-<fx:Script>
-<![CDATA[
- import org.apache.royale.collections.ArrayList;
- import org.apache.royale.events.Event;
-
- public const commits:Array = [];
- public var repos:Array;
- public var projectName:String;
-
- private function setConfig():void
- {
- repos = configurator.json.repos;
- projectName = configurator.json.projectName;
- }
-
- private var currentIndex:int = 0;
-
- private function fetchCommits():void
- {
- commitsService.addEventListener("complete", gotCommits);
- commitsService.url = "https://api.github.com/repos/"; +
repos[currentIndex] + "/commits";
- commitsService.send();
- }
+ xmlns:local="*"
+ xmlns:js="library://ns.apache.org/royale/express"
+ initialize="addEventListener('dataReady',
dataReadyHandler);configurator.send()">
+ <fx:Script>
+ <![CDATA[
+ import org.apache.royale.collections.ArrayList;
+ import org.apache.royale.events.Event;
+
+ public const commits:Array = [];
+ public var repos:Array;
+ public var projectName:String;
+
+ private function setConfig():void
+ {
+ repos = configurator.json.repos;
+ projectName = configurator.json.projectName;
+ }
- private function gotCommits(event:Event):void
- {
- currentIndex++;
- var results:Array = commitsService.json as Array;
- var n:int = results.length;
- for (var i:int = 0; i < n; i++)
+ private var currentIndex:int = 0;
+
+ private function fetchCommits():void
{
- var obj:Object = results[i];
- var data:Object = {};
- data.author = obj.commit.author.name;
- // clip date after yyyy-mm-dd
- data.date = obj.commit.author.date.substr(0, 10);
- data.message = obj.commit.message;
- commits.push(data);
+ commitsService.addEventListener("complete", gotCommits);
+ commitsService.url = "https://api.github.com/repos/"; +
repos[currentIndex] + "/commits";
+ commitsService.send();
}
- if (currentIndex < repos.length)
- fetchCommits();
- else
- dispatchEvent(new Event("dataReady"));
- }
- private function dataReadyHandler(event:Event):void
- {
- dg.dataProvider = new ArrayList(commits);
- }
+ private function gotCommits(event:Event):void
+ {
+ currentIndex++;
+ var results:Array = commitsService.json as Array;
+ var n:int = results.length;
+ for (var i:int = 0; i < n; i++)
+ {
+ var obj:Object = results[i];
+ var data:Object = {};
+ data.author = obj.commit.author.name;
+ // clip date after yyyy-mm-dd
+ data.date = obj.commit.author.date.substr(0, 10);
+ data.message = obj.commit.message;
+ commits.push(data);
+ }
+ if (currentIndex < repos.length)
+ fetchCommits();
+ else
+ dispatchEvent(new Event("dataReady"));
+ }
-]]>
-</fx:Script>
-<js:HTTPService id="configurator" url="project.json"
complete="setConfig();fetchCommits()" />
-<js:HTTPService id="commitsService" />
+ private function dataReadyHandler(event:Event):void
+ {
+ dg.dataProvider = new ArrayList(commits);
+ }
-<js:initialView>
- <js:VView>
- <js:Label text="{projectName} Commits Log"/>
- <js:DataGrid id="dg">
- <js:columns>
- <js:DataGridColumn label="Date" dataField="date"/>
- <js:DataGridColumn label="Author" dataField="author"/>
- <js:DataGridColumn label="Message" dataField="message"/>
- </js:columns>
- </js:DataGrid>
- <js:Label text="Selected Message:"/>
- <js:MultilineLabel text="{commits[dg.selectedIndex].message}" />
- </js:VView>
-</js:initialView>
+ ]]>
+ </fx:Script>
+
+ <js:HTTPService id="configurator" url="project.json"
complete="setConfig();fetchCommits()" />
+ <js:HTTPService id="commitsService" />
+
+ <js:initialView>
+ <js:VView>
+ <js:Label text="{projectName} Commits Log"/>
+ <js:DataGrid id="dg">
+ <js:columns>
+ <js:DataGridColumn label="Date" dataField="date"/>
+ <js:DataGridColumn label="Author" dataField="author"/>
+ <js:DataGridColumn label="Message" dataField="message"/>
+ </js:columns>
+ </js:DataGrid>
+ <js:Label text="Selected Message:"/>
+ <js:MultilineLabel text="{commits[dg.selectedIndex].message}" />
+ </js:VView>
+ </js:initialView>
</js:Application>
```
Before we compile this code, there are a few things we want to add.
-First, there is so far no way to know if a "var" has changed. So we want to
tell the compiler to convert the var into a get/set property so we can detect
changes. Otherwise, you will get a warning that assignment to some variable
cannot be detected. In Royale, this is done via MetaData. Metadata consists of
square brackets "[]" which contain a tag and some attributes. The compiler
knows to act on some MetaData. Other MetaData can be compiled into the code and
used at runtime. To convert [...]
+First, there is so far no way to know if a variable has changed. So we want to
tell the compiler to convert the var into a get/set property so we can detect
changes. Otherwise, you will get a warning that assignment to some variable
cannot be detected. In Royale, this is done via
[Metadata](features/as3/metadata). Metadata consists of square brackets `[]`
which contain a tag and some attributes. The compiler knows to act on some
MetaData. Other MetaData can be compiled into the code and [...]
Another thing missing is that we haven't specified the size of the controls.
As with HTML/JS/CSS, there are several ways to do this. We could have a
separate .css file, specify styles there and assign class names in the MXML
tags. That allows the CSS to be tweaked without recompiling so you can just
refresh the browser and see changes; but in Royale, the CSS file is actually
generated by the compiler from the CSS file in your source code and CSS files
in the libraries you used. So if you [...]
@@ -205,4 +206,4 @@ If you've used
[NPM](https://www.npmjs.com/){:target='_blank'} to install Royale
This should compile with one warning. We will ignore that for now and fix it
later. Next, let's see the results.
{:align="center"}
-[Previous Page](create-an-application/application-tutorial/controller.html) \|
[Next Page](create-an-application/application-tutorial/deploy.html)
+[Previous Page](create-an-application/application-tutorial/controller) \|
[Next Page](create-an-application/application-tutorial/deploy)
diff --git a/create-an-application/application-tutorial/controller.md
b/create-an-application/application-tutorial/controller.md
index 7a4ae48..b7cf4e3 100644
--- a/create-an-application/application-tutorial/controller.md
+++ b/create-an-application/application-tutorial/controller.md
@@ -16,17 +16,21 @@
layout: docpage
title: The controller
+description: Watching events from the View and updating the Model
+permalink: /create-an-application/application-tutorial/controller
---
# The controller
-The controller is the code that watches for events from the View and updates
the Model. Why separate that out? Because that way a View can be reused in
other applications. Our View right now is pretty generic and could be used to
display comments on a wiki page, or a text messaging conversation, or even some
social media discussion.
+Watching events from the View and updating the Model
-Right now, the View's only interaction (other than scrolling through the list
of commits) is selecting a commit so you can see any longer commit message in
the MultilineView. That doesn't really update the model, so this application's
controller currently has nothing to do. Also, the most of the individual
components like DataGrid are themselves implemented in the MVC pattern and the
DataGrid has a controller that handles selection and updating the selectdItem
property. But when we add l [...]
+The controller is the code that watches for events from the View and updates
the Model. Why separate that out? Because that way a View can be reused in
other applications. Our View right now is pretty generic and could be used to
display comments on a wiki page, or a text messaging conversation, or even some
social media discussion.
-If there were a reason to share the currently selected commit with other
Views, the Model could be extended to have a "currentCommit" field and then the
controller would watch for DataGrid selection changes and update the model.
+Right now, the View's only interaction (other than scrolling through the list
of commits) is selecting a commit so you can see any longer commit message in
the `MultilineLabel`. That doesn't really update the model, so this
application's controller currently has nothing to do. Also, the most of the
individual components like `DataGrid` are themselves implemented in the
[MVC](https://en.wikipedia.org/wiki/Model–view–controller){:target='_blank'}
pattern and the `DataGrid` has a controller [...]
-So, nothing to do here for now. Let's try to compile and run our application.
+If there were a reason to share the currently selected commit with other
Views, the Model could be extended to have a `currentCommit` field and then the
controller would watch for `DataGrid` selection changes and update the model.
+
+So, nothing to do here for now. Let's try to compile and run our application.
{:align="center"}
-[Previous Page](create-an-application/application-tutorial/view.html) \| [Next
Page](create-an-application/application-tutorial/build.html)
+[Previous Page](create-an-application/application-tutorial/view) \| [Next
Page](create-an-application/application-tutorial/build)
diff --git a/create-an-application/application-tutorial/data.md
b/create-an-application/application-tutorial/data-model.md
similarity index 55%
rename from create-an-application/application-tutorial/data.md
rename to create-an-application/application-tutorial/data-model.md
index 1feac21..1550523 100644
--- a/create-an-application/application-tutorial/data.md
+++ b/create-an-application/application-tutorial/data-model.md
@@ -16,13 +16,17 @@
layout: docpage
title: The data model
+description: Abstract model that organizes elements of data for easy use in
the application
+permalink: /create-an-application/application-tutorial/data-model
---
# The data model
+Abstract model that organizes elements of data for easy use in the application
+
Since the goal of this application is to display a list of commits to the
Royale GitHub repositories (repos), the data the application will work with
must include that list of commits. The application will query GitHub for the
information, place what GitHub provides in a data structure, and then connect
that data structure to components in the user interface that can display it.
-For large projects, the model is often built in a separate class and source
file so it can be separately developed, documented, and maintained (maybe by
other team members). But to get something up quickly, we are going to just
stick a few variables in the main application file in a script block.
+> For large projects, the model is often built in a separate class and source
file so it can be separately developed, documented, and maintained (maybe by
other team members). But to get something up quickly, we are going to just
stick a few variables in the main application file in a script block.
First we create the data structure, in this case an array, to hold the
information we get from GitHub:
@@ -34,28 +38,30 @@ First we create the data structure, in this case an array,
to hold the informati
</fx:Script>
```
-It might be nice to not hard-code which repos we use to get the commits so
that other projects can use this app. So let's add variables to hold
information about the project and repositories we are using:
+It might be nice to not hard-code which repos we use to get the commits so
that other projects can use this app. So let's add variables to hold
information about the **project** and **repositories** we are using:
```as3
- public var repos:Array;
- public var projectName:String;
+public var repos:Array;
+public var projectName:String;
```
-Next, we need to get the values for these arrays. Let's use a
[JSON](https://www.json.org){:target='_blank'} file, called "project.json", to
configure which repos to use and the project name. The file contents look like:
+Next, we need to get the values for these arrays. Let's use a
[JSON](https://www.json.org){:target='_blank'} file, called `project.json`, to
configure which repos to use and the project name. The file contents look like:
```json
-{ "projectName": "Apache Royale",
+{
+ "projectName": "Apache Royale",
"repos": [ "apache/royale-asjs", "apache/royale-typedefs",
"apache/royale-compiler" ]
}
```
+
You can download this file from
[here](https://github.com/apache/royale-asjs/blob/develop/examples/express/GitHubCommitLogViewer/src/main/resources/project.json){:target='_blank'}.
-Now we need to add calls that fetch the .json file and then the information
about the commits. We can use HTTPService to get the JSON file:
+Now we need to add calls that fetch the .json file and then the information
about the commits. We can use
[HTTPService](https://royale.apache.org/asdoc/index.html#!org.apache.royale.net/HTTPService){:target='_blank'}
(from the Network SWC library) to get the **JSON** file:
```mxml
<js:HTTPService id="configurator" url="project.json"
complete="setConfig();fetchCommits()" />
```
-The method setConfig() sets the data model variables:
+The method `setConfig()` sets the data model variables:
```as3
private function setConfig():void
@@ -65,7 +71,7 @@ private function setConfig():void
}
```
-The method fetchCommits() takes the list of repos and calls a separate
instance of HTTPService to get information about the commits:
+The method `fetchCommits()` takes the list of repos and calls a separate
instance of `HTTPService` to get information about the commits:
```mxml
<js:HTTPService id="commitsService" />
@@ -77,35 +83,34 @@ import org.apache.royale.events.Event;
private var currentIndex:int = 0;
private function fetchCommits():void
{
- commitsService.addEventListener("complete", gotCommits);
- commitsService.source = repos[currentIndex];
- commitsService.send();
+ commitsService.addEventListener("complete", gotCommits);
+ commitsService.source = repos[currentIndex];
+ commitsService.send();
}
private function gotCommits(event:Event):void
{
- currentIndex++;
- var results:Array = commitsService.json as Array;
- var n:int = results.length;
- for (var i:int = 0; i < n; i++)
- {
- var obj:Object = results[i];
- var data:Object = {};
- data.author = obj.commit.author.name;
- // clip date after yyyy-mm-dd
- data.date = obj.commit.author.date.substr(0, 10);
- data.message = obj.commit.message;
- commits.push(data);
- }
- if (currentIndex < repos.length)
- fetchCommits();
- else
- dispatchEvent(new Event("dataReady"));
+ currentIndex++;
+ var results:Array = commitsService.json as Array;
+ var n:int = results.length;
+ for (var i:int = 0; i < n; i++)
+ {
+ var obj:Object = results[i];
+ var data:Object = {};
+ data.author = obj.commit.author.name;
+ // clip date after yyyy-mm-dd
+ data.date = obj.commit.author.date.substr(0, 10);
+ data.message = obj.commit.message;
+ commits.push(data);
+ }
+ if (currentIndex < repos.length)
+ fetchCommits();
+ else
+ dispatchEvent(new Event("dataReady"));
}
-
```
-And, of course, we have to tell the service to go fetch the configuration
file, so we add an "initialize" event handler to the Application tag to have
the HTTPService send the request for the JSON file once the application is
ready to receive the response.
+And, of course, we have to tell the service to go fetch the configuration
file, so we add an `initialize` event handler to the `Application` tag to have
the `HTTPService` send the request for the **JSON** file once the application
is ready to receive the response.
```mxml
initialize="configurator.send()"
@@ -114,5 +119,5 @@ initialize="configurator.send()"
Now if you build and run this, nothing will show up. So now let's go create
the view (user interface).
{:align="center"}
-[Previous Page](create-an-application/application-tutorial/main.html) \| [Next
Page](create-an-application/application-tutorial/view.html)
+[Previous Page](create-an-application/application-tutorial/main) \| [Next
Page](create-an-application/application-tutorial/view)
diff --git a/create-an-application/application-tutorial/debug.md
b/create-an-application/application-tutorial/debug.md
index 4b02bb2..8b8acf4 100644
--- a/create-an-application/application-tutorial/debug.md
+++ b/create-an-application/application-tutorial/debug.md
@@ -40,5 +40,5 @@ Back to the topic of debugging for a moment. Most browsers
also have debuggers w
Anyway, to get this application to access GitHub, we have to make the
application available on a web server and learn a bit about security.
{:align="center"}
-[Previous Page](create-an-application/application-tutorial/deploy.html) \|
[Next Page](create-an-application/application-tutorial/security.html)
+[Previous Page](create-an-application/application-tutorial/deploy) \| [Next
Page](create-an-application/application-tutorial/security.html)
diff --git a/create-an-application/application-tutorial/deploy.md
b/create-an-application/application-tutorial/deploy.md
index 2cd8914..deed671 100644
--- a/create-an-application/application-tutorial/deploy.md
+++ b/create-an-application/application-tutorial/deploy.md
@@ -16,16 +16,26 @@
layout: docpage
title: Run the application
+description: Running the application in a browser
+permalink: /create-an-application/application-tutorial/deploy
---
# Run the application
-Assuming you followed the typical directory and file pattern, and the MXML
file was in a "src" directory, next to the "src" directory should be a "bin"
directory with a "js-debug" directory inside it.
+Running the application in a browser
-Inside the "js-debug" directory is an index.html file. You can open it in your
browser and you should see the list of commits appear.
+Assuming you followed the typical directory and file pattern, and the MXML
file was in a `src` directory, next to the `src` directory should be a `bin`
directory with a `js-debug` directory inside it.
+
+Inside the `js-debug` directory is an `index.html` file. You can open it in
your browser and you should see the list of commits appear.
+
+You should see something like this:
+
+<iframe frameborder="no" border="0" marginwidth="0" marginheight="0"
+width="100%" height="350"
+src="assets/application-tutorial/index.html"></iframe>
Or maybe the commits won't appear. In fact, many browsers will not run this
app successfully. Let's figure out why.
{:align="center"}
-[Previous Page](create-an-application/application-tutorial/build.html) \|
[Next Page](create-an-application/application-tutorial/debug.html)
+[Previous Page](create-an-application/application-tutorial/build) \| [Next
Page](create-an-application/application-tutorial/debug.html)
diff --git a/create-an-application/application-tutorial/main.md
b/create-an-application/application-tutorial/main.md
index fcdc056..75bcac0 100644
--- a/create-an-application/application-tutorial/main.md
+++ b/create-an-application/application-tutorial/main.md
@@ -16,11 +16,15 @@
layout: docpage
title: The main application file
+description: The file that serves as the entry point of your application
+permalink: /create-an-application/application-tutorial/main
---
# The main application file
-This application uses an MXML file as its main file.
+The file that serves as the entry point of your application
+
+This application uses an [MXML](features/mxml) file as its main file.
The file starts with:
@@ -37,9 +41,9 @@ The line:
xmlns:js="library://ns.apache.org/royale/express"
```
-means that the "js" prefix is mapped to the Express set of
[components](user-interface/components.html). The Express set is designed for
rapid prototyping and proofs-of-concepts and is not optimized for size and
performance. Applications built with the Express components can still be
deployed in production environments if the size and performance is acceptable,
which it often is.
+means that the `js` prefix is mapped to the Express set of
[components](user-interface/components.html). The Express set is designed for
rapid prototyping and proofs-of-concepts and is not optimized for size and
performance. Applications built with the Express components can still be
deployed in production environments if the size and performance is acceptable,
which it often is.
-As mentioned in [Application
structure](create-an-application/application-structure), there is more than one
pattern for creating applications. This example will use the MVC pattern. So,
the next step is to create the Model.
+As mentioned in [Application
structure](create-an-application/application-structure), there is more than one
pattern for creating applications. This example will use the [MVC
pattern](https://en.wikipedia.org/wiki/Model–view–controller){:target='_blank'}.
So, the next step is to create the Model.
{:align="center"}
-\| [Next Page](create-an-application/application-tutorial/data.html)
+\| [Next Page](create-an-application/application-tutorial/data-model)
diff --git a/create-an-application/application-tutorial/view.md
b/create-an-application/application-tutorial/view.md
index cb7d1ba..c135a85 100644
--- a/create-an-application/application-tutorial/view.md
+++ b/create-an-application/application-tutorial/view.md
@@ -16,13 +16,17 @@
layout: docpage
title: The view
+description: Contains the user interface elements that display data and accept
user input
+permalink: /create-an-application/application-tutorial/view
---
# The view
-In an MVC application the View contains the user interface elements that
display data and accept user input. We want a way to display the list of
commits and also some useful information about those commits. In Royale a
popular way to do that is with a DataGrid.
+Contains the user interface elements that display data and accept user input
-The main or initial view of an application is identified as its "initialView"
property. We want our user interface elements to appear vertically so we use
VView as the view:
+In an
[MVC](https://en.wikipedia.org/wiki/Model–view–controller){:target='_blank'}
application the **View** contains the user interface elements that display data
and accept user input. We want a way to display the list of commits and also
some useful information about those commits. In Royale a popular way to do that
is with a
[DataGrid](https://royale.apache.org/asdoc/index.html#!org.apache.royale.html/DataGrid){:target='_blank'}.
+
+The main or initial view of an application is identified as its `initialView`
property. We want our user interface elements to appear vertically so we use
[VView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.express/VView){:target='_blank'}
as the view:
```mxml
<js:initialView>
@@ -37,7 +41,7 @@ Inside the VView tag we add the DataGrid
</js:DataGrid>
```
-We want to display the date of the commit, who made the commit, and the commit
message, each in their own column on each row of the DataGrid. So inside the
DataGrid, we add:
+We want to display the date of the commit, who made the commit, and the commit
message, each in their own column on each row of the `DataGrid`. So inside the
`DataGrid`, we add:
```mxml
<js:columns>
@@ -47,13 +51,13 @@ We want to display the date of the commit, who made the
commit, and the commit m
</js:columns>
```
-Oh wait, we should have a label that displays the project name above the
DataGrid, so before DataGrid add:
+Oh wait, we should have a label that displays the project name above the
`DataGrid`, so before `DataGrid` add:
```mxml
<js:Label text="{projectName} Commits Log"/>
```
-Notice how the text of the label uses the projectName variable in the Model by
wrapping the variable name in curly braces "{}". In Royale, this is known as
Data Binding. When the compiler sees curly braces in MXML attribute values, it
generates code that sets the destination property (in this case, the Label's
"text" property) to the value of the expression in the curly braces and also
adds code that detects changes to that property and updates the destination
property if the source val [...]
+Notice how the text of the label uses the `projectName` variable in the Model
by wrapping the variable name in curly braces `{}`. In Royale, this is known as
[Data binding](features/data-binding). When the compiler sees curly braces in
MXML attribute values, it generates code that sets the destination property (in
this case, the Label's `text` property) to the value of the expression in the
curly braces and also adds code that detects changes to that property and
updates the destination [...]
```as3
myLabel.text = projectName;
@@ -61,21 +65,19 @@ myLabel.text = projectName;
And we'd also have to write change detection code if the value could change at
runtime (which it doesn't in this case).
-See more about what this powerful feature can do for you on this page: [Data
binding](features/data-binding).
-
-Also, a commit message might be too long to read in a row of a DataGrid so we
will add a place to display the longer message of a selected commit.
+Also, a commit message might be too long to read in a row of a `DataGrid` so
we will add a place to display the longer message of a selected commit.
```mxml
<js:MultilineLabel text="{commits[dg.selectedIndex].message}" />
```
-Notice how with data binding, we've written very little "code" to connect the
DataGrid to the MultilineLabel.
+Notice how with *data binding*, we've written very little code to connect the
`DataGrid` to the
[MultilineLabel](https://royale.apache.org/asdoc/index.html#!org.apache.royale.html/MultilineLabel){:target='_blank'}.
-We could use data binding to connect the commits array to the DataGrid, but it
turns out the commits array is initialized to an empty array at startup and the
commits variable is never assigned a different array so it never changes its
value. Only the contents of the thing it references change. So data binding
only detects changes in the expression, not changes to internal things
referenced by the expression.
+We could use *data binding* to connect the commits array to the `DataGrid`,
but it turns out the commits array is initialized to an empty array at startup
and the commits variable is never assigned a different array so it never
changes its value. Only the contents of the thing it references change. So
*data binding* only detects changes in the expression, not changes to internal
things referenced by the expression.
-It is possible to create something other than an Array that will dispatch
change events so data binding will react, but due to the way the commits array
is populated, that might result in updating the view for every commit, which
isn't necessary (it might make a cool visual effect as rows appear, though).
There are many other ways to hook up the commits array to the DataGrid, but for
this case, we will listen for a dataReady event from the data model and assign
the commits array then.
+It is possible to create something other than an Array that will dispatch
change events so *data binding* will react, but due to the way the commits
array is populated, that might result in updating the view for every commit
which isn't necessary (it might make a cool visual effect as rows appear,
though). There are many other ways to hook up the commits array to the
`DataGrid`, but for this case, we will listen for a `dataReady` event from the
data model and assign the commits array then.
-In the script block we add a handler for the dataReady event.
+In the script block we add a handler for the `dataReady` event.
```as3
import org.apache.royale.collections.ArrayList;
@@ -86,13 +88,13 @@ private function dataReadyHandler(event:Event):void
}
```
-In the initialize handler, we add a listener for the dataReady event:
+In the `initialize` handler, we add a listener for the `dataReady` event:
```as3
addEventListener('dataReady', dataReadyHandler);
```
-OK, so we've written the Model and now the View. On to the 'C' in MVC, the
Controller.
+OK, so we've written the **Model** and now the **View**. On to the 'C' in
[MVC](https://en.wikipedia.org/wiki/Model–view–controller){:target='_blank'},
the **Controller**.
{:align="center"}
-[Previous Page](create-an-application/application-tutorial/data.html) \| [Next
Page](create-an-application/application-tutorial/controller.html)
+[Previous Page](create-an-application/application-tutorial/data-model) \|
[Next Page](create-an-application/application-tutorial/controller)
