My Simple WebStorage Tutorial
This is not intended to be an end-all-be-all for WebStorage use. I am writting this because I spent over an hour last night trying to figure out how to make my app save its data between sessions using the WebStorage object. The information is out there but I could find no simple complete example or tutorial and had to piece it together from multiple threads.
I have also provided a capx file of a sample program I wrote for this tutorial. It simply reports the values of MyGameData and MyWebStorageData and allows you to see it updating or reset its values with button clicks. You can also shut down the instance and return to see the data still there (well it was actually just repopulated like magic...)
The first thing to bear in mind when working with WebStorage is that there are two types of storage options:
Local - Stores the data into a cookie within the specific browser it is accessed from. I do not believe these local storage cookies are set by default to be wiped when cookies are purged but I could be wrong, not the topic of this tutorial.
Session - Stores the data temporarily during the current session and then purges it when session is closed. Never use Session storage options if you want the data to be there when you reopen the program/page.
Second thing, WebStorage by default stores its data in Strings "" this should not be an issue for most data and there are examples out there on how to convert so that is not covered here.
Last thing, The WebStorage object must be added to your project by double clicking the layout area (or selecting via a menu) and adding it.
Mind Wrap Time:
Here is an oversimplification of WebStorage use to get your head around what it going on.
1. WebStorage must be told to create a WebStorage key (WebStorage data variable), WebStorage doesn't know you want to store junk inside it until you tell it where.
2. When a WebStorage key is known WebStorage needs to know from where it derives its junk to store (from what local variable).
3. Once it knows where the junk is derived from and what junk goes into it, it needs to be told when to dump junk into it to store.
Bear in mind, the first two events must be nested/subs under a System|On Start of Layout event. The last one doesn't.
See my example picture at bottom of tutorial or look into the example capx if your not sure what this looks like.
Create a WebStorage key for your data junk-
The easiest way to create a WebStorage key for your data is to simply allow Construct2 not to find one. Doing this is very simple, use WebStorage|Local Key Exists then type whatever WebStorage key name you want to use between the "". Now the important step, invert the check by right clicking inside it and selecting invert. This is what tells it "when not found" (which it won't be, it hasn't been added yet). After runtime this key name is now referenced inside WebStorage for its specific data and will be added each time the program runs and doesn't find it.
Now add action WebStorage|Set Local Value and type in the WebStorage key you used above between the "". Set its initial value to whatever your data calls for, "0", "cats", "true", etc.
Now each time the program is run it will create your WebStorage key for you and initialize its value if its not already there.
Linking our variables to our WebStorage key locations-
Ok, so we have made sure a WebStorage key exists, and if not created one. Now we need to tell the key where to get its data from.
To do this we need see if its even necessary by comparing the value of the WebStorage key to be stored. If the WebStorage key has no value, why bother.
My method is to use System|Compare Two Values the "first value" would be your WebStorage key (WebStorage.LocalValue("MyWebStorageData") in our example) and the second would be the value you are comparing too. If its a number use > greater-than 0 (or > greater-than-=-too 0), it is a string use it, ie. = fish, etc.
Now you need to set up the link for when it is satisfied that it has data in the WebStorage key that you can use. To do this add the action System|Set Value and input your variable in the top box (MyGameData in our example) and your WebStorage key location in the bottom (WebStorage.LocalValue("MyWebStorageData") in our example).
Now WebStorage knows that MyWebStorageData is derived from MyGameData and will update MyGameData to its remembered value when the variable is reset to 0 (or whatever you set) at start!
Dumping junk into the WebStorage key-
Now that we have a WebStorage key stored in a browser cookie somewhere. We can put junk into it that is linked to a local variable. All we need to do is feed the key data to store.
The easiest way to do this is to compare the value of the WebStorage key's current data to see if it is different than the data you want stored, if its not, why overwrite?
Use System|Compare Two Values for this. The first value is your games variable you want stored (MyGameData in our example) and the second is the WebStorage key location; WebStorage.LocalValue("MyWebStorageData"). You set the operator to not-equal-too so it detects differences in the data values, if its the same it moves on, why bother.
Now you must give it an action to store the data using WebStorage|Set Local Key.
The key is of course your WebStorage key (MyWebStorageData in our example) within "", and the value is your variable with the value you want stored, without quotes "" (MyGameData in our example).
Now your local variable can constantly send data to the WebStorage key where is can be recalled when the variable needs reset to its last value when the next session starts!
I found that it makes it much easier if you throw a text object into your layout for each WebStorage key you are using and force them to show their value with a keypress (or every tick if its a small program). This allows you to see your keys updating in real time and make sure the data is correct. I would also add a temporary button that resets all WebStorage data (an option under the WebStorage object actions) to facilitate testing as well.
I will also add since I didn't mention it (I hate getting hung up when following a tutorial because the author assumed the reader knew something obvious) that these events must be repeated for each variable you want stored in WebStorage. Ie. Your health, experience, coins, lives, etc, etc. Whatever you want stored for next session needs its own WebStorage key.
Hopefully this will help other new members get their WebStorage going without too much hassle and give me somewhere to come back to when I forget.
As promised, the picture of all the event coding: