Skip to content
This repository was archived by the owner on Jul 12, 2023. It is now read-only.

Commit 49fb32d

Browse files
valpackettvalpackett
committed
New readme instructions
1 parent 4cc6fb2 commit 49fb32d

File tree

1 file changed

+105
-5
lines changed

1 file changed

+105
-5
lines changed

‎README.md‎

Lines changed: 105 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,114 @@
22

33
# micro-panel
44

5-
**WIP: the whole thing is being rewritten from scratch**
5+
micro-panel is a set of [Web Components] that provide an interface for editing [posts] on your website using the [Micropub] protocol from the [IndieWeb].
66

7-
micro-panel is a set of Web Components for editing IndieWeb sites.
7+
(Actually, it doesn't have to be just posts! The [Sweetroll] engine gets away with using micro-panel as its one and only admin interface, because everything -- site configuration, categories, etc. -- is shoehorned into micropub-editable objects.)
88

9-
micro-panel is a part of [Sweetroll](https://github.com/myfreeweb/sweetroll), but it's usable as a completely independent tool.
10-
It just likes engines that put *everything* into Microformats2 objects :)
9+
[Web Components]: https://developers.google.com/web/fundamentals/web-components/
10+
[posts]: https://indieweb.org/posts
11+
[Micropub]: https://micropub.net/
12+
[IndieWeb]: https://indieweb.org/
13+
[Sweetroll]: https://github.com/myfreeweb/sweetroll
1114

12-
Also check out [indieweb-components](https://github.com/myfreeweb/indieweb-components) for some small components to enhance your website.
15+
## Requirements
16+
17+
To use micro-panel, your website needs to
18+
19+
- have a Micropub endpoint (duh) that
20+
- supports browser session (cookie) authentication, i.e. you can "just log in" on your website and send micropub requests, without going through OAuth/IndieAuth and stuff (which technically violates [the spec](https://www.w3.org/TR/micropub/#authentication-1) :D)
21+
- supports [source content queries with `?q=source`](https://www.w3.org/TR/micropub/#source-content)
22+
- accepts [JSON requests](https://www.w3.org/TR/micropub/#json-syntax)
23+
- supports update and delete (if you want to be able to do these things, which you probably do)
24+
25+
## Installation
26+
27+
(TODO publish to npm // for now, build with `npm run build`)
28+
29+
First of all, put the bundled script somewhere on your server.
30+
31+
Then edit the templates, like in the (hopefully obvious) pseudocode below:
32+
33+
### Script loading
34+
35+
Just do it!
36+
37+
```html
38+
...
39+
{{if logged-in-as-admin}}
40+
<script defer src="/some/where/micro-panel-all.bundle.min.js"></script>
41+
{{else}}
42+
<script defer src="/some/where/indie-action.min.js"></script>
43+
{{endif}}
44+
</body>
45+
```
46+
47+
Note that micro-panel includes an implementation of the `indie-action` tag from [webactions] to allow you to easily e.g. like your own posts -- or actually not just your own posts if your site acts as a [reader]!
48+
So if you use a "guest" implementation to allow others to easily react to your posts -- such as the implementation from [indieweb-components] that uses [indie-config] -- load that one for non-admin users.
49+
50+
[webactions]: https://indieweb.org/webactions
51+
[reader]: https://indieweb.org/reader
52+
[indie-config]: https://indieweb.org/indie-config
53+
[indieweb-components]: https://github.com/myfreeweb/indieweb-components
54+
55+
If you want to try to support browsers without native [Custom Elements](https://caniuse.com/#feat=custom-elementsv1) & [Shadow DOM](https://caniuse.com/#feat=shadowdomv1), also load the [Web Components Polyfill](https://www.npmjs.com/package/@webcomponents/webcomponentsjs) loader (make sure you use `-loader.js`, DO NOT load the `-bundle.js` you don't want the whole 100kb of polyfills on browser that don't need them):
56+
57+
```html
58+
<head>
59+
...
60+
<script src="/whatever/webcomponentsjs/webcomponents-loader.js"></script>
61+
```
62+
63+
But hey, it's an admin application, not a public application, so you only have to care about browsers *you* use.
64+
If all your Firefoxes are Nightly, you're fine without polyfills.
65+
(Actually, you might try enabling `about:config` flags on stable Firefox, that might work.)
66+
67+
### Editor and toolbar
68+
69+
Place the `micro-panel-editor` directly into the body.
70+
Beginning, end, doesn't matter -- it's a full screen overlay.
71+
Don't forget to provide your Micropub endpoint's URL!
72+
There's no smart detection, it doesn't look up in various links for simplicity reasons.
73+
74+
The `micro-panel-toolbar` is what provides the New post button.
75+
It's a normal block element.
76+
You can write custom styles to make it `position:sticky` or whatever.
77+
78+
```html
79+
<body>
80+
<micro-panel-editor hidden micropub="/your/micropub/endpoint"></micro-panel-editor>
81+
<micro-panel-toolbar></micro-panel-toolbar>
82+
...
83+
```
84+
85+
### Posts
86+
87+
In the post template, add a button or link wrapped in a `micro-panel-action`.
88+
The `with` attribute of the element will be used, without modification, for the `?q=source` Micropub request.
89+
So make sure that e.g. if it's relative here, your Micropub endpoint also understands relative URLs.
90+
91+
And as already mentioned, `indie-action` is also handled.
92+
93+
```html
94+
...
95+
<footer class="post-footer">
96+
{{if logged-in-as-admin}}
97+
<micro-panel-action with="{{permalink}}">
98+
<button>Edit</button>
99+
</micro-panel-action>
100+
{{endif}}
101+
<indie-action do="reply" with="{{permalink}}">
102+
<button>Reply</button>
103+
</indie-action>
104+
...
105+
</footer>
106+
```
107+
108+
## Usage
109+
110+
With the setup above, you should be ready to go!
111+
112+
Just log in to your website, click the New post or Edit buttons and enjoy.
13113

14114
## Contributing
15115

0 commit comments

Comments
 (0)