8cb8b0729a | ||
---|---|---|
RealmJS.xcodeproj | ||
examples/ReactExample | ||
lib | ||
react-native | ||
scripts | ||
src | ||
tests | ||
vendor | ||
.eslintrc | ||
.gitignore | ||
.gitmodules | ||
LICENSE | ||
README.md | ||
RealmJS.mm |
README.md
RealmJS
Realm is a mobile database that runs directly inside phones, tablets or wearables. This repository holds the source code for Realm's JavaScript bindings for integrating with mobile apps built using ReactNative and Apache Cordova (PhoneGap).
Setup
This repository uses submodules so you need to run git submodule update --init --recursive
in the realm-js root directory before running any examples or including the project in your app.
ReactNative Example
Make sure your environment is set up to run react native applications. Follow the instructions here https://facebook.github.io/react-native/docs/getting-started.html.
The ReactNative example project is in the examples/ReactExample
directory. You need to run npm install
in this directory before running the example for the first time.
ReactNative Project Setup
- Create a new ReactNative project
react-native init <project-name>
and open the generated XCode project. - Drag
RealmJS.xcodeproj
into theLibraries
folder in your project. - Drag
RealmReact.framework
from theProducts
directory underRealmJS.xcodeproj
into theEmbedded Binaries
section in theGeneral
tab for your app's target settings. Make sure the checkbox underCode Sign On Copy
is not checked because having it checked will cause issues when trying to run your app on a device. - In the
Build Phases
tab for your app's target settings, addRealmReact.framework
to theLink Binary with Library
build phases. - In your app's
package.json
file, add therealm
dependency with a path to therealm-js/lib
folder like this:"realm": "file:path/to/realm-js/lib"
(symlinks are not yet supported by the React Native packager, see issue #637). - You can now
require('realm')
in your app's JS to use Realm!
Getting Started
Start with creating a realm
by passing it an array of objectSchema
(object types and their properties) for each type of object it will contain:
const Realm = require('realm');
const personSchema = {
name: 'Person',
primaryKey: 'name',
properties: [
{name: 'name', type: Realm.Types.STRING},
{name: 'birthday', type: Realm.Types.DATE},
{name: 'friends', type: Realm.Types.LIST, objectType: 'Person'},
{name: 'points', type: Realm.Types.INT, default: 0},
],
};
const realm = new Realm({schema: [personSchema]});
If you'd prefer your objects inherit from a prototype, you just need to define the schema
on the prototype
object and instead pass in the constructor when creating a realm
:
function Person() {}
Person.prototype = {
schema: personSchema,
get age() {
return Math.floor((Date.now() - this.birthday.getTime()) / 31557600000);
},
};
const realm = new Realm({schema: [Person]});
You can now use the realm
instance to create new objects. When using Realm, all mutations must take place inside of a write transaction:
realm.write(() => {
ross = realm.create('Person', {
name: 'Ross Geller',
birthday: new Date(1967, 9, 18),
friends: [chandler, joey, monica, phoebe, rachel],
});
});
When creating an object, values for all properties without default values need to be specified. In the example above, since the points
property has a default property it can be omitted.
Changes to object properties and object deletions also need to take place in a write transactions:
realm.write(() => {
rachel.points++;
rachel.friends.push(ross);
realm.delete(janine);
});
Note: If an uncaught exception occurs during a write transaction, then the write transaction will rollback and all object creations, deletions and modifications will be undone.
You can query for existing objects by passing the object type and an optional query into the realm.objects()
method:
let characters = realm.objects('Person');
let chandler = realm.objects('Person', 'name = "Chandler Bing"')[0];
Queries are live updating, so as change are made to a Realm queries are updated automatically to reflect those changes.
You can see more examples of how to use these APIs in the ReactExample app and in the JS test files.
Documentation
Realm
Constructor Options
new Realm(realmConfig)
The realmConfig
passed to the constructor can contain the following:
schema
– required when first accessing a realm - array ofObjectSchema
or object constructors (see below)path
– optional - defaults toRealm.defaultPath
(which initially is'Documents/default.realm'
)schemaVersion
– optional - defaults to0
but must be specified and incremented after changing the schema
ObjectSchema
name
– string used to refer to this object typeproperties
- array of property defitions (see below)primaryKey
– optional - name ofSTRING
orINT
property that should be unique
Property Types
When definining object properties
in a schema
, each should have a unique name
, and the type
of each property must be defined as either the name of an object type in the same schema or as one of the following:
Realm.Types.BOOL
Realm.Types.INT
Realm.Types.FLOAT
Realm.Types.DOUBLE
Realm.Types.STRING
Realm.Types.DATE
Realm.Types.DATA
Realm.Types.OBJECT
(requiresobjectType
, is alwaysoptional
)Realm.Types.LIST
(requiresobjectType
, is neveroptional
)
You may specify these property options as well:
default
– default value when property was not specified on creationoptional
– boolean indicating if this property may be assignednull
orundefined
Realm
Instance Methods
create(type, props [, update])
type
– string matching objectname
in theschema
definitionprops
– object with property values for all required properties without a default valueupdate
– optional – boolean signaling that an existing object (matching primary key) should be updated – only the primary key property and properties which should be updated need to be specified for theprops
arguments (all missing property values will remain unchanged)- Returns a new realm object instance
delete(object)
object
– realm object or array of realm objects (which can be aList
orResults
object)
deleteAll()
WARNING: This does what you think it does!
objects(type [, query])
type
- string matching objectname
in theschema
definitionquery
– optional – string that defines a query to filter results (see tests for examples)- Returns
Results
object
write(callback)
callback
– function that is synchronously called inside the write transaction
addListener(event, callback)
event
– string specifying the event name (only'change'
is currently supported)callback
– function that is called when that event occurs
removeListener(event, callback)
event
– string specifying the event name (only'change'
is currently supported)callback
– function that was previously added a listener callback
removeAllListeners([event])
event
– optional – string specifying the event name (only'change'
is currently supported)
close()
WARNING: This is only for advanced use cases and generally doesn't need to be used.
License
Copyright 2015 Realm Inc - All Rights Reserved Proprietary and Confidential