Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Moved Browser related information to separate page; Added some basic … #151

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Moved Browser related information to separate page; Added some basic … #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2823546
Moved Browser related information to seperate page; Added some basic …
robsiera Feb 10, 2023
9e6b83c
Update SUMMARY.md
joepio Mar 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
97 changes: 97 additions & 0 deletions src/atomic-browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Accessing the Atomic-Server by using the Atomic-Browser

After installing your server you can access it with your browser.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good place to link to the install instructions

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that it's on another page that becomes more important

By default, that's [`http://localhost:9883`](http://localhost:9883).<br/>
Fun fact: `&#9883;` is HTML entity code for the Atom icon: ⚛.

Alternatively use the demo installation at <a href="https://atomicdata.dev" target="_blank">atomicdata.dev</a>.

## 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add an image or two

![Beschrijving](../assets/screenshots/plaatje.png)

## 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not entirely correct - there's also the normal view, which is the default.


* 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will be in normal view

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 <a href="https://docs.atomicdata.dev/schema/collections.html" target="_blank">collection</a> 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use markdown syntax for links

[collection](https://docs.atomicdata.dev/schema/collections.html)


> 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. <br/>
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.
97 changes: 10 additions & 87 deletions src/atomic-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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).<br/>
Take a look at the demo installation at <a href="https://atomicdata.dev" target="_blank">atomicdata.dev</a> 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 <a href="https://atomicdata.dev" target="_blank">atomicdata.dev</a> 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's missing something here right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just a dot

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.
Expand All @@ -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: `&#9883;` 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

built-in