Skip to content

Commit d01c954

Browse files
dacharycdacharyc
authored
(DOCSP-12426): Build out Realm Studio documentation (#1053)
1 parent 118b7c4 commit d01c954

20 files changed

+794
-52
lines changed

‎snooty.toml

+2-1
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@ toc_landing_pages = [
4141
"/node",
4242
"/react-native",
4343
"/web",
44-
"/dotnet"
44+
"/dotnet",
45+
"/studio"
4546
]
4647

4748
[substitutions]

‎source/images/realm-studio-click-into-list-of-tasks.png

142 KB
Loading

‎source/images/realm-studio-create-task-from-category-work.png

204 KB
Loading

‎source/images/realm-studio-task-creation-ui.png

197 KB
Loading

‎source/includes/find-realm-file-dotnet.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. code-block:: csharp
2+
3+
var realm = Realm.GetInstance();
4+
Console.WriteLine($"Realm is located at: {realm.Config.DatabasePath}");

‎source/includes/find-realm-file-java.rst

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
The filesystem used by Android emulators is not directly accessible
2+
from the machine running Realm Studio. You must download the file
3+
from the emulator before you can access it.
4+
5+
First, find the path of the file on the emulator:
6+
7+
.. code-block:: java
8+
9+
// Run this on the device to find the path on the emulator
10+
Realm realm = Realm.getDefaultInstance();
11+
Log.i("Realm", realm.getPath());
12+
13+
Then, download the file using ADB. You can do this while the app
14+
is running.
15+
16+
.. code-block:: java
17+
18+
> adb pull <path>
19+
20+
You can also upload the modified file again using ADB, but only
21+
when the app isn't running. Uploading a modified file while the
22+
app is running can corrupt the file.
23+
24+
.. code-block:: java
25+
26+
> adb push <file> <path>
27+

‎source/includes/find-realm-file-javascript.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. code-block:: javascript
2+
3+
// Get on-disk location of the default Realm
4+
Realm.open({}).then(realm => {
5+
console.log("Realm is located at: " + realm.path);
6+
});

‎source/includes/find-realm-file-swift.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. code-block:: swift
2+
3+
// Get on-disk location of the default Realm
4+
let realm = try! Realm()
5+
print("Realm is located at:", realm.configuration.fileURL!)
6+

‎source/includes/realm-studio-export-class-definitions.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
To export updated class definitions:
2+
3+
- Go to :guilabel:`File` > :guilabel:`Save model definitions`, and select
4+
your preferred language. Supported languages include: Swift, JavaScript,
5+
TypeScript, Java, Kotlin, and C#.
6+
- Specify a name and destination for your new class definitions. Press
7+
the :guilabel:`Save` button.
8+
9+
If your destination directory does not already exist, Realm Studio creates
10+
it. Inside, you'll find a file that contains a complete list of classes
11+
and properties, including new additions.

‎source/includes/realm-studio.rst

-13
This file was deleted.

‎source/includes/steps-create-realm-from-csv.yaml

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
title: Browse to the Create Realm from CSV option
2+
ref: realm-studio-select-create-from-csv
3+
content: |
4+
In Realm Studio, go to: :guilabel:`File` > :guilabel:`Create Realm from` > :guilabel:`CSV`
5+
---
6+
title: Open your CSV
7+
ref: realm-studio-open-csv
8+
content: |
9+
Browse to the location of your CSV file, and select it.
10+
11+
Press the :guilabel:`Open` button.
12+
---
13+
title: Choose where to store the imported data
14+
ref: realm-studio-choose-where-to-store-imported-data
15+
content: |
16+
Enter a name for the {+realm+} file that will be created from your CSV.
17+
18+
Browse to the location where you want to save it.
19+
20+
Press the :guilabel:`Save` button.
21+
---
22+
title: Add more data to the {+realm+}
23+
ref: realm-studio-add-data-to-realm-created-from-csv
24+
content: |
25+
When you create a new {+realm+} file from a CSV, you may get this message:
26+
27+
"Failed to import data: Class name (name-of-file.csv) missing from schema"
28+
29+
If this happens, press :guilabel:`OK`. You'll see that creating a {+realm+}
30+
from your CSV has created a class definition, but there are no objects
31+
in your {+realm+}. From here, you can :ref:`Import from a CSV<realm-studio-import-from-a-csv>`
32+
to populate your {+realm+} with object that map to the class definition
33+
you just created.

‎source/includes/steps-install-realm-studio.yaml

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
title: Select a version
2+
ref: select-realm-studio-version
3+
content: |
4+
5+
The binaries listed on this page are always the latest version of
6+
Realm Studio.
7+
8+
If you open an older version of a {+realm+} file in a newer Realm Studio
9+
version, you may see a prompt to upgrade your {+realm+} file. Once
10+
upgraded, you cannot revert to the older file version. You may also
11+
need to upgrade your SDK to a version that supports the newer file format.
12+
13+
If you don't want to upgrade {+client-database+}, download an older
14+
version of Realm Studio. You can see a list of all releases at
15+
`Realm Studio Releases <https://studio-releases.realm.io/>`_.
16+
Click a version number to view a page listing enhancements, fixes,
17+
and file downloads.
18+
19+
---
20+
title: Download the binary
21+
ref: download-realm-studio-binary
22+
content: |
23+
24+
Download and extract the correct binary for your operating system.
25+
26+
.. list-table::
27+
:header-rows: 1
28+
:class: index-table
29+
30+
* - Operating System
31+
- Download
32+
33+
* - Linux
34+
- `.AppImage <https://studio-releases.realm.io/latest/download/linux-appimage>`_
35+
36+
* - MacOS
37+
- `.dmg <https://studio-releases.realm.io/latest/download/mac-dmg>`_
38+
39+
* - Windows
40+
- `.exe <https://studio-releases.realm.io/latest/download/win-setup>`_
41+
42+
---
43+
title: Run the executable file
44+
ref: run-realm-studio-executable
45+
content: |
46+
47+
Run the executable file. Follow installer instructions.

‎source/includes/steps-realm-studio-create-object.yaml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
title: Select a class for the new object
2+
ref: realm-studio-create-object-select-class
3+
content: |
4+
The left sidebar of Realm Studio displays the classes that comprise the
5+
schema. Select the class for the type of object you want to create.
6+
---
7+
title: Create the new object
8+
ref: realm-studio-create-the-new-object
9+
content: |
10+
Once you've decided where to create your new object, you can do this in
11+
two ways:
12+
13+
- Click the :guilabel:`Create {Class name}` button in the upper right
14+
corner of the app
15+
- Right click (or control click) anywhere in the main window to bring
16+
up the contextual menu, and select :guilabel:`Create new {Class name}`
17+
18+
Either option will open a dialog where you can set the properties
19+
for the object. When you've specified the required properties, press the
20+
:guilabel:`Create` button.
21+
22+
If you create an orphaned object that is not associated with a parent
23+
object via a linking property, you'll need to add it manually to the
24+
linked object. See: :ref:`Modify an Object <realm-studio-modify-an-object>`.

‎source/includes/steps-realm-studio-import-from-csv.yaml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
title: Browse to the Import from CSV option
2+
ref: realm-studio-import-from-csv-option
3+
content: |
4+
In Realm Studio, go to: :guilabel:`File` > :guilabel:`Import data from` > :guilabel:`CSV`
5+
---
6+
title: Select a CSV to import
7+
ref: realm-studio-import-from-csv-select-csv
8+
content: |
9+
Browse to the location of your CSV file, and select it.
10+
11+
Press the :guilabel:`Open` button.
12+
---
13+
title: Choose the destination class for your objects
14+
ref: realm-studio-import-from-csv-choose-destination-class
15+
content: |
16+
You'll see a drop-down selector containing the available classes in
17+
your {+realm+} file. Select the class where the imported data should
18+
become objects.
19+
20+
Press the :guilabel:`Import data` button.
21+
22+
Now you'll see newly-created objects created from the data you imported.
23+
Each object's properties map to the properties of the class you selected
24+
during import.

‎source/studio.txt

+27-38
Original file line numberDiff line numberDiff line change
@@ -4,50 +4,39 @@
44
Realm Studio
55
============
66

7+
.. toctree::
8+
:titlesonly:
9+
:hidden:
10+
11+
Install Realm Studio </studio/install>
12+
Open a Realm File </studio/open-realm-file>
13+
Explore a Realm File </studio/explore-realm-file>
14+
Modify a Realm File </studio/modify-objects>
15+
Modify Schema </studio/modify-schema>
16+
717
Get Started with Realm Studio
818
-----------------------------
919

10-
Realm Studio is a developer tool for desktop operating systems that
11-
allows you to manage Realm Database instances. With Realm Studio, you
12-
can open and edit local and synced realms. It supports Mac, Windows, and
13-
Linux.
20+
Realm Studio is a visual tool to view, edit, and design {+client-database+}
21+
files. With Realm Studio, developers can:
22+
23+
- Query objects in the database
24+
- View live objects in realtime while running an app
25+
- Create, modify, and delete objects
26+
- Add classes and properties to the schema
27+
- Export the schema as class definitions in C#, Java, JavaScript, Kotlin,
28+
Swift, and TypeScript
29+
- Save and import changes into a client app or production database
1430

1531
.. image:: /images/realm-studio.png
1632
:alt: A screenshot of Realm Studio
1733

18-
See :github:`Releases on GitHub <realm/realm-studio/releases/latest>`:
19-
20-
- `Download for Linux <https://studio-releases.realm.io/latest/download/linux-appimage>`_
21-
- `Download for Mac <https://studio-releases.realm.io/latest/download/mac-dmg>`_
22-
- `Download for Windows <https://studio-releases.realm.io/latest/download/win-setup>`_
23-
24-
.. _find-the-default-realm-path:
25-
26-
Find the Realm File(s)
27-
----------------------
28-
29-
{+client-database+} stores a binary encoded version of every object and type in a
30-
realm in a single ``.realm`` file. The file is located at a specific path that
31-
you define when you open the realm.
32-
33-
.. tabs-realm-languages::
34-
35-
.. tab::
36-
:tabid: swift
37-
38-
In Swift app development, you can find the current path of the
39-
default {+realm+} by pausing the simulator and using the LLDB console:
40-
41-
.. code-block:: swift
42-
43-
(lldb) po Realm.Configuration.defaultConfiguration.fileURL
44-
45-
.. tab::
46-
:tabid: objective-c
47-
48-
In Objective-C app development, you can find the current path of the
49-
default {+realm+} by pausing the simulator and using the LLDB console:
34+
View Realm Studio Releases
35+
--------------------------
5036

51-
.. code-block:: objective-c
37+
You can see a list of all releases at `Realm Studio Releases <https://studio-releases.realm.io/>`_.
38+
Click a version number to view a page listing enhancements, fixes, and
39+
file downloads for that version.
5240

53-
(lldb) po [RLMRealmConfiguration defaultConfiguration].fileURL
41+
Alternately, you can view :github:`Releases on GitHub <realm/realm-studio/releases/latest>`,
42+
as well as track and file issues for Realm Studio.

‎source/studio/explore-realm-file.txt

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
.. _realm-studio-explore-realm-file:
2+
3+
====================
4+
Explore a Realm File
5+
====================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
When you open a {+realm+} file in Realm Studio, you can:
19+
20+
- View live objects in realtime
21+
- Query objects in the {+realm+}
22+
- Export SDK model definitions
23+
24+
This makes it a valuable tool for developing and debugging applications
25+
backed by {+client-database+}.
26+
27+
View Live Objects in Realtime
28+
-----------------------------
29+
30+
Realm Studio gives you the ability to view live objects while you're
31+
running a client app in an emulator. You can see how functions in your
32+
app are transforming objects in realtime. This is a powerful debugging
33+
and development tool.
34+
35+
To view live objects in Realm Studio, you'll need to :ref:`find your {+realm+}
36+
file <realm-studio-find-a-realm-file>`. Once you know your {+realm+} file
37+
path, you can open it in Realm Studio while your app is running.
38+
39+
.. note::
40+
41+
Unfortunately, Android emulators do not support viewing live objects
42+
in Realm Studio. If you're developing for Android, you must download
43+
the file from the emulator before you can access it.
44+
45+
Query Objects in the Realm
46+
--------------------------
47+
48+
Realm Studio enables you to query the objects in the {+realm+} file. The
49+
ability to do this in the {+realm+} via Realm Studio gives you a visual
50+
tool to:
51+
52+
- Quickly view query results
53+
- Experiment with query syntax
54+
- Validate the data in the {+realm+} file
55+
56+
The Realm Studio query bar at the top of the main pane
57+
accepts the :ref:`{+client-database+} JavaScript query syntax<node-client-query-engine>`.
58+
You can query using:
59+
60+
- Comparison operators
61+
- Logical operators
62+
- String operators
63+
64+
You can also view a reference document that details the query options from
65+
within Realm Studio. Press the :guilabel:`?` button next to the query bar.
66+
67+
Export SDK Model Definitions
68+
----------------------------
69+
70+
Realm Studio enables you to export model definitions, streamlining
71+
cross-platform development.
72+
73+
For example, you may be an iOS developer who has already created a
74+
schema in an existing app. You now need to declare the same schema for
75+
your Android app. Recreating that schema in another programming language
76+
can be time-consuming and error-prone. Instead, you can open your {+realm+}
77+
file in Realm Studio, and export the model definition in Java.
78+
79+
.. include:: /includes/realm-studio-export-class-definitions.rst

0 commit comments

Comments
 (0)