« Back to index

Storage

Table of Contents:

• CloudDB
• DataFile
• File
• Spreadsheet
• TinyDB
• TinyWebDB

CloudDB

The CloudDB component is a Non-visible component that allows you to store data on a Internet connected database server (using Redis software). This allows the users of your App to share data with each other. By default data will be stored in a server maintained by MIT, however you can setup and run your own server. Set the RedisServer property and RedisPort property to access your own server.

Properties

ProjectID

Gets the ProjectID for this CloudDB project.

RedisPort

The Redis Server port to use. Defaults to 6381

RedisServer

The Redis Server to use to store data. A setting of “DEFAULT” means that the MIT server will be used.

Token

This field contains the authentication token used to login to the backed Redis server. For the “DEFAULT” server, do not edit this value, the system will fill it in for you. A system administrator may also provide a special value to you which can be used to share data between multiple projects from multiple people. If using your own Redis server, set a password in the server’s config and enter it here.

UseSSL

Set to true to use SSL to talk to CloudDB/Redis server. This should be set to True for the “DEFAULT” server.

Events

CloudDBError(message)

Indicates that an error occurred while communicating with the CloudDB Redis server.

DataChanged(tag,value)

Indicates that the data in the CloudDB project has changed. Launches an event with the tag that has been updated and the value it now has.

FirstRemoved(value)

Event triggered by the RemoveFirstFromList function. The argument value is the object that was the first in the list, and which is now removed.

GotValue(tag,value)

Indicates that a GetValue request has succeeded.

TagList(value)

Event triggered when we have received the list of known tags. Run in response to a call to the GetTagList function.

UpdateDone(tag,operation)

Indicates that operations that store data to CloudDB have completed.

Methods

AppendValueToList(tag,itemToAdd)

Append a value to the end of a list atomically. If two devices use this function simultaneously, both will be appended and no data lost.

ClearTag(tag)

Remove the tag from CloudDB.

CloudConnected()

Returns true if we are on the network and will likely be able to connect to the CloudDB server.

GetTagList()

Asks CloudDB to retrieve all the tags belonging to this project. The resulting list is returned in the event TagList.

GetValue(tag,valueIfTagNotThere)

GetValue asks CloudDB to get the value stored under the given tag. It will pass the result to the GotValue will be given.

RemoveFirstFromList(tag)

Obtain the first element of a list and atomically remove it. If two devices use this function simultaneously, one will get the first element and the the other will get the second element, or an error if there is no available element. When the element is available, the FirstRemoved event will be triggered.

StoreValue(tag,valueToStore)

Asks CloudDB to store the given value under the given tag.

DataFile

Component that allows reading CSV and JSON data. The DataFile contains functionality relevant to accessing CSV or JSON parsed data in the form of rows or columns. Can be used together with the ChartData2D component to import data directly from a file to the Chart. The component may also be dragged and dropped on a Chart after a file has been selected and parsed successfully to create ChartData components automatically from the file onto the Chart.

Properties

ColumnNames

Retrieve the column names of the currently loaded Source file. For CSV files, this will return a List of entries in the first row. For JSON files, this will return a List of keys in the JSON object.

Columns

Retrieve a List of columns of the currently loaded Source file.

DefaultScope

Specifies the default scope for files accessed using the File component. The App scope should work for most apps. Legacy mode can be used for apps that predate the newer constraints in Android on app file access.

Rows

Retrieve a List of rows of the currently loaded Source file.

SourceFile

Sets the source file to parse data from, and then parses the file asynchronously. The results are stored in the Columns, Rows and ColumnNames properties. The expected formatting of the file is either the CSV or JSON format.

Events

None

Methods

ReadFile(fileName)

Indicates source file to load data from. The expected format of the contents of the file are either CSV or JSON. 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.

File

Non-visible component for storing and retrieving files. Use this component to write or read files on the device.

The exact location where external files are placed is a function of the value of the Scope property, whether the app is running in the Companion or compiled, and which version of Android the app is running on.

Because newer versions of Android require files be stored in app-specific directories, the DefaultScope is set to App. If you are using an older version of Android and need access to the legacy public storage, change the DefaultScope property to Legacy. You can also change the Scope using the blocks.

Below we briefly describe each scope type:

• App: Files will be read from and written to app-specific storage on Android 2.2 and higher. On earlier versions of Android, files will be written to legacy storage.
• Asset: Files will be read from the app assets. It is an error to attempt to write to app assets as they are contained in read-only storage.
• Cache: Files will be read from and written to the app’s cache directory. Cache is useful for temporary files that can be recreated as it allows the user to clear temporary files to get back storage space.
• Legacy: Files will be read from and written to the file system using the App Inventor rules prior to release nb187. That is, file names starting with a single / will be read from and written to the root of the external storage directory, e.g., /sdcard/. Legacy functionality will not work on Android 11 or later.
• Private: Files will be read from and written to the app’s private directory. Use this scope to store information that shouldn’t be visible to other applications, such as file management apps.
• Shared: Files will be read from and written to the device’s shared media directories, such as Pictures.

