aboutsummaryrefslogtreecommitdiff
path: root/devdoc
diff options
context:
space:
mode:
Diffstat (limited to 'devdoc')
-rw-r--r--devdoc/design-notes.md122
1 files changed, 89 insertions, 33 deletions
diff --git a/devdoc/design-notes.md b/devdoc/design-notes.md
index 0d7b5c1..9bca7c8 100644
--- a/devdoc/design-notes.md
+++ b/devdoc/design-notes.md
@@ -1,9 +1,13 @@
1# ldgallery design notes 1# ldgallery design notes
2 2
3_ldgallery_ consists of two main components that are packaged and distributed together, but are otherwise functionally independent: 3_ldgallery_ consists of two main components that are packaged and distributed
4together, but are otherwise functionally independent:
4 5
5* a __compiler__ which turns a collection of pictures and sidecar metadata files into their compressed/normalised and aggregated versions respectively, and 6* a __compiler__ which turns a collection of pictures and sidecar metadata
6* a web __viewer__ in the form of a single-page application, rendering the output of the compiler as a searchable picture gallery. 7 files into their compressed/normalised and aggregated versions respectively,
8 and
9* a web __viewer__ in the form of a single-page application, rendering the
10 output of the compiler as a searchable picture gallery.
7 11
8 12
9## Gallery compiler 13## Gallery compiler
@@ -12,7 +16,9 @@ _ldgallery_ consists of two main components that are packaged and distributed to
12 16
13#### Directory structure 17#### Directory structure
14 18
15The compiler takes a source directory as input which shall contain item resource files and associated metadata sidecar files. Those items may be recursively grouped into multiple levels of sub-directories. 19The compiler takes a source directory as input which shall contain item
20resource files and associated metadata sidecar files. Those items may be
21recursively grouped into multiple levels of sub-directories.
16 22
17Example source directory structure: 23Example source directory structure:
18 24
@@ -31,9 +37,14 @@ example-gallery-source
31 37
32#### Metadata sidecar file 38#### Metadata sidecar file
33 39
34Metadata associated to items are stored in YAML sidecar files of the same name, with the `.yaml` extension appended. The use of plain text sidecar files allow for easier editing without any special tool in a unified manner for multiple types of files (pictures, videos, ebooks, ...). The metadata contained within item files are simply ignored. 40Metadata associated to items are stored in YAML sidecar files of the same name,
41with the `.yaml` extension appended. The use of plain text sidecar files allow
42for easier editing without any special tool in a unified manner for multiple
43types of files (pictures, videos, ebooks, ...). The metadata contained within
44item files are simply ignored.
35 45
36Tags are given with a group hierarchy separated by `.`, which allows generic searches as well as implicit disambiguation. 46Tags are given with a group hierarchy separated by `.`, which allows generic
47searches as well as implicit disambiguation.
37 48
38Example metadata sidecar file: 49Example metadata sidecar file:
39 50
@@ -55,16 +66,21 @@ tags:
55Possible evolutions: 66Possible evolutions:
56 67
57* Fallback values may later be defined for each field, making them optional. 68* Fallback values may later be defined for each field, making them optional.
58* The description field could be allowed to contain markdown-formatted content, which would be rendered by the __viewer__ app. 69* The description field could be allowed to contain markdown-formatted content,
59* Other keys could be added to allow the definition of specific transform/compilation/displaying parameters on a particular file. 70 which would be rendered by the __viewer__ app.
60* Metadata sidecar files could be added for directories as well in some `index.yaml` file. 71* Other keys could be added to allow the definition of specific
72 transform/compilation/displaying parameters on a particular file.
73* Metadata sidecar files could be added for directories as well in some
74 `index.yaml` file.
61 75
62 76
63#### Gallery configuration file 77#### Gallery configuration file
64 78
65The gallery YAML configuration file contains the __compiler__'s and the __viewer__'s settings in two different sections. 79The gallery YAML configuration file contains the __compiler__'s and the
80__viewer__'s settings in two different sections.
66 81
67Proposed configuration file, named `gallery.yaml` at the root of the source directory: 82Proposed configuration file, named `gallery.yaml` at the root of the source
83directory:
68 84
69```yaml 85```yaml
70compiler: 86compiler:
@@ -115,16 +131,23 @@ data
115 131
116#### Viewer configuration file 132#### Viewer configuration file
117 133
118The content of the `viewer` section of the gallery configuration file is used, without any transformation by the __compiler__, to generate the `viewer.json` file located at the root of the output directory. 134The content of the `viewer` section of the gallery configuration file is used,
135without any transformation by the __compiler__, to generate the `viewer.json`
136file located at the root of the output directory.
119 137
120 138
121#### Gallery items index 139#### Gallery items index
122 140
123The __compiler__ generates a global index file `index.json` aggregating the metadata of all the source sidecar files as a tree of items as described below. Its root node is a directory item. The type of each property node is marked by its `type` field. 141The __compiler__ generates a global index file `index.json` aggregating the
142metadata of all the source sidecar files as a tree of items as described below.
143Its root node is a directory item. The type of each property node is marked by
144its `type` field.
124 145
125Directory items aggregate their tags from the items below it in order to be displayed in search results. 146Directory items aggregate their tags from the items below it in order to be
147displayed in search results.
126 148
127Resource paths are rooted with respect to the data output directory which serves as the base path. 149Resource paths are rooted with respect to the data output directory which
150serves as the base path.
128 151
129Serialised item structure: 152Serialised item structure:
130 153
@@ -175,35 +198,53 @@ Serialised item structure:
175 198
176#### Normalised items and thumbnails 199#### Normalised items and thumbnails
177 200
178Gallery items are normalised and made available in the `items` sub-directory of the data output directory. Normalisation consists of optional transcoding and other transforms as configured by the user in the compiler part of the `gallery.yaml` configuration file. 201Gallery items are normalised and made available in the `items` sub-directory of
202the data output directory. Normalisation consists of optional transcoding and
203other transforms as configured by the user in the compiler part of the
204`gallery.yaml` configuration file.
179 205
180Thumbnails are also generated for those items and are placed in the `thumbnails` sub-directory. Thumbnails of pictures in particular are resized using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails may later be generated by picking or assembling one or multiple of its items, or defined explicitely by the user. 206Thumbnails are also generated for those items and are placed in the
207`thumbnails` sub-directory. Thumbnails of pictures in particular are resized
208using ~~Lanczos~~ (not available) bilinear resampling. Directory thumbnails
209may later be generated by picking or assembling one or multiple of its items,
210or defined explicitely by the user.
181 211
182The structure of the input directory is kept in both those output sub-directories. Input item files and directories also keep their original names. 212The structure of the input directory is kept in both those output
213sub-directories. Input item files and directories also keep their original
214names.
183 215
184 216
185## Gallery viewer 217## Gallery viewer
186 218
187The __viewer__ is a single-page web application which displays the gallery's content. 219The __viewer__ is a single-page web application which displays the gallery's
220content.
188 221
189It runs fully on the client's side and remains usable without any back-end. It renders the compiled resources from the `data` directory, placed at its root, generated by the __compiler__. 222It runs fully on the client's side and remains usable without any back-end. It
223renders the compiled resources from the `data` directory, placed at its root,
224generated by the __compiler__.
190 225
191 226
192### URL anchor 227### URL anchor
193 228
194The page anchor is updated and used by the application to reflect the state of its current state in such a way that any view can be shared and loaded back by copying the URL and its anchor. It should in particular contain the current directory or item, as well as the filtering query. 229The page anchor is updated and used by the application to reflect the state of
230its current state in such a way that any view can be shared and loaded back by
231copying the URL and its anchor. It should in particular contain the current
232directory or item, as well as the filtering query.
195 233
196 234
197### Directory/collection/grid view 235### Directory/collection/grid view
198 236
199The application starts by showing a grid view of the root directory of the gallery. 237The application starts by showing a grid view of the root directory of the
238gallery.
200 239
201This combined view offers the possiblity to the user to navigate to other items and to search recursively through the current directory. 240This combined view offers the possiblity to the user to navigate to other items
241and to search recursively through the current directory.
202 242
203 243
204#### Directory breadcrumbs 244#### Directory breadcrumbs
205 245
206The directory view displays the current directory path, with links allowing the user to navigate into parent ones. 246The directory view displays the current directory path, with links allowing the
247user to navigate into parent ones.
207 248
208``` 249```
209Gallery / Some directory / Sub-directory 250Gallery / Some directory / Sub-directory
@@ -212,28 +253,43 @@ Gallery / Some directory / Sub-directory
212 253
213#### Filering query 254#### Filering query
214 255
215A query field allows the user to search through and filter the items of the current directory and its sibling items recursively. This search field allows restriction on tags in a hierarchical manner. It should feature some sort of autocompletion, as well as an adjacent list of tags that are available for filtering. Positive as well as negative filtering should be possible, allowing the user to exclude some tags from the search results. 256A query field allows the user to search through and filter the items of the
257current directory and its sibling items recursively. This search field allows
258restriction on tags in a hierarchical manner. It should feature some sort of
259autocompletion, as well as an adjacent list of tags that are available for
260filtering. Positive as well as negative filtering should be possible, allowing
261the user to exclude some tags from the search results.
216 262
217For instance, the query `france -chessy` should match an item tagged with `location.france.paris`, but not `location.france.chessy`. 263For instance, the query `france -chessy` should match an item tagged with
264`location.france.paris`, but not `location.france.chessy`.
218 265
219The search is performed on the client side, either by scanning the item tree or with the use on some client-side indexer such as [Elasticlunr]. 266The search is performed on the client side, either by scanning the item tree or
267with the use on some client-side indexer such as [Elasticlunr].
220 268
221In addition to tag-based filtering, full-text search on the `title` and `description` could later be added by leveraging such indexer. 269In addition to tag-based filtering, full-text search on the `title` and
270`description` could later be added by leveraging such indexer.
222 271
223[Elasticlunr]: http://elasticlunr.com/ 272[Elasticlunr]: http://elasticlunr.com/
224 273
225 274
226#### Thumbnail grid 275#### Thumbnail grid
227 276
228The content of a directory are displayed as a grid of thumbnails which allows to navigate through sub-directories and to view items. 277The content of a directory are displayed as a grid of thumbnails which allows
278to navigate through sub-directories and to view items.
229 279
230By default, the content is rendered in the same ordered as listed in `index.json`. The user could later be presented with a menu allowing to sort those items by name, date for example. 280By default, the content is rendered in the same ordered as listed in
281`index.json`. The user could later be presented with a menu allowing to sort
282those items by name, date for example.
231 283
232 284
233### Item view 285### Item view
234 286
235Items other than directories are displayed by this view, making use of most of the screen space to render the element. 287Items other than directories are displayed by this view, making use of most of
288the screen space to render the element.
236 289