You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by ca...@apache.org on 2019/12/26 09:11:23 UTC
[royale-docs] branch master updated: adding info to LSO page also
doing some styling
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 aa62785 adding info to LSO page also doing some styling
aa62785 is described below
commit aa62785b3150c054663370932a2a1e6d914194c9
Author: Carlos Rovira <ca...@apache.org>
AuthorDate: Thu Dec 26 10:11:12 2019 +0100
adding info to LSO page also doing some styling
---
.../loading-external-data/localsharedobject.md | 135 ++++++++++++++-------
1 file changed, 92 insertions(+), 43 deletions(-)
diff --git a/features/loading-external-data/localsharedobject.md b/features/loading-external-data/localsharedobject.md
index 295a56a..8729cda 100644
--- a/features/loading-external-data/localsharedobject.md
+++ b/features/loading-external-data/localsharedobject.md
@@ -20,105 +20,160 @@ description: Use LocalSharedObject to store user or session data
permalink: /features/loading-external-data/localsharedobject
---
-# Local Shared Object
+# Local Shared Object (LSO)
Store user data in the equivalent of a cookie
Web browsers often store small amounts of data on a user's computer in a "cookie", a set of one or more name-value pairs in text. This information can be useful for session management and customizing the UI to match the user's needs and interests. Cookies have a bit of a bad name, though, because many applications and websites also use them for tracking user behavior and recording data the application really does not need in order to function.
-Instead of using cookies, your Royale application can use Local Shared Objects to store data on a user's computer. Local Shared Objects
+Instead of using cookies, your Royale application can use Local Shared Objects (LSO) to store data on a user's computer. Local Shared Objects
* can store up to 100 kb of data without asking the user's permission, much more than a cookie (4 kb).
* can store not only text values, but Number, String, Boolean, XML, Date, Array and Object name-value pairs.
* can even store instances of a custom class, if the class is registered using the _RemoteCass_ -metadata tag.
* have whatever name you give them, with the _.sol_ file type
+> Storing data types and instances of a custom class is done thanks to [AMF](features/loading-external-data/amf) enconding used as well in [RemoteObject](features/loading-external-data/remoteobject).
+
+## Implementations
+
+In Apache Royale we have currently two implementations of Local Shared Object:
+
+- **SharedObject**: An emulation class to support the swf based Local Shared Object. This implementation supports AMF encoded content (requires `[RemoteClass]` or `registerClassAlias` before reading and writing to roundtrip instances of custom classes).
+
+- **SharedObjectJSON**: An lighter weight emulation class to support the swf based Local SharedObject support. This implementation does not support AMF encoded content. It is intended for javascript implementations that require persistence, but do not already have the AMF support dependency as part of the application.
+
+Both classes can be found in `MXRoyale` library.
+
## Create and retrieve a Local Shared Object
-You use the same static method _getLocal()_ to create a new Local Shared Object or to retrieve an existing one.
-```
+
+You use the same static method `getLocal()` to create a new Local Shared Object or to retrieve an existing one.
+
+```as3
public static function getLocal(name:String, localPath:String = null, secure:Boolean = false):SharedObject
```
+
The call the method and save the referrence in a variable:
-```
+
+```as3
var myNewLocalSharedObject:SharedObject = SharedObject.getLocal("myNewLocalSharedObject");
```
-Royale looks for an existing myNewLocalSharedObject.sol file on the user's computer. local directory on the user's computer. If it does not find one, Royale creates a new .sol file with that name. It then returns a reference to the file.
-To see if the .sol file has any data (and, therefore, whether it is new), you can query its size:
-```
+Royale looks for an existing `myNewLocalSharedObject.sol` file on the user's computer. local directory on the user's computer. If it does not find one, Royale creates a new `.sol` file with that name. It then returns a reference to the file.
+
+To see if the `.sol` file has any data (and, therefore, whether it is new), you can query its size:
+
+```as3
var myNewLocalSharedObject:SharedObject = SharedObject.getLocal("myNewLocalSharedObject");
if (myNewLocalSharedObject.size > 0)
- {
- trace("Existing Local Shared Object");
- }
- else
- {
- trace("New Local Shared Object");
- }
- ```
-The _getLocal()_ method has three parameters:
-
- * _name_ (required) assigns a name to the Local Shared Object.
- * _localPath_ is optional. You can use it if many components in the same application may be accessing the same Local Shared Object, rather than accessing the object your created in the app.
- * _secure_ is optional. If you create it, future calls to this Local Shared Object must use HTTPS.
+{
+ trace("Existing Local Shared Object");
+}
+else
+{
+ trace("New Local Shared Object");
+}
+```
+
+The `getLocal()` method has three parameters:
+
+| Parameter | Required | Description |
+|-------------- |---------- | ----------------------------------------------------------------------------- |
+| __name__ | Yes | Assigns a name to the Local Shared Object. |
+| __localPath__ | No | You can use it if many components in the same application may be accessing the same Local Shared Object, rather than accessing the object your created in the app. |
+| __secure__ | No | If you create it, future calls to this Local Shared Object must use HTTPS. |
## Access and update Local Shared Object values
-A Local Shared Object can have many attributes. A Local Shared Object for each registered user of your app could include name, role, userID, age and other data your app needs to provide a good user experience. Each attribute is a property of the Local Shared Object's data property. You can read, update, or delete these values. For a Local Shared Object you have created for user Alan Smithee, alansmithee.sol, you can:
+A Local Shared Object can have many attributes. A Local Shared Object for each registered user of your app could include name, role, userID, age and other data your app needs to provide a good user experience. Each attribute is a property of the Local Shared Object's data property. You can read, update, or delete these values. For a Local Shared Object you have created for user __Alan Smithee__, __alansmithee.sol__, you can:
### Read LSO data
+
Create an instance of the Local Shared Object and populate it with the contents of the Local Shared Object on the user's computer.
-``` var so:SharedObject = SharedObject.getLocal("alansmithee.sol");```
+```as3
+var so:SharedObject = SharedObject.getLocal("alansmithee.sol");
+```
#### Get the value of a specific property
+
Once you have read the Local Shared Object, you can get the values of specific properties.
-```
+```as3
var name:String = so.data.name;
var age:int = so.data.age;
```
### Update property values
+
You can update any of the existing values:
-```
+```as3
so.data.name= "John Smith";
so.data.age = 23;
so.data.orderIds = [23456, 24444, 25432];
```
-<!--
-a custom class must be registered and marked serializable using the [RemoteClass] metadata tag
+
+A custom class must be registered and marked serializable using the `[RemoteClass]` metadata tag:
+
+```as3
+package {
+
+ [RemoteClass]
+ public class Address
+ {
+ public function Address(street:String)
+ {
+ this._street = street;
+ }
+
+ private var _street:String;
+
+ public function get street():String
+ {
+ return _street;
+ }
+ }
+}
+```
+
+Then used like this:
+
+```as3
var address:Address = new Address();
address.street = "125 Foo Lane";
so.data.address = address;
--->
+```
### Delete values
You can delete values of specific properties, rather than replacing them.
-```
+```as3
delete so.data.age;
delete so.data.orderIds;
```
## Save a Local Shared Object
-Use the _flush()_ method to immediately write a Local Shared Object to the user's computer.
+Use the `flush()` method to immediately write a Local Shared Object to the user's computer.
-`public function flush(minDiskSpace:int = 0):String`
+```as3
+public function flush(minDiskSpace:int = 0):String
+```
-The _minDiskSpace_ parameter is optional. Add a value to request additional space over 100 kb on the user's computer. If the value is greater than 0, the user sees a dialog box requesting the additional space.
+The `minDiskSpace` parameter is optional. Add a value to request additional space over 100 kb on the user's computer. If the value is greater than 0, the user sees a dialog box requesting the additional space.
-A call to _flush()_ returns either _SharedObjectFlushStatus.PENDING_ or _SharedObjectFlushStatus.FLUSHED_. If the Local Shared Object needs more space than it currently has on the user's computer, the method returns _PENDING_ and presents a dialog box to ask the user to grant more space.
+A call to `flush()` returns either `SharedObjectFlushStatus.PENDING` or `SharedObjectFlushStatus.FLUSHED`. If the Local Shared Object needs more space than it currently has on the user's computer, the method returns `PENDING` and presents a dialog box to ask the user to grant more space.
When the user chooses either "Allow" or "Deny", the response dispatches a _NetStatusEvent.NET_STATUS_ event. Register an event listener to handle this event:
-```
+
+```as3
so.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
```
You can write a "save" function like this:
-```
+
+```as3
private function writeSharedObject():void
{
var so:SharedObject = SharedObject.getLocal("mySO");
@@ -137,15 +192,9 @@ private function writeSharedObject():void
## Delete a Local Shared Object
-Use the _clear()_ method (``` public function clear():void ```) to delete a Local Shared Object and erase its data. If the Local Shared Object's name is "loginInfo", we could clear and delete it like this:
+Use the `clear()` method (``` public function clear():void ```) to delete a Local Shared Object and erase its data. If the Local Shared Object's name is "loginInfo", we could clear and delete it like this:
-```
+```as3
var so:SharedObject = SharedObject.getLocal("loginInfo");
so.clear();
```
-
-
-
-
-
-