Merge pull request #243 from realm/km-react-ReadmeUpdate
Update to Readme for Public Release
This commit is contained in:
Tim Anglade
commit
f43c75437e
|
|
@ -0,0 +1,40 @@
|
||||||
|
# Contributing
|
||||||
|
|
||||||
|
## Filing Issues
|
||||||
|
|
||||||
|
Whether you find a bug, typo or an API call that could be clarified, please [file an issue](https://github.com/realm/realm-js/issues) on our GitHub repository.
|
||||||
|
|
||||||
|
When filing an issue, please provide as much of the following information as possible in order to help others fix it:
|
||||||
|
|
||||||
|
1. **Goals**
|
||||||
|
2. **Expected results**
|
||||||
|
3. **Actual results**
|
||||||
|
4. **Steps to reproduce**
|
||||||
|
5. **Code sample that highlights the issue** (full Xcode / Android Studio projects that we can compile ourselves are ideal)
|
||||||
|
6. **Version of Realm / Xcode/ Android Studio/ OSX/ WIN**
|
||||||
|
|
||||||
|
If you'd like to send us sensitive sample code to help troubleshoot your issue, you can email <help@realm.io> directly.
|
||||||
|
|
||||||
|
## Contributing Enhancements
|
||||||
|
|
||||||
|
We love contributions to Realm! If you'd like to contribute code, documentation, or any other improvements, please [file a Pull Request](https://github.com/realm/realm-js/pulls) on our GitHub repository. Make sure to accept our [CLA](#cla)
|
||||||
|
|
||||||
|
### Commit Messages
|
||||||
|
|
||||||
|
Although we don’t enforce a strict format for commit messages, we prefer that you follow the guidelines below, which are common among open source projects. Following these guidelines helps with the review process, searching commit logs and documentation of implementation details. At a high level, the contents of the commit message should convey the rationale of the change, without delving into much detail. For example, `setter names were not set right` leaves the reviewer wondering about which bits and why they weren’t “right”. In contrast, `[RLMProperty] Correctly capitalize setterName` conveys almost all there is to the change.
|
||||||
|
|
||||||
|
Below are some guidelines about the format of the commit message itself:
|
||||||
|
|
||||||
|
* Separate the commit message into a single-line title and a separate body that describes the change.
|
||||||
|
* Make the title concise to be easily read within a commit log.
|
||||||
|
* Make the body concise, while including the complete reasoning. Unless required to understand the change, additional code examples or other details should be left to the pull request.
|
||||||
|
* If the commit fixes a bug, include the number of the issue in the message.
|
||||||
|
* Use the first person present tense - for example "Fix …" instead of "Fixes …" or "Fixed …".
|
||||||
|
* For text formatting and spelling, follow the same rules as documentation and in-code comments — for example, the use of capitalization and periods.
|
||||||
|
* If the commit is a bug fix on top of another recently committed change, or a revert or reapply of a patch, include the Git revision number of the prior related commit, e.g. `Revert abcd3fg because it caused #1234`.
|
||||||
|
|
||||||
|
### CLA
|
||||||
|
|
||||||
|
Realm welcomes all contributions! The only requirement we have is that, like many other projects, we need to have a [Contributor License Agreement](https://en.wikipedia.org/wiki/Contributor_License_Agreement) (CLA) in place before we can accept any external code. Our own CLA is a modified version of the Apache Software Foundation’s CLA.
|
||||||
|
|
||||||
|
[Please submit your CLA electronically using our Google form](https://docs.google.com/forms/d/1bVp-Wp5nmNFz9Nx-ngTmYBVWVdwTyKj4T0WtfVm0Ozs/viewform?fbzx=4154977190905366979) so we can accept your submissions. The GitHub username you file there will need to match that of your Pull Requests. If you have any questions or cannot file the CLA electronically, you can email <help@realm.io>.
|
||||||
210
README.md
210
README.md
|
|
@ -1,176 +1,88 @@
|
||||||
# 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
|
Realm is a mobile database that runs directly inside phones, tablets or wearables.
|
||||||
This repository uses submodules so you need to run `git submodule update --init --recursive` in the realm-js root directory before running any examples.
|
This repository holds the source code for Realm's JavaScript bindings for integrating with mobile apps built using React Native.
|
||||||
|
|
||||||
## ReactNative Example
|
Currently we only support React Native (both iOS & Android) but we are considering adding support for Cordova/PhoneGap/Ionic as well as Node.js (V8) soon.
|
||||||
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.
|
## Features
|
||||||
|
|
||||||
## ReactNative Project Setup
|
* **Mobile-first:** Realm is the first database built from the ground up to run directly inside phones, tablets and wearables.
|
||||||
- Create a new ReactNative project: `react-native init <project-name>`
|
* **Simple:** Data is directly [exposed as objects](https://realm.io/docs/react-native/latest/#models) and [queryable by code](https://realm.io/docs/react-native/latest/#queries), removing the need for ORM's riddled with performance & maintenance issues.
|
||||||
- Change directories into the new project (`cd <project-name>`) and add the `realm` 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)
|
* **Modern:** Realm supports relationships, generics, and vectorization.
|
||||||
|
* **Fast:** Realm is faster than even raw SQLite on common operations, while maintaining an extremely rich feature set.
|
||||||
### 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 least `8.0` in the project settings.
|
|
||||||
- Right-click the `Libraries` group in the sidebar and click `Add Files to “<project-name>”`. Select `node_modules/realm/RealmJS.xcodeproj` from the dialog.
|
|
||||||
- Drag `RealmReact.framework` from the `Products` directory under `RealmJS.xcodeproj` into the `Embedded Binaries` section in the `General` tab for your app's target settings.
|
|
||||||
- In the `Build Phases` tab for your app's target settings, make sure `RealmReact.framework` is added to the `Link 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 the `getPackages()` method.
|
|
||||||
- You can now `require('realm')` in your Android app's JS to use Realm!
|
|
||||||
|
|
||||||
## Getting Started
|
## 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:
|
|
||||||
|
|
||||||
```js
|
Please see the detailed instructions in our docs to use [Realm React Native](https://realm.io/docs/react-native/latest/#installation).
|
||||||
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`:
|
|
||||||
|
|
||||||
```js
|
|
||||||
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:
|
|
||||||
|
|
||||||
```js
|
|
||||||
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:
|
|
||||||
|
|
||||||
```js
|
|
||||||
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:
|
|
||||||
|
|
||||||
```js
|
|
||||||
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](https://github.com/realm/realm-js/tree/master/examples/ReactExample) app and in the [JS test files](https://github.com/realm/realm-js/tree/master/tests).
|
|
||||||
|
|
||||||
## Documentation
|
## 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 of `ObjectSchema` or object constructors (see below)
|
### Realm React Native
|
||||||
- `path` – optional - defaults to `Realm.defaultPath` (which initially is `'Documents/default.realm'` for iOS and inside the [internal storage](http://developer.android.com/reference/android/content/Context.html#getFilesDir()) `/data/data/<packagename>/files/` for Android)
|
|
||||||
- `schemaVersion` – optional - defaults to `0` but must be specified and incremented after changing the schema
|
|
||||||
|
|
||||||
### ObjectSchema
|
The documentation can be found at [realm.io/docs/react-native/latest](https://realm.io/docs/react-native/latest).
|
||||||
- `name` – string used to refer to this object type
|
The API reference is located at [realm.io/docs/react-native/latest/api](https://realm.io/docs/react-native/latest/api).
|
||||||
- `properties` - object with property definitions (see below)
|
|
||||||
- `primaryKey` – optional - name of `STRING` or `INT` property that should be unique
|
|
||||||
|
|
||||||
### Property Types
|
## Getting Help
|
||||||
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"`)
|
- **Need help with your code?**: Look for previous questions on the [#realm tag](https://stackoverflow.com/questions/tagged/realm?sort=newest) — or [ask a new question](https://stackoverflow.com/questions/ask?tags=realm). We actively monitor and answer questions on SO!
|
||||||
- `Realm.Types.INT` (`"int"`)
|
- **Have a bug to report?** [Open an issue](https://github.com/realm/realm-js/issues/new). If possible, include the version of Realm, a full log, the Realm file, and a project that shows the issue.
|
||||||
- `Realm.Types.FLOAT` (`"float"`)
|
- **Have a feature request?** [Open an issue](https://github.com/realm/realm-js/issues/new). Tell us what the feature should do, and why you want the feature.
|
||||||
- `Realm.Types.DOUBLE` (`"double"`)
|
- Sign up for our [**Community Newsletter**](http://eepurl.com/VEKCn) to get regular tips, learn about other use-cases and get alerted of blog posts and tutorials about Realm.
|
||||||
- `Realm.Types.STRING` (`"string"`)
|
|
||||||
- `Realm.Types.DATE` (`"date"`)
|
|
||||||
- `Realm.Types.DATA` (`"data"`)
|
|
||||||
- `Realm.Types.LIST` (`"list"` – requires `objectType` and cannot be `optional`)
|
|
||||||
|
|
||||||
You _may_ specify these property options as well:
|
## Building Realm
|
||||||
|
|
||||||
- `default` – default value when property was not specified on creation
|
In case you don't want to use the precompiled version on npm, you can build Realm yourself from source. You’ll need an Internet connection the first time you build in order to download the core library.
|
||||||
- `optional` – boolean indicating if this property may be assigned `null` or `undefined`
|
|
||||||
|
|
||||||
**Note:** When the `type` of a property is that of an object type in the same schema, it _always_ will be `optional`.
|
Prerequisites:
|
||||||
|
- Node 4.0+
|
||||||
|
- Xcode 7.2+
|
||||||
|
- Android SDK 23+
|
||||||
|
- Android NDK 10e+
|
||||||
|
|
||||||
### `Realm` Instance Methods
|
First clone this repository:
|
||||||
#### `create(type, props [, update])`
|
|
||||||
- `type` – string matching object `name` in the `schema` definition
|
|
||||||
- `props` – object with property values for all required properties without a default value
|
|
||||||
- `update` – 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 the `props` 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 a `List` or `Results` object)
|
git clone https://github.com/realm/realm-js.git
|
||||||
|
```
|
||||||
|
|
||||||
#### `deleteAll()`
|
Then in the cloned directory:
|
||||||
**WARNING:** This does what you think it does!
|
|
||||||
|
|
||||||
#### `objects(type [, query])`
|
```
|
||||||
- `type` - string matching object `name` in the `schema` definition
|
git submodule update --init --recursive
|
||||||
- `query` – optional – string that defines a query to filter results (see tests for examples)
|
```
|
||||||
- _Returns `Results` object_
|
|
||||||
|
|
||||||
#### `write(callback)`
|
To build for iOS:
|
||||||
- `callback` – function that is synchronously called inside the write transaction
|
- Open `RealmJS.xcodeproj`
|
||||||
|
- Select `RealmReact.framework` as the build target
|
||||||
|
- Build
|
||||||
|
|
||||||
#### `addListener(event, callback)`
|
To build for Android:
|
||||||
- `event` – string specifying the event name (only `'change'` is currently supported)
|
- `cd react-native/android`
|
||||||
- `callback` – function that is called when that event occurs
|
- `./gradlew publishAndroid`
|
||||||
|
- The compiled version of the Android module is here: `<project-root>/android`
|
||||||
|
|
||||||
#### `removeListener(event, callback)`
|
## Code of Conduct
|
||||||
- `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](https://realm.io/conduct/).
|
This project adheres to the Contributor Covenant [code of conduct](https://realm.io/conduct/).
|
||||||
By participating, you are expected to uphold this code. Please report unacceptable behavior to [info[at]realm.io](mailto:info+conduct@realm.io).
|
By participating, you are expected to uphold this code. Please report unacceptable behavior to [info@realm.io](mailto:info+conduct@realm.io).
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for more details!
|
||||||
|
|
||||||
## License
|
## License
|
||||||
Copyright 2015 Realm Inc - All Rights Reserved
|
|
||||||
Proprietary and Confidential
|
Realm JS is published under the Apache 2.0 license.
|
||||||
|
The underlying core is available under the [Realm Core Binary License](https://github.com/realm/realm-cocoa/blob/master/LICENSE#L210-L243) while we [work to open-source it under the Apache 2.0 license](https://realm.io/docs/react-native/latest/#faq).
|
||||||
|
|
||||||
|
**This product is not being made available to any person located in Cuba, Iran,
|
||||||
|
North Korea, Sudan, Syria or the Crimea region, or to any other person that is
|
||||||
|
not eligible to receive the product under U.S. law.**
|
||||||
|
|
||||||
|
## Feedback
|
||||||
|
|
||||||
|
**_If you use Realm and are happy with it, all we ask is that you please consider sending out a tweet mentioning [@realm](https://twitter.com/realm), or email [help@realm.io](mailto:help@realm.io) about your great apps!_**
|
||||||
|
|
||||||
|
**_And if you don't like it, please let us know what you would like improved, so we can fix it!_**
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue