diff --git a/src/SUMMARY.md b/src/SUMMARY.md index bc86ea5..94b8758 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -36,6 +36,7 @@ * [Atomizing](atomizing.md) * [Using Atomic-Server](atomic-server.md) + * [Using Atomic-Data-Browser](atomic-browser.md) * [Creating a JSON-AD file](create-json-ad.md) * [Upgrade your existing project](interoperability/upgrade.md) diff --git a/src/atomic-browser.md b/src/atomic-browser.md new file mode 100644 index 0000000..26e22e4 --- /dev/null +++ b/src/atomic-browser.md @@ -0,0 +1,97 @@ +# Accessing the Atomic-Server by using the Atomic-Browser + +After installing your server you can access it with your browser. +By default, that's [`http://localhost:9883`](http://localhost:9883).
+Fun fact: `⚛` is HTML entity code for the Atom icon: ⚛. + +Alternatively use the demo installation at atomicdata.dev. + +## The Homepage, Your Drive + +The first screen should show you your [_Drive_](https://atomicdata.dev/classes/Drive). +You can think of this as your root folder. +It is the resource hosted at the root URL, effectively being the home page of your server. + +## Quick Setup - Creating a User/Agent +There's an instruction on the screen about the `/setup` page. +Click this, and you'll get a screen showing an [_Invite_](https://atomicdata.dev/classes/Invite). +Normally, you could `Accept as new user`, but since you're running on `localhost`, you won't be able to use the newly created Agent on non-local Atomic-Servers. +Therefore, it may be best to create an Agent on some _other_ running server, such as the [demo Invite on AtomicData.dev](https://atomicdata.dev/invites/1). +And after that, copy the Secret from the `User settings` panel from AtomicData.dev, go back to your `localhost` version, and press `sign in`. +Paste the Secret, and voila! You're signed in. + +Now, again go to `/setup`. This time, you can `Accept as {user}`. +After clicking, your Agent has gotten `write` rights for the Drive! +You can verify this by hovering over the description field, clicking the edit icon, and making a few changes. +You can also press the menu button (three dots, top left) and press `Data view` to see your agent after the `write` field. +Note that you can now edit every field. +You can also fetch your data now as various formats. + +Try checking out the other features in the menu bar, and check out the `collections`. + +Again, check out the [README](https://github.com/atomicdata-dev/atomic-data-rust/blob/master/server/README.md) for more information and guides! + +But first, understand the two Views of the Browser. + +## Understanding the two Views of the Browser +The Atomic Browser has two views + +* Edit View `(Ctrl+E)` +* Data View `(Ctrl+D)` + +After installation your browser will be in `Edit View`, also known as 'Data Definitions' View. This means you will be viewing, browsing and editing the Data Definitions. +A simple `Ctrl+D` will switch you to `Data View` which will hide the data definitions but instead make all the data occurrences visible for viewing, browsing and editing. Just use `(Ctrl+E)` to switch back. + +Now, we are ready to create some data. + +## Creating your first Atomic Data + +Now, in Edit View, let's create a [_Class_](https://atomicdata.dev/classes/Class). +A Class represents an abstract concept, such as a `BlogPost` (which we'll do here). +We can do this in a couple of ways: + +- Press the `+ icon` button on the left menu (only visible when logged in), and selecting Class +- Opening [Class](https://atomicdata.dev/classes/Class) and pressing `new class` +- Going to the [Classes Collection](https://atomicdata.dev/classes/) and pressing the plus icon + +The result is the same: we end up with a form in which we can fill in some details. + +Let's add a shortname (singular, lower case), and then a description. + +After that, we'll add the `required` properties. +This form you're looking at is constructed by using the `required` and `recommended` Properties defined in `Class`. +We can use these same fields to generate our BlogPost resource! +Which fields would be required in a `BlogPost`? +A `name`, and a `description`, probably. + +So click on the `+ icon` under `requires` and search for these Properties to add them. + +Now, we can skip the `recommended` properties, and get right to saving our newly created `BlogPost` class. +So, press save, and now look at what you created. + +Notice a couple of things: + +- Your Class has its own URL. +- It has a `parent`, shown in the top of the screen. This has impact on the visibility and rights of your Resource. We'll get to that [later in the documentation](./hierarchy.md). + +Now, go to the navigation bar, which is by default at the bottom of the window. Use its context menu to open the `Data View`. +This view gives you some more insight into your newly created data, and various ways in which you can serialize it. + +## How can I see the members of a collection? + +The members of a collection are the actual data of that collection, and thus you need to be in [the Data View](#understanding-the-two-views-of-the-browser) `(Ctrl+D)` to see them. + +> While in [the Data View](#understanding-the-two-views-of-the-browser), clicking on `collections` in the left menu brings you to the list of members of the `collections` class. Clicking on one of its members, for example `classes` will show you the list of classes. + +Now let us do that again but with some View switching to notice how that might confuse you in the beginning: + +> So again, while in [the Data View](#understanding-the-two-views-of-the-browser), click on `collections` in the left menu. You will see all the collections. Now press `Ctrl+E`. As expected that brings you to the Edit View of the `collections` class.
+But now, press `Ctrl+D`... where are the collections? Yet another View? No, this indeed is data of the `collections` class, only the metadata. What you were expecting to see is the `subject` data, which is one click away, namely the subject link on top of this list of metadata. + +## There's more! + +This was just a very brief introduction to Atomic Server, and its features. +There's quite a bit that we didn't dive in to, such as versioning, file uploads, the collaborative document editor and more... +But by clicking around you're likely to discover these features for yourself. + +In the next page, we'll dive into how you can create an publish JSON-AD files. diff --git a/src/atomic-server.md b/src/atomic-server.md index 8d58bf5..16f8acf 100644 --- a/src/atomic-server.md +++ b/src/atomic-server.md @@ -1,13 +1,5 @@ # Creating Atomic Data using Atomic-Server -Here is everything you need to get started: - - - [Atomic-Server and its features](#atomic-server-and-its-features) - - [Running Atomic-Server locally (optional)](#running-atomic-server-locally-optional) - - [Creating an Agent](#creating-an-agent) - - [Creating your first Atomic Data](#creating-your-first-atomic-data) - - [Next steps](#theres-more) - ## Atomic-Server and its features [`Atomic-Server`](https://github.com/atomicdata-dev/atomic-data-rust/blob/master/server/README.md) is the _reference implementation_ of the Atomic Data Core + Extended specification. @@ -32,10 +24,17 @@ It's free, open source (MIT license), and has a ton of features: - 📂 **File management**: Upload, download and preview attachments. - 🖥️ **Desktop app**: Easy desktop installation, with status bar icon, powered by [tauri](https://github.com/tauri-apps/tauri/). +## Using the Atomic-Server + +You can use the Atomic-Server with the build in [Atomic-Browser](./atomic-browser.md).
+Take a look at the demo installation at atomicdata.dev or [install your own copy of the server](#running-atomic-server-locally-optional). + ## Running Atomic-Server locally (optional) -In this guide, we'll can simply use `atomicdata.dev` in our browser without installing anything. -So you can skip this step and go to _Creating your first Atomic Data_. +In this guide, we'll can simply use atomicdata.dev in our browser without installing anything. +So you can skip this step and go to [Using the Atomic-Server](#using-the-atomic-server). + +If you just want to try out the Atomic server, you can use the demo But if you want to, you can run Atomic-Server on your machine in a couple of ways: - **Using a desktop installer**: download a desktop release from the [`releases`](https://github.com/atomicdata-dev/atomic-data-rust/releases) page and install it using your desktop GUI. @@ -45,80 +44,4 @@ But if you want to, you can run Atomic-Server on your machine in a couple of way _[Atomic-Server's README](https://github.com/atomicdata-dev/atomic-data-rust/blob/master/server/README.md) contains more (and up-to-date) information about how to use it!_ -Open your server in your browser. -By default, that's [`http://localhost:9883`](http://localhost:9883). -Fun fact: `⚛` is HTML entity code for the Atom icon: ⚛. - -The first screen should show you your [_Drive_](https://atomicdata.dev/classes/Drive). -You can think of this as your root folder. -It is the resource hosted at the root URL, effectively being the home page of your server. - -There's an instruction on the screen about the `/setup` page. -Click this, and you'll get a screen showing an [_Invite_](https://atomicdata.dev/classes/Invite). -Normally, you could `Accept as new user`, but since you're running on `localhost`, you won't be able to use the newly created Agent on non-local Atomic-Servers. -Therefore, it may be best to create an Agent on some _other_ running server, such as the [demo Invite on AtomicData.dev](https://atomicdata.dev/invites/1). -And after that, copy the Secret from the `User settings` panel from AtomicData.dev, go back to your `localhost` version, and press `sign in`. -Paste the Secret, and voila! You're signed in. - -Now, again go to `/setup`. This time, you can `Accept as {user}`. -After clicking, your Agent has gotten `write` rights for the Drive! -You can verify this by hovering over the description field, clicking the edit icon, and making a few changes. -You can also press the menu button (three dots, top left) and press `Data view` to see your agent after the `write` field. -Note that you can now edit every field. -You can also fetch your data now as various formats. - -Try checking out the other features in the menu bar, and check out the `collections`. - -Again, check out the [README](https://github.com/atomicdata-dev/atomic-data-rust/blob/master/server/README.md) for more information and guides! - -Now, let's create some data. - -## Creating an Agent - -Before you can create new things on AtomicData.dev, you'll need an _Agent_. -This is your virtual User, which can create, sign and own things. - -Simply open the [demo invite](https://atomicdata.dev/invites/1) and press accept. -And you're done! - - -## Creating your first Atomic Data - -Now let's create a [_Class_](https://atomicdata.dev/classes/Class). -A Class represents an abstract concept, such as a `BlogPost` (which we'll do here). -We can do this in a couple of ways: - -- Press the `+ icon` button on the left menu (only visible when logged in), and selecting Class -- Opening [Class](https://atomicdata.dev/classes/Class) and pressing `new class` -- Going to the [Classes Collection](https://atomicdata.dev/classes/) and pressing the plus icon - -The result is the same: we end up with a form in which we can fill in some details. - -Let's add a shortname (singular), and then a description. - -After that, we'll add the `required` properties. -This form you're looking at is constructed by using the `required` and `recommended` Properties defined in `Class`. -We can use these same fields to generate our BlogPost resource! -Which fields would be required in a `BlogPost`? -A `name`, and a `description`, probably. - -So click on the `+ icon` under `requires` and search for these Properties to add them. - -Now, we can skip the `recommended` properties, and get right to saving our newly created `BlogPost` class. -So, press save, and now look at what you created. - -Notice a couple of things: - -- Your Class has its own URL. -- It has a `parent`, shown in the top of the screen. This has impact on the visibility and rights of your Resource. We'll get to that [later in the documentation](./hierarchy.md). - -Now, go to the navigation bar, which is by default at the bottom of the window. Use its context menu to open the `Data View`. -This view gives you some more insight into your newly created data, and various ways in which you can serialize it. - -## There's more! - -This was just a very brief introduction to Atomic Server, and its features. -There's quite a bit that we didn't dive in to, such as versioning, file uploads, the collaborative document editor and more... -But by clicking around you're likely to discover these features for yourself. - -In the next page, we'll dive into how you can create an publish JSON-AD files. +You can now start using the Atomic-Server with the build in [Atomic-Browser](./atomic-browser.md) which we will explain in the next page.