You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by ah...@apache.org on 2018/01/31 06:33:35 UTC
[royale-docs] 01/02: first draft of tutorial
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 cfe93ac7b9ffcc144eda2d4d5c888199d6c1da0e
Author: Alex Harui <ah...@apache.org>
AuthorDate: Tue Jan 30 22:25:53 2018 -0800
first draft of tutorial
---
_data/toc.json | 2 +-
create-an-application/application-tutorial.md | 2 +-
.../application-tutorial/build.md | 2 +-
.../application-tutorial/debug.md | 44 ++++++++++
.../application-tutorial/deploy.md | 14 +++-
create-an-application/application-tutorial/main.md | 2 +-
.../application-tutorial/production.md | 57 +++++++++++++
.../application-tutorial/security.md | 11 ++-
.../application-tutorial/value-objects.md | 98 ++++++++++++++++++++++
9 files changed, 223 insertions(+), 9 deletions(-)
diff --git a/_data/toc.json b/_data/toc.json
index 8d07afe..5b130fd 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -36,8 +36,8 @@
{"path" : "create-an-application/application-tutorial/build.md"},
{"path" : "create-an-application/application-tutorial/deploy.md"},
{"path" : "create-an-application/application-tutorial/debug.md"},
- {"path" : "create-an-application/application-tutorial/production.md"},
{"path" : "create-an-application/application-tutorial/security.md"},
+ {"path" : "create-an-application/application-tutorial/production.md"},
{"path" : "create-an-application/application-tutorial/value-objects.md"},
{"path" : "create-an-application/application-tutorial/locales.md"},
{"path" : "create-an-application/application-tutorial/filters.md"},
diff --git a/create-an-application/application-tutorial.md b/create-an-application/application-tutorial.md
index c6424e5..bc8a668 100644
--- a/create-an-application/application-tutorial.md
+++ b/create-an-application/application-tutorial.md
@@ -33,7 +33,7 @@ The first six segments will result in a functional application.
[Build](create-an-application/application-tutorial/build.html) This segment gets the code to compile.
-[Deploy](create-an-application/application-tutorial/deploy.html) This segment discusses how to view the results.
+[Run](create-an-application/application-tutorial/deploy.html) This segment discusses how to view the results.
The next four segments will discuss further improvements needed to make a production-ready version.
diff --git a/create-an-application/application-tutorial/build.md b/create-an-application/application-tutorial/build.md
index e6e7f2e..71b1fbd 100644
--- a/create-an-application/application-tutorial/build.md
+++ b/create-an-application/application-tutorial/build.md
@@ -204,4 +204,4 @@ If you've used NPM to install Royale, you can just run:
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/build.html) \| [Next Page](create-an-application/application-tutorial/debug.html)
+[Previous Page](create-an-application/application-tutorial/controller.html) \| [Next Page](create-an-application/application-tutorial/deploy.html)
diff --git a/create-an-application/application-tutorial/debug.md b/create-an-application/application-tutorial/debug.md
new file mode 100644
index 0000000..398608c
--- /dev/null
+++ b/create-an-application/application-tutorial/debug.md
@@ -0,0 +1,44 @@
+---
+# 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: Debug the application
+---
+
+# Debug the application
+
+If the application built and showed a set of columns but no commit data, then you are probably running a browser that has a tighter security model than some other browsers. Some browsers won't let an application access data from another domain without permission.
+
+But to verify that, or whenever something goes wrong in your application, the first step is to open the console window for your browser. How to do that depends on the browser, but basically, the output JavaScript is going to be executed until it throws an "uncaught exception" and code that was supposed to run after that won't and that will result in lots of things not working.
+
+In one browser, the console said:
+
+```
+Failed to load file:///.../bin/js-debug/project.json: Cross origin requests are only
+ supported for protocol schemes: http, data, chrome, chrome-extension, https.
+```
+
+Because I had simply opened the file from my computer's file viewer in the browser, the browser opened it under the file:/// protocol and wouldn't allow access from my computer to GitHub.
+
+So, to do further testing you will need to set up a web server for the application or copy the application to a web server and run it from there. If you look in the "js-debug" folder, there is a lot of files to copy. You can't just copy the index.html file.
+
+Back to the topic of debugging for a moment. Most browsers also have debuggers with breakpoints. Your application .mxml and .as files have each been turned into a .js file that the browser will let you set breakpoints and step in. Some IDEs support the ability to see your .mxml and .as files in the debugger.
+
+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)
+
diff --git a/create-an-application/application-tutorial/deploy.md b/create-an-application/application-tutorial/deploy.md
index 554bae5..b94cf6a 100644
--- a/create-an-application/application-tutorial/deploy.md
+++ b/create-an-application/application-tutorial/deploy.md
@@ -15,9 +15,17 @@
# limitations under the License.
layout: docpage
-title: Application deployment
+title: Run the application
---
-# Application deployment
+# 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 and in it is a "js-debug" directory.
+
+Inside the "js-debug" directory is an index.html. You can open it in your browser and you should see the list of commits appear.
+
+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)
-*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 0b1106e..2ee1840 100644
--- a/create-an-application/application-tutorial/main.md
+++ b/create-an-application/application-tutorial/main.md
@@ -39,7 +39,7 @@ 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.
+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 pattern. So, the next step is to create the Model.
{:align="center"}
diff --git a/create-an-application/application-tutorial/production.md b/create-an-application/application-tutorial/production.md
new file mode 100644
index 0000000..6a3526a
--- /dev/null
+++ b/create-an-application/application-tutorial/production.md
@@ -0,0 +1,57 @@
+---
+# 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: Making a production version
+---
+
+# Making a production version
+
+The version in the "js-debug" folder is considered a "debug version" or "development version". If you looked at all of the files in the folder or copied them to a web server, you probably noticed there are quite a few, and each takes time to load.
+
+These versions are designed to be more easily debugged. Each source file has an equivalent .js file with nice readable variable and function names. If they are small enough and fast enough, it is perfectly fine to deploy the development version.
+
+A production version will combine just about all of the .js into a single .js file, renaming variables and function names from things like "Application" to just "aa". This is done using the Google Closure Compiler and the results are easier to manage (fewer files to copy) and also should load faster (fewer requests for files and smaller total file sizes).
+
+To create a production version, don't set debug=true. The compiler will still produce the js-debug folder, but then will pass it to the Google Closure Compiler that will generate a production or "release" version in a "js-release" folder. The build process will take longer as the Google compiler crunches through all of the files. There may be additional warnings, and hopefully, no errors. If there is an error, then the production version will probably not run.
+
+So, create a production version by running:
+
+```
+<path to Royale SDK>/royale-asjs/js/bin/mxmlc GitHubCommitsViewer.mxml
+```
+
+If you've used NPM to install Royale, you can just run:
+
+```
+mxmlc GitHubCommitsViewer.mxml
+```
+
+Then if your browser worked when you viewed the js-debug folder you can view the js-release folder, or copy the
+js-release folder to your webserver.
+
+You will probably not see any rows of commits. And if you look in the console, you should see an error that looks like:
+
+```
+TypeError: undefined is not an object (evaluating 'e.Vf.Qf')
+```
+
+Why is the production version not working? Because as the Google Closure Compiler renamed variables, it also renamed variables in the code that fetches fields from the data.
+
+How do you prevent certain variables from being renamed? One way is by not using as many plain objects, especially when those objects come from an external source. If a plain object is used entirely internally, then the Google Closure Compiler can rename all references to a property like "message" to just "mm". Google doesn't know or have a way to know that the objects in this tutorial are coming from a server. There is more than one way to keep Google Closure Compiler from renaming [...]
+
+{:align="center"}
+[Previous Page](create-an-application/application-tutorial/security.html) \| [Next Page](create-an-application/application-tutorial/value-objects.html)
diff --git a/create-an-application/application-tutorial/security.md b/create-an-application/application-tutorial/security.md
index 44e6bb6..c79ba7d 100644
--- a/create-an-application/application-tutorial/security.md
+++ b/create-an-application/application-tutorial/security.md
@@ -18,6 +18,13 @@ layout: docpage
title: Application security
---
-# Secure your application
+# Application security
-*This information will be available soon.*
+There are two sides to security: How do you access something external resource? And, How do you keep certain external resources from accessing your application and the things your application can access. There is a separate section that deals with both topics in more detail, but the most common problem, especially for applications that mainly present data instead of collect data, is how to access an external resource.
+
+It is up the external resource to decide whether you can access it or not. And even if the external resource intends to let others access it, there may be rules and restrictions in order to get permission. If you run into an access problem, look for documentation on "Cross-Origin Resource Sharing" or "CORS".
+
+Fortunately, for this tutorial, GitHub's APIs are very permissive and the application should now show rows of commits if it wasn't when running from file://.
+
+{:align="center"}
+[Previous Page](create-an-application/application-tutorial/debug.html) \| [Next Page](create-an-application/application-tutorial/production.html)
diff --git a/create-an-application/application-tutorial/value-objects.md b/create-an-application/application-tutorial/value-objects.md
new file mode 100644
index 0000000..78ef0c9
--- /dev/null
+++ b/create-an-application/application-tutorial/value-objects.md
@@ -0,0 +1,98 @@
+---
+# 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: Value Objects
+---
+
+# Value Objects
+
+Many servers return JSON which is just a plain object or array often referencing other plain objects and arrays. In ActionScript there are advantages to using something called "data classes" or "value objects" (also sometimes "ValueObjects").
+
+Value Objects tell the compiler that your data has a fixed set of properties of a given type. If you misspell the name of a field in the data, the compiler will catch it. Some IDEs know how to complete the field name as you type it and only offer completions for that data object instead of all strings used in the file.
+
+And, they keep the Google Closure Compiler from renaming references to those fields, and allow you to have changes to the fields detected or ignored by the DataBinding code.
+
+There is more than one way to create a Value Object for JSON objects. This tutorial will use the simplest brute-force technique. There are only three fields we are interested in out of the many fields and nested fields in the GitHub server response. So instead of converting all of those fields or wrapping the JSON object and returning the nested fields, it is easier to just copy the three fields we need.
+
+Many people prefer to keep their Value Objects in a folder/package. For simplicity, we will just create the Value Object in the main "src" folder. It will look like this:
+
+```
+package {
+
+public class LogEntry
+{
+ public var date:String;
+ public var author:String;
+
+ [Bindable("__NoChangeEvent__")]
+ public var message:String;
+}
+}
+```
+
+Notice the use of [Bindable] metadata. This special syntax indicaes to the compiler that there are no DataBinding notifications for the message field. Once it is set, it will not change. We could also specify "message" as a "const" instead of a "var" and set up a constructor with parameters, but constructor parameters are not allowed for anything that wants to be declared in MXML.
+
+Once we have that, we use LogEntry throughout the app. In the conversion loop, we change it to look like this:
+
+```
+ for (var i:int = 0; i < n; i++)
+ {
+ var obj:Object = results[i];
+ var data:LogEntry = new LogEntry();
+ 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);
+ }
+```
+
+And in the DataBinding to the MultilineLabel, we must also declare the type of the object in the Array so that the compilers know that the message property is from a LogEntry and should not be changed.
+
+```
+<js:MultilineLabel text="{LogEntry(commits[dg.selectedIndex]).message}" width="600" />
+```
+
+Compiling with these changes will eliminate the last warning that assignment to some variable cannot be detected since the [Bindable] metadata has instructed the compiler that the "message" property will not change at runtime. But it still won't work. That's because in the conversion loop, the JSON objects are also plain objects, and the Google Closure Compiler is going to rename expressions like obj.commit.author.name to things like "o.b.c.d".
+
+Now we could define more Value Objects like LogEntry for these GitHub API data types, and if we do that, we should share it with everyone else (as of this writing we are seeking permission to do so), but given that we only have to tackle these JSON object in one place in the code and thus presents a good opporunity to show another technique to deal with renaming.
+
+Another way to prevent the Google Closure Compiler from renaming variables is to use bracket notation. In order to use the fewest number of bracket notations (because they are prone to mispelling) we will refactor the code a bit (which should also make it run a bit faster). So the conversion loop will now look like this:
+
+```
+ for (var i:int = 0; i < n; i++)
+ {
+ var obj:Object = results[i];
+ var data:LogEntry = new LogEntry();
+ var commitObj:Object = obj["commit"];
+ var authorObj:Object = commitObj["author"];
+ data.author = authorObj["name"];
+ // clip date after yyyy-mm-dd
+ data.date = authorObj["date"].substr(0, 10);
+ data.message = commitObj.message;
+ commits.push(data);
+ }
+```
+
+This should now work. And if you look in the js-release folder, you now have a single .js file to deploy (along with the .css, .json and .html file). The .js.map file is there in case you have to debug this optimized .js file. If you don't deploy it, anyone trying to reverse-engineer your application is in for quite a challenge!
+
+If you weren't really following the steps and just skimming, the final result is available [here](create-an-application/application-tutorial/example/index.html){:target='_blank'}
+
+This concludes the set of steps required to create a not-so-simple application and put it into production. The next set of steps add additional features to the application.
+
+{:align="center"}
+[Previous Page](create-an-application/application-tutorial/production.html) \| [Next Page](create-an-application/application-tutorial/locales.html)
--
To stop receiving notification emails like this one, please contact
aharui@apache.org.