1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
---
pagetitle: Viewer user manual - ldgallery
title: LDGALLERY-VIEWER(7) ldgallery
author: Pacien TRAN-GIRARD, Guillaume FOUET
date: 2020-09-24 (v2.0)
---
# NAME
ldgallery viewer - a static web gallery viewer with tags
# DESCRIPTION
The ldgallery viewer is a web application that allows users to browse, search through and view items in galleries generated by the ldgallery(1) compiler.
The web application runs in a JavaScript-enabled web browser and does not require any special software on the server's side.
Its responsiveness allows it to be used from either a desktop browser or some mobile device.
# USER INTERFACE
The viewer's user interface is split into a main item view and a side search panel, which can be opened by using the appropriate button in the toolbar at the top-left corner.
The main view displays the gallery's directories and items as a thumbnail grid.
The order in which items are displayed can be chosen from the sort menu at the top-left corner.
The side panel allows the user to interactively enter filtering queries to search through the gallery's content.
This panel features a list of relevant tags, grouped by categories, that can be used to build the search query.
The information panel at the bottom of the sidebar displays various metadata about the currently viewed item.
Those include the title, date and description of the file or directory.
Items of the following formats can be opened and visualised within the web application:
* Pictures (Bitmap, JPEG, PNG, TIFF, HDR, GIF)
* Videos (OGV, WebM, Matroska, MPEG-4)
* Audio files (WAV, Opus, FLAC, MP3, MPEG-4)
* Plain text files (`.txt`)
* PDFs
Formats which are not listed above or which are not supported by the user's web browser are offered for download instead of being directly displayed in the same window.
# SEARCH QUERIES
Items can be filtered based on their tags.
Adding tags to the search query restricts the search results to items having those tags.
Tags which belong to multiple categories may be disambiguated by adding their category as a prefix, separated by a colon (":").
The following modifiers can be used in queries as prefixes of tags:
`+`
: Include all items having the associated tag, independently of simple tag restrictions.
`-`
: Exclude all items having the associated tag, independently of simple tag restrictions and inclusions.
Auto-completion suggestions are shown as filters are being typed in the query field.
In the case of disambiguated tags, both the category and the tag components are allowed to be partially entered, allowing "loc:fra" to expand into "location:france" for example.
# VIEWER CONFIGURATION
The viewer itself can be configured through a JSON file named __config.json__ and placed in the web viewer's directory.
Viewer configuration options are:
galleryRoot
: Absolute or relative path to the root of the gallery to display.
galleryIndex
: Optional index file to use under the value specified for "galleryRoot".
Defaults to "index.json".
initialItemSort
: Order in which gallery items are originally to be displayed.
Possible values are "title_asc", "date_asc", "date_desc".
Defaults to "date_asc".
Titles are sorted using a human-friendly _natural sort order_ which treats multi-digit numbers atomically.
The item path is used as a tie-breaker for all the defined orders.
<!-- https://github.com/pacien/ldgallery/issues/27
initialSearchQuery
: Optional initial search query to set when opening the gallery.
-->
initialTagDisplayLimit
: Limit on the number of tags to suggest in each tag category.
Causes only the specified amount of most used tags to be displayed until the user expands the list.
Set to -1 to disable the limit on suggestions.
Defaults to 10.
splashScreen
: Displays an information notice before opening the gallery (see below).
An alternative viewer configuration file located in the viewer's directory can be loaded by specifying its name,
without the ".json" extension, as a query parameter given before the page anchor;
for example, some alternative configuration named "config_2.json" can be loaded with "http://gallery/?config_2#".
# SPLASH SCREEN CONFIGURATION
splashScreen.resource
: Absolute or relative path to the information notice. The user is prompted to explicitly acknowledge such notice before being allowed to browse the gallery.
Rich text formatting is possible through the use of the [GitHub Flavoured Markdown syntax][GFM].
Inline HTML and CSS are also supported.
[GFM]: https://github.github.com/gfm/
splashScreen.acknowledgmentKey
: Optional key; when set to an arbitrary string, the information notice will appear only the first time it is proposed to the user. Once the notice acknowledged, the key is saved to the device's local storage. To display the notice again, change this key to another value.
When left empty, the notice will appear every time.
splashScreen.buttonAcknowledgeLabel
: Optional label for the acknowledge button shown below the notice.
*Defaults to "Acknowledge"*
splashScreen.style
: Optional CSS attributes for the information notice's container.
String or JSON formats are supported.
# CONFIGURATION EXAMPLE
Viewer __config.json__:
```json
{
"galleryRoot": "./gallery/",
"galleryIndex": "index.json",
"initialItemSort": "date_desc",
"initialTagDisplayLimit": 10,
"splashScreen": {
"resource": "./splashscreen.md",
"acknowledgmentKey": "v001",
"buttonAcknowledgeLabel": "I agree",
"style": {
"max-width": "45em",
"font-size": "20px",
"padding-top": "20vh"
}
}
}
```
# PROGRESSIVE WEB APPLICATION
This web application can be "installed" on some user's mobile device as a progressive web application, i.e. a shortcut giving the web page the appearance of a native application.
This feature can be enabled by adding a PWA manifest in the viewer's directory when deployed.
An example of such manifest and an associated icon are available in the example folder packaged with the viewer.
# SEE ALSO
Related manual pages: __ldgallery__(1), __ldgallery-quickstart__(7).
The ldgallery source code is available on <https://ldgallery.pacien.org>.
# LICENSE
Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU Affero General Public License for more details <https://www.gnu.org/licenses/agpl-3.0.html>.
|