0f01c413ab
Update everything to use React Native 0.20.0 |
||
---|---|---|
RealmJS.xcodeproj | ||
docs | ||
examples | ||
lib | ||
react-native | ||
scripts | ||
src | ||
tests | ||
vendor | ||
.eslintrc | ||
.gitignore | ||
.gitmodules | ||
LICENSE | ||
README.md | ||
package.json |
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.
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>
- Change directories into the new project (
cd <project-name>
) and add therealm
dependency:npm install --save git+ssh://git@github.com/realm/realm-js.git#beta
(please note it's essential to leave the#beta
at the end)
iOS
- Open the generated Xcode project (
ios/<project-name>.xcodeproj
) - Making sure the top-level project is selected in the sidebar, change the
iOS Deployment Target
to at least8.0
in the project settings. - Right-click the
Libraries
group in the sidebar and clickAdd Files to “<project-name>”
. Selectnode_modules/realm/RealmJS.xcodeproj
from the dialog. - Drag
RealmReact.framework
from theProducts
directory underRealmJS.xcodeproj
into theEmbedded Binaries
section in theGeneral
tab for your app's target settings. - In the
Build Phases
tab for your app's target settings, make sureRealmReact.framework
is added to theLink Binary with Library
build phase. - You can now
require('realm')
in your iOS app's JS to use Realm!
Android
- Run this command from the project directory:
react-native link realm
- Open
MainActivity.java
inside your project:- Add
import io.realm.react.RealmReactPackage;
under the other imports. - Add
new RealmReactPackage()
to the list returned by thegetPackages()
method.
- Add
- You can now
require('realm')
in your Android 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: 'string',
birthday: 'date',
friends: {type: 'list', objectType: 'Person'},
points: {type: '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'
for iOS and inside the internal storage/data/data/<packagename>/files/
for Android)schemaVersion
– optional - defaults to0
but must be specified and incremented after changing the schema
ObjectSchema
name
– string used to refer to this object typeproperties
- object with property definitions (see below)primaryKey
– optional - name ofSTRING
orINT
property that should be unique
Property Types
When defining object properties
in a schema
, the value for each property must either be the type
OR an object with a type
key along with other options detailed below. 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
("bool"
)Realm.Types.INT
("int"
)Realm.Types.FLOAT
("float"
)Realm.Types.DOUBLE
("double"
)Realm.Types.STRING
("string"
)Realm.Types.DATE
("date"
)Realm.Types.DATA
("data"
)Realm.Types.LIST
("list"
– requiresobjectType
and cannot beoptional
)
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
Note: When the type
of a property is that of an object type in the same schema, it always will be optional
.
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.
Conduct
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to info[at]realm.io.
License
Copyright 2015 Realm Inc - All Rights Reserved Proprietary and Confidential