Storage - App Inventor for Android
Table of Contents
Non-visible component for storing and retrieving files. Use this component to write or read files on your device. The default behavior is to write files to the private data directory associated with your App. The Companion writes files to /sdcard/AppInventor/data for easy debugging. If the file path starts with a slash (/), then the file is created relative to /sdcard. For example, writing a file to /myFile.txt will write the file in /sdcard/myFile.txt.
- Event indicating that the contents of the file have been written.
- Event indicating that the contents from the file have been read.
AppendToFile(text text, text fileName)
- Appends text to the end of a file. Creates the file if it does not already exist. See the help text under SaveFile for information about where files are written.
- Deletes a file from storage. Prefix the filename with / to delete a specific file in the SD card (for example, /myFile.txt will delete the file /sdcard/myFile.txt). If the filename does not begin with a /, then the file located in the program's private storage will be deleted. Starting the file with // is an error because asset files cannot be deleted.
- Reads text from a file in storage. Prefix the filename with / to read from a specific file on the SD card (for example, /myFile.txt will read the file /sdcard/myFile.txt). To read assets packaged with an application (also works for the Companion) start the filename with // (two slashes). If a filename does not start with a slash, it will be read from the application's private storage (for packaged apps) and from /sdcard/AppInventor/data for the Companion.
SaveFile(text text, text fileName)
- Saves text to a file. If the filename begins with a slash (/) the file is written to the sdcard (for example, writing to /myFile.txt will write the file to /sdcard/myFile.txt). If the filename does not start with a slash, it will be written in the program's private data directory where it will not be accessible to other programs on the phone. There is a special exception for the AI Companion where these files are written to /sdcard/AppInventor/data to facilitate debugging. Note that this block will overwrite a file if it already exists. If you want to add content to a file use the append block.
A non-visible component that communicates with Google Fusion Tables. Fusion Tables let you store, share, query and visualize data tables; this component lets you query, create, and modify these tables.
This component uses the Fusion Tables API V2.0.
Applications using Fusion Tables must authenticate with Google's servers. There are two ways this can be done. The first way only uses an API Key which you (the developer) obtain. With this approach end-users must also login to access a Fusion Table.
The second approach is to use Service Authentication. With this approach you create credentials and a special "Service Account Email Address" which allows end-users to edit your Fusion Tables without logging in; your service account authenticates all access.
Using the FusiontablesControl Component
Creating Fusion Tables
You will probably want to create your own Fusion Tables to experiment with as you are developing your apps. This is as easy as creating a Google document, if you are familiar with that process. Here are the steps:
- On the web, login to your Gmail account or any other Google service (e.g., Drive, YouTube). Navigate to Google Drive.
- Click the New button and navigate to More. If you do not see a Google Fusion Tables option, select Connect more apps and scroll through the page of Google services to find the Fusion Tables service and connect it to your Google Drive.
- You may want to view some of the examples and work through a tutorial (e.g. Pizza Party Tutorial) to learn the basics.
- Click the See my tables button (top right of the page). This will bring you to your own page.
- You should see a list of your own tables or tables that have been shared with you (possibly none).
- Use the Create button to create a new table. Give it some column names and save it.
- Click on the Share button (top right) to modify the table's permissions.
Creating a Fusiontables App
When you drag the FusiontablesControl component onto the Designer, don't forget to set its ApiKey property, which is initially blank. You should copy this from your Google Developers Console and paste it into the property field.
To get an API key, follow these instructions.
- Go to your Google Developers Console and login if necessary.
- Under APIs & auth select the APIs item from the menu on the left.
- Choose the Fusion Tables API from the list provided and turn it on.
- On the left bar, select the Credentials item.
- Under Public API access click Create new Key, choose Android key and click Create to generate an API key.
Your API key(s) will appear in the pane next to "Public API access". You must provide that key as the value for the ApiKey property in your Fusion Tables app.
Once you have an API key, set the value of the Query property to a valid Fusiontables SQL query and call SendQuery to execute the query. App Inventor will send the query to the Fusion Tables server and the GotResult block will fire when a result is returned from the server. Query results will be returned in CSV format, and can be converted to list format using the "list from csv table" or "list from csv row" blocks.
Note that you do not need to worry about UTF-encoding the query. But you do need to make sure the query follows the syntax described in the reference manual, which means that things like capitalization for names of columns matters, and that single quotes must be used around column names if there are spaces in them.
To set up Service Authentication for your Fusion Table, follow these additional steps:
- In the Google APIs Console under APIs & auth select the APIs item from the menu on the left.
- Click the Create new Client ID button. Select the Service account option, and click Create Client ID.
- A file called the KeyFile (ends in extension .p12) will automatically download onto your computer. Save it in a place you will remember. Once the creation is complete, you will get a table with your Service Account information.
- In the designer window of App Inventor, select the FusionTablesControl. In the properties pane, add the ServiceAccountEmail (from the table on the console), upload the KeyFile, and check the UseServiceAuthentication box.
- Share the Fusion Table with your ServiceAccountEmail, and give it editing permissions, just like you would share any other Google Doc with an email address.
- Your Google API Key. See above for details on obtaining an API key.
- Specifies the path of the private key file. This key file is used to get access to the FusionTables API through Service Authentication.
- The message shown in the loading dialog
- The query to send to the Fusion Tables API.
For legal query formats and examples, see the Fusion Tables API v2.0 reference manual.
Note that you do not need to worry about UTF-encoding the query. You must make sure the query follows the syntax described in the reference manual. Note that capitalization for names of columns is necessary and that single quotes must be used around column names if there are spaces in them.
- The Service Account Email Address used for Service Authentication.
- Whether to show the loading dialog or not
- Indicates whether a service account should be used for authentication.
- Indicates that the Fusion Tables query has finished processing and returned with a result. The result of the query will generally be returned in CSV format, and can be converted to list format using the "list from csv table" or "list from csv row" blocks.
- DEPRECATED. This block is deprecated as of the end of 2012. Use SendQuery instead.
- Forget the end-user's login credentials. Has no effect on Service Authentication.
GetRows(text tableId, text columns)
- Gets all the rows from a specified Fusion Table. The tableId field (required) is the id of the Fusion Table. The columns field is a comma-separated list of the columns to retrieve.
GetRowsWithConditions(text tableId, text columns, text conditions)
- Gets all the rows from a Fusion Table that meet certain conditions. The tableId field (required) is the id of the Fusion Table. The columns field is a comma-separated list of the columns to retrieve. The conditions field specifies what rows to retrieve from the table (for example, the rows in which a particular column value is not null).
InsertRow(text tableId, text columns, text values)
- Inserts a row into the specified Fusion Table. The tableId field is the id of the Fusion Table. The columns field is a comma-separated list of the columns into which to insert values. The values field specifies what values to insert into each column.
- Send the query to the Fusion Tables server.
TinyDB is a non-visible component that stores data for an app.
Apps created with App Inventor are initialized each time they run. This means that if an app sets the value of a variable and the user then quits the app, the value of that variable will not be remembered the next time the app is run. In contrast, TinyDB is a persistent data store for the app. The data stored in a TinyDB will be available each time the app is run. An example might be a game that saves the high score and retrieves it each time the game is played.
Data items consist of tags and values. To store a data item, you specify the tag it should be stored under. The tag must be a text block, giving the data a name. Subsequently, you can retrieve the data that was stored under a given tag.
You cannot use the TinyDB to pass data between two different apps on the phone, although you can use the TinyDB to share data between the different screens of a multi-screen app.
When you are developing apps using the AI Companion, all the apps using that Companion will share the same TinyDB. That sharing will disappear once the apps are packaged and installed on the phone. During development you should be careful to clear the Companion app's data each time you start working on a new app.
- Namespace for storing data. All TinyDB components in the same app with the same namespace property access the same data.
- Each namespace represents a single data store that is shared by the entire app. If you have multiple TinyDB components with the same namespace within an app, they use the same data store, even if they are on different screens. If you only need one datastore for your app, it's not necessary to define a namespace.
- Clear the entire data store in the TinyDB.
- Clear the entry with the given tag.
- Return a list of all the tags in the TinyDB.
any GetValue(text tag, any valueIfTagNotThere)
- Retrieve the value stored under the given tag. If there's no such tag, then return valueIfTagNotThere.
StoreValue(text tag, any valueToStore)
- Store the value under the given tag. The storage persists on the phone when the app is restarted.
Non-visible component that communicates with a Web service to store and retrieve information.See Creating a Custom TinyWebDB Service.
- The URL to the database with which the component should communicate.
GotValue(text tagFromWebDB, any valueFromWebDB)
- Indicates that a GetValue server request has succeeded.
- Event indicating that a StoreValue server request has succeeded.
- Indicates that the communication with the Web service signaled an error.
- Sends a request to the Web service to get the value stored under the given tag. The Web service must decide what to return if there is no value stored under the tag. This component accepts whatever is returned.
StoreValue(text tag, any valueToStore)
- Sends a request to the Web service to store the given value under the given tag.