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