Note 1: In Legacy mode, file names can take one of three forms:

• Private files have no leading / and are written to app private storage (e.g., “file.txt”)
• External files have a single leading / and are written to public storage (e.g., “/file.txt”)
• Bundled app assets have two leading // and can only be read (e.g., “//file.txt”)

Note 2: In all scopes, a file name beginning with two slashes (//) will be interpreted as an asset name.

Properties

DefaultScope

Specifies the default scope for files accessed using the File component. The App scope should work for most apps. Legacy mode can be used for apps that predate the newer constraints in Android on app file access.

ReadPermission

A designer-only property that can be used to enable read access to file storage outside of the app-specific directories.

Scope

Indicates the current scope for operations such as ReadFrom and SaveFile.

WritePermission

A designer-only property that can be used to enable write access to file storage outside of the app-specific directories.

Events

AfterFileSaved(fileName)

Event indicating that the contents of the file have been written.

GotText(text)

Event indicating that the contents from the file have been read.

Methods

AppendToFile(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. On success, the AfterFileSaved event will run.

CopyFile(fromScope,fromFileName,toScope,toFileName)

Copy the contents from the first file to the second file.

Delete(fileName)

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 fileName with // is an error because asset files cannot be deleted.

Exists(scope,path)

Tests whether the path exists in the given scope.

IsDirectory(scope,path)

Tests whether the path named in the given scope is a directory.

ListDirectory(scope,directoryName)

Get a list of files and directories in the given directory.

MakeDirectory(scope,directoryName)

Create a new directory for storing files. The semantics of this method are such that it will return true if the directory exists at its completion. This can mean that the directory already existed prior to the call.

MakeFullPath(scope,path)

Converts the scope and path into a single string for other components.

MoveFile(fromScope,fromFileName,toScope,toFileName)

Move a file from one location to another.

ReadFrom(fileName)

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.

RemoveDirectory(scope,directoryName,recursive)

Remove a directory from the file system. If recursive is true, then everything is removed. If recursive is false, only the directory is removed and only if it is empty.

SaveFile(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 an existing file use the AppendToFile method.

Spreadsheet

Spreadsheet is a non-visible component for storing and receiving data from a Google Sheets document using the Google Sheets API.

In order to utilize this component, one must first have a Google Developer Account. Then, one must create a new project under that Google Developer Account, enable the Google Sheets API on that project, and finally create a Service Account for the Sheets API.

Instructions on how to create the Service Account, as well as where to find other relevant information for using the Google Sheets Component, can be found here.

Row and column numbers are 1-indexed.

Properties

ApplicationName

The name of your application, used when making API calls.

CredentialsJson

The JSON File with credentials for the Service Account

SpreadsheetID

The ID for the Google Sheets file you want to edit. You can find the spreadsheetID in the URL of the Google Sheets file.

Events

ErrorOccurred(errorMessage)

Triggered whenever an API call encounters an error. Details about the error are in errorMessage.

FinishedAddColumn(columnNumber)

The callback event for the AddColumn block, called once the values on the table have been updated. Additionally, this returns the column number for the new column.

FinishedAddRow(rowNumber)

The callback event for the AddRow block, called once the values on the table have been updated. Additionally, this returns the row number for the new row.

FinishedAddSheet(sheetName)

The callback event for the addSheet block, called once the values on the table have been updated.

FinishedClearRange()

The callback event for the ClearRange block, called once the values on the table have been updated.

FinishedDeleteSheet(sheetName)

The callback event for the DeleteSheet block, called once the values on the table have been updated.

FinishedRemoveColumn()

The callback event for the RemoveColumn block, called once the values on the table have been updated.

FinishedRemoveRow()

The callback event for the RemoveRow block, called once the values on the table have been updated.

FinishedWriteCell()

The callback event for the WriteCell block, called once the values on the table have been updated.

FinishedWriteColumn()

The callback event for the WriteColumn block, called once the values on the table have been updated.

FinishedWriteRange()

The callback event for the WriteRange block, called once the values on the table have been updated.

FinishedWriteRow()

The callback event for the WriteRow block, called once the values on the table have been updated.

GotCellData(cellData)

The callback event for the ReadCell block. The cellData is the text value in the cell.

GotColumnData(columnData)

The callback event for the ReadColumn block. The columnData is a list of text cell-values in order of increasing row number.

GotRangeData(rangeData)

The callback event for the ReadRange block. The rangeData is a list of rows, where the dimensions are the same as the rangeReference.

GotRowData(rowDataList)

The callback event for the ReadRow block. The rowDataList is a list of text cell-values in order of increasing column number.

GotSheetData(sheetData)

The callback event for the ReadSheet block. The sheetData is a list of rows.

Methods

AddColumn(sheetName,data)

Given a list of values as data, appends the values to the next empty column of the sheet. It will always start from the top row and continue downwards. Once complete, it triggers the FinishedAddColumn callback event.

AddRow(sheetName,data)

Given a list of values as data, appends the values to the next empty row of the sheet. It will always start from the left most column and continue to the right. Once complete, it triggers the FinishedAddRow callback event. Additionally, this returns the row number for the new row.

AddSheet(sheetName)

Adds a new sheet inside the Spreadsheet.

ClearRange(sheetName,rangeReference)

Empties the cells in the given range. Once complete, this block triggers the FinishedClearRange callback event.

DeleteSheet(sheetName)

Deletes the specified sheet inside the Spreadsheet.

GetCellReference(row,column)

Converts the integer representation of rows and columns to A1-Notation used in Google Sheets for a single cell. For example, row 1 and col 2 corresponds to the string "B1".

GetRangeReference(row1,column1,row2,column2)

Converts the integer representation of rows and columns for the corners of the range to A1-Notation used in Google Sheets. For example, selecting the range from row 1, col 2 to row 3, col 4 corresponds to the string “B1:D3”.

ReadCell(sheetName,cellReference)

On the page with the provided sheetName, reads the cell at the given cellReference and triggers the GotCellData callback event. The cellReference can be either a text block with A1-Notation, or the result of the GetCellReference block.

ReadColumn(sheetName,column)

On the page with the provided sheetName, reads the column at the given colNumber and triggers the GotColumnData callback event.

ReadRange(sheetName,rangeReference)

On the page with the provided sheetName, reads the cells at the given rangeReference and triggers the GotRangeData callback event. The rangeReference can be either a text block with A1-Notation, or the result of the GetRangeReference block.

ReadRow(sheetName,rowNumber)

On the page with the provided sheetName, reads the row at the given rowNumber and triggers the GotRowData callback event.

ReadSheet(sheetName)

Reads the entire Google Sheets document and triggers the GotSheetData callback event.

ReadWithExactFilter(sheetName,colID,value)

Filters a Google Sheet for rows where the given column number matches the provided value.

ReadWithPartialFilter(sheetName,colID,value)

Filters a Google Sheet for rows where the given column number contains the provided value string.

RemoveColumn(sheetName,column)

Deletes the column with the given column number from the table. This does not clear the column, but removes it entirely. The sheet’s grid id can be found at the end of the url of the Google Sheets document, right after the “gid=”. Once complete, it triggers the FinishedRemoveColumn callback event.

RemoveRow(sheetName,rowNumber)

Deletes the row with the given row number (1-indexed) from the table. This does not clear the row, but removes it entirely. The sheet’s grid id can be found at the end of the url of the Google Sheets document, right after the “gid=”. Once complete, it triggers the FinishedRemoveRow callback event.

WriteCell(sheetName,cellReference,data)

Given text or a number as data, writes the value to the cell. It will override any existing data in the cell with the one provided. Once complete, it triggers the FinishedWriteCell callback event.

WriteColumn(sheetName,column,data)

Given a list of values as data, writes the values to the column with the given column number, overriding existing values from top down. (Note: It will not erase the entire column.) Once complete, it triggers the FinishedWriteColumn callback event.

WriteRange(sheetName,rangeReference,data)

Given list of lists as data, writes the values to cells in the range. The number of rows and columns in the range must match the dimensions of your data. This method will override existing data in the range. Once complete, it triggers the FinishedWriteRange callback event.

WriteRow(sheetName,rowNumber,data)

Given a list of values as data, writes the values to the row with the given row number, overriding existing values from left to right. (Note: It will not erase the entire row.) Once complete, it triggers the FinishedWriteRow callback event.

TinyDB

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.

Properties

Namespace

Namespace for storing data.

Events

None

Methods

ClearAll()

Clear the entire data store.

ClearTag(tag)

Clear the entry with the given tag.

GetEntries()

Method to get all data in form of Dictionary

GetTags()

Return a list of all the tags in the data store.

GetValue(tag,valueIfTagNotThere)

Retrieve the value stored under the given tag. If there’s no such tag, then return valueIfTagNotThere.

StoreValue(tag,valueToStore)

Store the given valueToStore under the given tag. The storage persists on the phone when the app is restarted.

TinyWebDB

The TinyWebDB component communicates with a Web service to store and retrieve information. Although this component is usable, it is very limited and meant primarily as a demonstration for people who would like to create their own components that talk to the Web. The accompanying Web service is at (http://tinywebdb.appinventor.mit.edu). The component has methods to store a value under a tag and to retrieve the value associated with the tag. The interpretation of what “store” and “retrieve” means is up to the Web service. In this implementation, all tags and values are strings (text). This restriction may be relaxed in future versions.

Properties

ServiceURL

Specifies the URL of the Web service. The default value is the demo service running on App Engine.

Events

GotValue(tagFromWebDB,valueFromWebDB)

Indicates that a GetValue server request has succeeded.

ValueStored()

Event indicating that a StoreValue server request has succeeded.

WebServiceError(message)

Indicates that the communication with the Web service signaled an error.

Methods

GetValue(tag)

GetValue asks the Web service to get the value stored under the given tag. It is up to the Web service what to return if there is no value stored under the tag. This component just accepts whatever is returned. The GotValue event will be run on completion.

StoreValue(tag,valueToStore)

Sends a request to the Web service to store the given valueToStore under the given tag. The ValueStored event will be run on completion.