Skip to content

Commit d8b7ee4

Browse files
angelo-vangelo-v
committed
doc(homepage): Displaying data guide
1 parent 4b9b154 commit d8b7ee4

File tree

3 files changed

+199
-19
lines changed

3 files changed

+199
-19
lines changed

‎homepage/docs/getting-started/.nav.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ nav:
22
- Building dashboards:
33
- quick-start.md
44
- installation.md
5+
- displaying-data.md

‎homepage/docs/getting-started/demo.html‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -14,31 +14,33 @@
1414
/>
1515
</head>
1616
<style>
17-
body {
18-
main {
19-
padding: 4rem;
20-
margin: 1rem;
21-
border-radius: 1rem;
22-
background-color: var(--pos-background-color);
23-
}
17+
pos-app {
18+
display: block;
19+
padding: 4rem;
20+
margin: 1rem;
21+
border-radius: 1rem;
22+
background-color: var(--pos-background-color);
23+
}
24+
pos-resource {
25+
display: flex;
26+
gap: 1rem;
27+
align-items: center;
2428
}
2529
</style>
2630
<body>
2731
<main>
2832
<pos-app>
2933
<pos-resource uri="https://pod-os.solidcommunity.net/profile/card#me">
30-
<div style="display: flex; gap: 1rem; align-items: center">
31-
<pos-picture></pos-picture>
32-
<section>
33-
<h1>
34-
Welcome to
35-
<pos-label></pos-label>
36-
</h1>
37-
<blockquote>
38-
<pos-description></pos-description>
39-
</blockquote>
40-
</section>
41-
</div>
34+
<pos-picture></pos-picture>
35+
<section>
36+
<h1>
37+
Welcome to
38+
<pos-label></pos-label>
39+
</h1>
40+
<blockquote>
41+
<pos-description></pos-description>
42+
</blockquote>
43+
</section>
4244
</pos-resource>
4345
</pos-app>
4446
</main>

‎homepage/docs/getting-started/displaying-data.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
After PodOS has been included on your page, let's take a look at how to show some data about things on the web.
2+
3+
We will go through these for steps:
4+
5+
1. Define a new app
6+
2. Refer to a resource on the web
7+
3. Show label and description of that resource
8+
4. Mix and match with plain HTML
9+
5. Show a picture of the resource
10+
11+
??? question "What is a resource?"
12+
13+
A resource is anything on the Web identified by a URI (Uniform Resource Identifier).
14+
Most contents on the Web are *pages*, that can be found by their URL (Uniform Resource Locator).
15+
With PodOS and Solid, we are going beyond pages: *Anything* can be identified by a URI and when this URI resolves to
16+
data, then PodOS will be able to show it.
17+
18+
## Define a new app
19+
20+
Anything you want to do with PodOS needs to be wrapped in `<pos-app></pos-app>`
21+
22+
```html
23+
24+
<body>
25+
<pos-app>
26+
<!-- your app goes here -->
27+
</pos-app>
28+
</body>
29+
```
30+
31+
Whenever you add other PodOS elements to your page, make sure they are placed inside `pos-app`. This ensures that
32+
the child elements get access to PodOS functionality.
33+
34+
## Refer to a resource
35+
36+
Now that we have an app, we can refer to a resource we want to display information about.
37+
38+
First, we need the URI of the resource in question. The PodOS project has a URI at solidcommunity.net, that serves some
39+
data:
40+
41+
```
42+
https://pod-os.solidcommunity.net/profile/card#me
43+
```
44+
45+
To fetch the data of that resource and make it available for further usage, add a `<pos-resource>` into the app:
46+
47+
```html hl_lines="2-3"
48+
49+
<pos-app>
50+
<pos-resource uri="https://pod-os.solidcommunity.net/profile/card#me">
51+
</pos-resource>
52+
</pos-app>
53+
```
54+
55+
!!! tip
56+
57+
If you already own a Solid Pod, you can also pass your WebID into the `uri` attribute.
58+
59+
If you open your page now, you might notice that the resource URI will be fetched from the network already, but nothing
60+
shows up yet. We will change that in a second.
61+
62+
## Show label and description
63+
64+
With `<pos-resource>` we set the context to a specific resource. Inside that element, we can now define what data we
65+
want to show.
66+
67+
Let's add
68+
69+
1. `pos-label` to show a human-readable name of the resource
70+
2. `pos-description` to get a short text describing what it is
71+
72+
```html hl_lines="3-4"
73+
74+
<pos-app>
75+
<pos-resource uri="https://pod-os.solidcommunity.net/profile/card#me">
76+
<pos-label></pos-label>
77+
<pos-description></pos-description>
78+
</pos-resource>
79+
</pos-app>
80+
```
81+
82+
!!! info
83+
84+
Both `pos-label` and `pos-description` try to be "smart" about what information to show. On the web there are multiple
85+
terms that could be used to state resource labels, e.g. `rdfs:label`, `schema:name` and more.
86+
PodOS tries to use the most fitting terms and falls back to others until it finds something it could show. If nothing is availabe
87+
`pos-label` will just show the resource URI as a last resort.
88+
89+
If you open the page now, you will see some content!
90+
91+
> PodOS An operating system for your personal online datastore
92+
93+
But it does not look very appealing, yet. This is where good old HTML and CSS come in.
94+
95+
## Mix in plain HTML and CSS
96+
97+
PodOS elements *extend* HTML, they do not replace it. On the contrary, you can use any HTML elements next to,
98+
around or (depending on the element) even inside PodOS elements.
99+
100+
Let's create a `section` with a `h1` heading and a `blockquote`. Use `pos-label` as part of the a heading and put
101+
`pos-description` into the `blockquote`:
102+
103+
```html
104+
105+
<section>
106+
<h1>
107+
Welcome to
108+
<pos-label></pos-label>
109+
</h1>
110+
<blockquote>
111+
<pos-description></pos-description>
112+
</blockquote>
113+
</section>
114+
```
115+
116+
Let's also add some style for `pos-app`:
117+
118+
```html
119+
120+
<style>
121+
pos-app {
122+
display: block;
123+
padding: 4rem;
124+
margin: 1rem;
125+
border-radius: 1rem;
126+
background-color: var(--pos-background-color);
127+
}
128+
</style>
129+
```
130+
131+
This should look a lot better already. But nothing compares to showing a picture.
132+
133+
!!! tip "Build in CSS variables"
134+
135+
Did you notice the `--pos-background-color` we are using here? PodOS comes with several of those variables built-in. You can find the available variables in [global.css](https://github.com/pod-os/PodOS/blob/main/elements/src/global.css). `--pos-background-color` is aware of the preferred color scheme and adjust to light and dark mode.
136+
137+
## Showing a picture
138+
139+
Adding a picture works the same as adding a label and description. You might have guessed it by now, add a `pos-picture`
140+
to your page:
141+
142+
```html hl_lines="2"
143+
144+
<pos-resource uri="https://pod-os.solidcommunity.net/profile/card#me">
145+
<pos-picture></pos-picture>
146+
<section>
147+
...
148+
</section>
149+
</pos-resource>
150+
```
151+
152+
We added it right next to the section with our label and description, so that we can now apply a nice flex layout to the
153+
`pos-resource`, so that the picture appears next to the text:
154+
155+
```css
156+
pos-resource {
157+
display: flex;
158+
gap: 1rem;
159+
align-items: center;
160+
}
161+
```
162+
163+
## The final page
164+
165+
Now let's take a look at the page we have built! You can find a living example at [demo.html](./demo.html). You can use
166+
your browsers "View source" feature to view the
167+
source, [or find it on GitHub](https://github.com/pod-os/PodOS/blob/main/homepage/docs/getting-started/demo.html).
168+
169+
## Element reference
170+
171+
Elements we have used in this guide:
172+
173+
- [pos-app](../reference/elements/components/pos-app/index.md)
174+
- [pos-resource](../reference/elements/components/pos-resource/index.md)
175+
- [pos-label](../reference/elements/components/pos-label/index.md)
176+
- [pos-description](../reference/elements/components/pos-description/index.md)
177+
- [pos-picture](../reference/elements/components/pos-picture/index.md)

0 commit comments

Comments
 (0)