This is an automated email from the ASF dual-hosted git repository. aharui pushed a commit to branch develop in repository https://gitbox.apache.org/repos/asf/royale-docs.git
commit 0e8ad7717e555c8f794eb3ee9916525c51c2f843 Author: Alex Harui <[email protected]> AuthorDate: Mon Jan 29 12:00:15 2018 -0800 fill out more of tutorial --- .../application-tutorial/build.md | 135 ++++++++++++++++++++- .../application-tutorial/controller.md | 32 +++++ create-an-application/application-tutorial/data.md | 73 ++++++++++- create-an-application/application-tutorial/main.md | 7 +- create-an-application/application-tutorial/view.md | 62 +++++++++- 5 files changed, 300 insertions(+), 9 deletions(-) diff --git a/create-an-application/application-tutorial/build.md b/create-an-application/application-tutorial/build.md index 0e1a001..75ef614 100644 --- a/create-an-application/application-tutorial/build.md +++ b/create-an-application/application-tutorial/build.md @@ -18,6 +18,137 @@ layout: docpage title: Build the application --- -# Building the application +# Build the application -*This information will be available soon.* +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. So the compiler scans all of 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 [...] + +The main MXML file should now look like this: + +```XML +<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"; +xmlns:local="*" +xmlns:js="library://ns.apache.org/royale/express" +> +<fx:Script> +<![CDATA[ + public var commits:Array = []; + public var repos:Array; + public var projectName:String; + + private function setConfig():void + { + repos = configurator.data.repos; + projectName = configurator.data.projectName; + } + + private var currentIndex:int = 0; + + private function fetchCommits():void + { + commitsService.addEventListener("complete", gotCommits); + commitsService.source = repos[currentIndex]; + commitsService.send(); + } + + private function gotCommits(event:Event):void + { + currentIndex++; + commits.concat(commitsService.data.commits); + if (currentIndex < repos.length) + fetchCommits(); + } +]]> +</fx:Script> +<js:HTTPService id="configurator" source="project.json" complete="setConfig();fetchCommits()" /> +<js:HTTPService id="commitsService" source="project.json" complete="setConfig();fetchCommits()" /> + +<js:initialView> + <js:VView> + <js:Label text="{projectName} Commits Log"> + <js:DataGrid id="dg" dataProvider="commits"> + <js:columns> + <js:DataGridColumn label="Date" dataField="date" columnWidth="15"/> + <js:DataGridColumn label="Author" dataField="author" columnWidth="15" /> + <js:DataGridColumn label="Message" dataField="message" columnWidth="70" /> + </js:columns> + </js:DataGrid> + <js:MultilineLabel text="{dg.selectedItem.message}" /> + </js:VView> +</js:initialView> +</js:Application> +``` + +Before we compile this code, there are a few things we want to add. First off, there is 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 changes 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 [...] + +Another thing missing is that we haven't specified the size of the controls. Just like HTML/JS/CSS there are multiple ways to do this. We could have a separate .css file and 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 [...] + +This simple example will look fine if we just set the width and height of the DataGrid and the width of the MultilineLabel, so we will add them directly. You can read the section on Styles to see other ways of setting styles on the View. + +The final code should look like this: + +```XML +<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"; +xmlns:local="*" +xmlns:js="library://ns.apache.org/royale/express" +> +<fx:Script> +<![CDATA[ +[Bindable] +public var commits:Array = []; +public var repos:Array; +[Bindable] +public var projectName:String; + +private function setConfig():void +{ +repos = configurator.data.repos; +projectName = configurator.data.projectName; +} + +private var currentIndex:int = 0; + +private function fetchCommits():void +{ +commitsService.addEventListener("complete", gotCommits); +commitsService.source = repos[currentIndex]; +commitsService.send(); +} + +private function gotCommits(event:Event):void +{ +currentIndex++; +commits = commits.concat(commitsService.data.commits); +if (currentIndex < repos.length) +fetchCommits(); +} +]]> +</fx:Script> +<js:HTTPService id="configurator" source="project.json" complete="setConfig();fetchCommits()" /> +<js:HTTPService id="commitsService" source="project.json" complete="setConfig();fetchCommits()" /> + +<js:initialView> +<js:VView> +<js:Label text="{projectName} Commits Log"> +<js:DataGrid id="dg" dataProvider="commits" width="80%" height="300"> +<js:columns> +<js:DataGridColumn label="Date" dataField="date" columnWidth="15"/> +<js:DataGridColumn label="Author" dataField="author" columnWidth="15" /> +<js:DataGridColumn label="Message" dataField="message" columnWidth="70" /> +</js:columns> +</js:DataGrid> +<js:MultilineLabel text="{dg.selectedItem.message}" width="80%"/> +</js:VView> +</js:initialView> +</js:Application> +``` + +Since we are intersted in JS output, to compile this code, we run: + +``` + js/bin/mxmlc -debug=true GitHubCommitsViewer.mxml +``` + +This should compile without errors. Next, let's see the results. + +{:align="center"} +[Previous Page](create-an-application/application-tutorial/build.html) \| [Next Page](create-an-application/application-tutorial/debug.html) diff --git a/create-an-application/application-tutorial/controller.md b/create-an-application/application-tutorial/controller.md new file mode 100644 index 0000000..1855a61 --- /dev/null +++ b/create-an-application/application-tutorial/controller.md @@ -0,0 +1,32 @@ +--- +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +layout: docpage +title: The 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. It could be used to display comments on a wiki page, or a text messaging conversation, or even some social media discussion. + +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. But when we add localization and filters later, the controller will have something to do. Also, the most of the individual components like DataGrid are themselves implemented in the MVC pattern and the DataGrid has [...] + +Now if there was a reason to share the currently selected commit with other Views then 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. Let's try to compile it and run it. + +{:align="center"} +[Previous Page](create-an-application/application-tutorial/view.html) \| [Next Page](create-an-application/application-tutorial/build.html) diff --git a/create-an-application/application-tutorial/data.md b/create-an-application/application-tutorial/data.md index 60010ee..ff2a486 100644 --- a/create-an-application/application-tutorial/data.md +++ b/create-an-application/application-tutorial/data.md @@ -15,9 +15,76 @@ # limitations under the License. layout: docpage -title: Application design +title: The data model --- -# Application design +# The data model + +Since the goal of this application is to display a list of commits to the Royale GitHub repos, the data the application will work with must include that list of commits. 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, it can be easier to just stick a few variables in the main application file in a script block like this: + +``` +<fx:Script> +<![CDATA[ + public var commits:Array = []; +]]> +</fx:Script> +``` + +But thinking about this a bit more, 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 also: + +```ActionScript + public var repos:Array; + public var projectName:String; +``` + +Next, we need to get the values for these arrays. Let's use a .json file to configure which repos to use and the project name. So create a file that looks like: + +```JSON +{ "projectName": "Apache Royale", + "repos": [ "apache/royale-asjs", "apache/royale-typedefs", "apache/royale-compiler" ] +} +``` +Now we need to add calls that fetch the .json file and then the commits. We can use HTTPService to get the JSON file: + +```XML +<js:HTTPService id="configurator" source="project.json" complete="setConfig();fetchCommits()" /> +``` +The method setConfig() sets the data model variables: + +```ActionScript +private function setConfig():void +{ + repos = configurator.data.repos; + projectName = configurator.data.projectName; +} +``` + +The method fetchCommits() will take the list of repos and calls a separate instance of HTTPServie to get the commits: + +```XML +<js:HTTPService id="commitsService" /> +``` +```ActionScript +private var currentIndex:int = 0; +private function fetchCommits():void +{ + commitsService.addEventListener("complete", gotCommits); + commitsService.source = repos[currentIndex]; + commitsService.send(); +} + +private function gotCommits(event:Event):void +{ + currentIndex++; + commits = commits.concat(commitsService.data.commits); + if (currentIndex < repos.length) + fetchCommits(); +} + +``` + +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) -*This information will be available soon.* diff --git a/create-an-application/application-tutorial/main.md b/create-an-application/application-tutorial/main.md index 842d3c7..0b1106e 100644 --- a/create-an-application/application-tutorial/main.md +++ b/create-an-application/application-tutorial/main.md @@ -24,7 +24,7 @@ This application uses an MXML file as its main file. The file starts with: -``` +```XML <js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"; xmlns:local="*" xmlns:js="library://ns.apache.org/royale/express" @@ -39,3 +39,8 @@ The line: means that the "js" prefix is mapped to the Express set of components. 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.md), there is more than one pattern for creating applications. This example will use the MVC. So, the next step is to create the Model. + + +{:align="center"} +Previous Page \| [Next Page](create-an-application/application-tutorial/data.html) diff --git a/create-an-application/application-tutorial/view.md b/create-an-application/application-tutorial/view.md index 5713dc7..366b503 100644 --- a/create-an-application/application-tutorial/view.md +++ b/create-an-application/application-tutorial/view.md @@ -15,9 +15,65 @@ # limitations under the License. layout: docpage -title: Application maintenance +title: The view --- -# Application maintenance +# The view -*This information will be available soon.* +In an MVC application the View contains the user interface elements that display data and accept user input. For sure, 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. + +The main or initial view of an application is assigned as the "initialView" property of the application. We want our user interface elements to appear vertically so we will use VView as the view. So, we add: + +```XML +<js:initialView> + <js:VView> + </js:VView> +</js:initialView> +``` +Then inside the VView tag we add the DataGrid + +```XML +<js:DataGrid id="dg"> +</js:DataGrid> +``` + +We want to display the date of the commit, who made the commit, and the commit message each in thir own column on each row of the DataGrid. So inside the DataGrid, we add: + +```XML +<js:columns> + <js:DataGridColumn label="Date" dataField="date" columnWidth="15"/> + <js:DataGridColumn label="Author" dataField="author" columnWidth="15" /> + <js:DataGridColumn label="Message" dataField="message" columnWidth="70" /> +</js:columns> +``` + +Oh wait, we should have a label that displays the project name above the DataGrid, so before DataGrid add: + +```XML +<js:Label text="{projectName} Commits Log"> +``` + +Notice how the text of the label is referencing the projectName variable in the Model by wrapping the variable name in curly braces "{}". In Royale, this is known as DataBinding. 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 it c [...] + +```ActionScript +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. To read more about DataBinding see this [section]. + +DataBinding is also a good way to assign the data for the DataGrid to display, so we will add a databinding expression to the DataGrid. + +```XML +<js:DataGrid id="dg" dataProvider="commits"> +``` + +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. + +<js:MultilineLabel text="{dg.selectedItem.message}" /> + +Notice how with DataBinding, we've written very little if any "code" to connect the DataGrid to the MultilineLabel. + +OK, so we've written the Model and now the View. On to the 'C' in MVC, the Controller. + +{:align="center"} +[Previous Page](create-an-application/application-tutorial/data.html) \| [Next Page](create-an-application/application-tutorial/controller.html) -- To stop receiving notification emails like this one, please contact [email protected].
