Commit b775d0d2069e9ecf1c7928c83c2930993636a5e2
README: highlight some key modules
mix irving committed on 4/15/2018, 8:42:50 PMParent: 8fc2a74abce74dbdf19b270cda8853ea0cb6f587
Files changed
| README.md | changed |
| README.md | |||
|---|---|---|---|
| @@ -1,16 +1,63 @@ | |||
| 1 | 1 … | # Patchbay | |
| 2 | 2 … | ||
| 3 | -`patchbay` is a secure-scuttlebutt client interface that is fully compatible with [patchwork](https://github.com/ssbc/patchwork). | ||
| 3 … | +Patchbay is a scuttlebutt client designed to be easy to modify and extend. | ||
| 4 … | +It uses the same database as Patchwork and Patchfoo, so you can easily take it for a spin with your existing identity. | ||
| 4 | 5 … | ||
| 5 | 6 … |  | |
| 6 | 7 … | ||
| 7 | -Patchbay is built using [patchcore](https://github.com/ssbc/patchcore) + [depject](https://github.com/dominictarr/depject). The goal is to make it easier to develop new features, and enable or disable features. This has so far been quite successful! | ||
| 8 … | +Patchbay was created by Dominic Tarr towards the end of the life of Patchwork v1. | ||
| 9 … | +It was born our out of the observation that maintaining a large client apps can be really hard work. | ||
| 10 … | +Patchbay was designed to sidestep this by using some technology ([`depject`](https://github.com/dominictarr/depject)) to make parts easier to swap and extend. | ||
| 8 | 11 … | ||
| 9 | -This makes in very easy to create say, a renderer for a new message type, or switch to a different method for choosing user names. | ||
| 12 … | +Patchbay now shares a common core library ([`patchcore`](https://github.com/ssbc/patchcore)) with Patchwork, and connects this in using the `depject` | ||
| 13 … | +This is another experiment in sharing useful code and mainmtenance. | ||
| 10 | 14 … | ||
| 11 | -## Setup | ||
| 15 … | +Current features boasted: | ||
| 16 … | +- gatherings - a booking system | ||
| 17 … | +- chess - p2p chess games and chat | ||
| 18 … | +- bookblub - a book review interface | ||
| 19 … | +- blogs - can read blogposts created in Ticktack | ||
| 12 | 20 … | ||
| 21 … | +## Install | ||
| 22 … | + | ||
| 23 … | +Download easy installer for Mac / Windows / Linux here : https://github.com/ssbc/patchbay/releases | ||
| 24 … | + | ||
| 25 … | +If you'd like to hack on Patchbay, check out the Developer Install below. | ||
| 26 … | + | ||
| 27 … | +## Keyboard shortcuts | ||
| 28 … | + | ||
| 29 … | +`CmdOrCtrl` is the `command` key on Apple keyboards or the `ctrl` key on PC keyboards. | ||
| 30 … | + | ||
| 31 … | +### Tabs and window | ||
| 32 … | + | ||
| 33 … | +- `h` / `CmdOrCtrl+Shift+]` : tabs left | ||
| 34 … | +- `j` / `CmdOrCtrl+Shift+[`: tabs right | ||
| 35 … | +- `x` / `CmdOrCtrl+w` : close tab | ||
| 36 … | +- `CmdOrCtrl+Shift+w` will close the current window | ||
| 37 … | + | ||
| 38 … | +### Message feeds | ||
| 39 … | + | ||
| 40 … | +`j` : next message (down) | ||
| 41 … | +`k` : previous message | ||
| 42 … | +`o` : open message thread (and scroll to position of this message in that thread) | ||
| 43 … | +` ` ` : toggle raw message view for currently selected message (` ` ` = backtick, lives on the same key as `~`) | ||
| 44 … | + | ||
| 45 … | +composing : cttrl + enter = post | ||
| 46 … | + | ||
| 47 … | +### Nav bar thing | ||
| 48 … | + | ||
| 49 … | +`@` : start a person query | ||
| 50 … | +`#` : start a channel query | ||
| 51 … | +`?` : start a search query | ||
| 52 … | +`/` : start a navigation (e.g. /public) - need to re-instate suggestions for this | ||
| 53 … | + | ||
| 54 … | +you can also paste a message id (starts with `%`) in here to navigate to it. Same with blobs (`&`) | ||
| 55 … | + | ||
| 56 … | +--- | ||
| 57 … | + | ||
| 58 … | +## Developer Install | ||
| 59 … | + | ||
| 13 | 60 … | Libsodium has some build dependencies. On ubuntu systems the following might help: | |
| 14 | 61 … | ||
| 15 | 62 … | ```sh | |
| 16 | 63 … | sudo apt-get install m4 libtool eclipse-cdt-autotools | |
| @@ -71,9 +118,8 @@ | |||
| 71 | 118 … | ``` | |
| 72 | 119 … | ||
| 73 | 120 … | ## Running the desktop app | |
| 74 | 121 … | ||
| 75 | - | ||
| 76 | 122 … | Easy mode (embedded sbot): | |
| 77 | 123 … | ```sh | |
| 78 | 124 … | # from the patchbay repo folder | |
| 79 | 125 … | npm start | |
| @@ -86,56 +132,59 @@ | |||
| 86 | 132 … | # from the patchbay repo folder | |
| 87 | 133 … | npm run dev | |
| 88 | 134 … | ``` | |
| 89 | 135 … | ||
| 90 | -## Keyboard shortcuts | ||
| 91 | -`CmdOrCtrl` is the `command` key on Apple keyboards or the `ctrl` key on PC keyboards. | ||
| 136 … | +## Development | ||
| 92 | 137 … | ||
| 93 | -### Tabs and Window | ||
| 94 | -- `CmdOrCtrl+Shift+]` and `CmdOrCtrl+Shift+[` will cycle the tabs left and right | ||
| 95 | -- `CmdOrCtrl+w` will close the current tab | ||
| 96 | -- `CmdOrCtrl+Shift+w` will close the current window | ||
| 138 … | +### Key depject modules in Patchbay | ||
| 97 | 139 … | ||
| 98 | -## How to add a feature | ||
| 140 … | +Here's a quick high level overview of the depject modules you're going to want to know about: | ||
| 99 | 141 … | ||
| 100 | -To add a new message type, add add a js to `./modules/` that exports a function named `message_content` (it should return an HTML element). To add a new tab, export a function named `screen_view` (returns an html element). | ||
| 142 … | +#### `app.html.app` | ||
| 101 | 143 … | ||
| 102 | -To add a new detail, that appears above a message, export a function named `message_meta`. | ||
| 144 … | +The top level module which starts the front end js. | ||
| 103 | 145 … | ||
| 104 | -See the code for more examples. | ||
| 146 … | +#### `app.sync.initialise` | ||
| 105 | 147 … | ||
| 148 … | +A collection of function which are called on app start. | ||
| 149 … | +Does things like load css into the app, set up custom listeners, set default settings | ||
| 106 | 150 … | ||
| 107 | -## Keyboard shortcuts | ||
| 151 … | +#### `app.sync.goTo(location)` | ||
| 108 | 152 … | ||
| 109 | -## Tabs | ||
| 153 … | +The function you call when you want to open a new location. | ||
| 154 … | +`location` can be a string (like a message or blob id) or an object. | ||
| 110 | 155 … | ||
| 111 | -`h` : tabs left | ||
| 112 | -`j` : tabs right | ||
| 113 | -`x` : close tab | ||
| 156 … | +Note - some locations are _normalised_ before being passed onto the router. | ||
| 157 … | +Check out `router.async.normalise` for explicit detail. | ||
| 114 | 158 … | ||
| 115 | -## Message feeds | ||
| 159 … | +#### `router.sync.router` | ||
| 116 | 160 … | ||
| 117 | -`j` : next message (down) | ||
| 118 | -`k` : previous message | ||
| 119 | -`o` : open message thread (and scroll to position of this message in that thread) | ||
| 120 | -` ` ` : toggle raw message view for currently selected message (` ` ` = backtick, lives on the same key as `~`) | ||
| 161 … | +This is the module where you can add routes to the app. | ||
| 162 … | +This is ultimately reduced along with all other `router.sync.router` modules into the final router. | ||
| 121 | 163 … | ||
| 122 | -composing : cttrl + enter = post | ||
| 164 … | +#### `app.html.settings` | ||
| 123 | 165 … | ||
| 124 | -## Nav bar thing | ||
| 166 … | +Giving modules here will add settings sections to the settings page (`app.page.settings`). | ||
| 125 | 167 … | ||
| 126 | -`@` : start a person query | ||
| 127 | -`#` : start a channel query | ||
| 128 | -`?` : start a search query | ||
| 129 | -`/` : start a navigation (e.g. /public) - need to re-instate suggestions for this | ||
| 130 | 168 … | ||
| 131 | -you can also paste a message id (starts with `%`) in here to navigate to it. Same with blobs (`&`) | ||
| 169 … | +### How to add a new page | ||
| 132 | 170 … | ||
| 171 … | +e.g. to add a 'cats' page to the app: | ||
| 133 | 172 … | ||
| 134 | -## Module graph | ||
| 173 … | +- Add a file `app/page/cats.js` which gives `app.page.cats` | ||
| 174 … | +- Tell the router to send people browsing to location `{page: 'cats'}` to send them to this page | ||
| 175 … | + - route will look like `[location => location.page === 'cats', api.app.page.cats]` | ||
| 176 … | + - Note the normaliser will automaticall turn location `/cats` to `{page: 'cats'}` | ||
| 177 … | +- Add a link somewhere which will trigger that route: | ||
| 178 … | + - e.g. activate`api.app.sync.goTo('/cats')` onclick | ||
| 179 … | + - e.g. add a link `<a href='/cats'>Cats!</a>` (which will be clicked up by listeners) | ||
| 135 | 180 … | ||
| 136 | -TODO - reinstate this | ||
| 137 | 181 … | ||
| 182 … | + | ||
| 183 … | +### Module graph | ||
| 184 … | + | ||
| 185 … | +TODO! | ||
| 186 … | + | ||
| 138 | 187 … | ## License | |
| 139 | 188 … | ||
| 140 | 189 … | MIT | |
| 141 | 190 … | ||
Built with git-ssb-web