Docs

Everything You Need to Know

Box

Intro

When you need to store things, you might put them in a box. ChocolateChip-UI's Box does that for your app. It provides a consistent and simple interface for handling local data persistence using IndexedDB, WebSQL and localStorage. By default it tries to use IndexedDB. If the browser's implementation is buggy, Box will try to use WebSQL. If that also proves to be problematic, it will use localStorage.

Older versions of Safari on desktop and mobile claim to support IndexedDB. Unfortunately their implementation is seriously flawed, rendering this problematic for reliable storage. We use WebSQL for those versions Safari. If you know what your target platform supports, you can tell Box to use it with a configuration setting to override the defaults.

Local data stores have severe limitations as to how much they can hold. Box's data cap is 5MB. This is the limit for localStorage. If you want to ignore the localStorage fallback and depend on IndexedDB and WebSQL for your storage need, you can set the size to up to 50MB, which is the limit for WebSQL. Doing so means the user will be prompted to authorize it. Your users may not understand why they are being asked to permit storage and choose to deny it. You should therefore properly inform the user with a notification explaining that they need to authorize the use of more storage for the app to function properly.

Although IndexedDB can store binary data, such as images, WebSQL and localStorage cannot. If you want to store binary data, ChocolateChip-UI Box will need to encode the binary data into 64 bit format before saving it to them. Depending on the size of your binary data, this may take quite some time. This will temporarily impact the performance of your app, so plan accordingly.

Not Included by Default

The code to make Box work adds an additional 20kb to the library. Since this is a feature many of you may not use, we've made it optional. When you create a project and want to have local data persistence with Box, you need to ask for it with a flag. Notice the use of the flag -b in the following command for a new project:

// Create a project with support for Box:
chui -n myProject -o android -t navigation -b

Using the -b flag will give you a version of ChocolateChip-UI that includes Box. If you are not going to use Box for local data persistence, do not use this flag.

For more information about options to use when creating a new project, read the documentation.