|
4 | 4 |
|
5 | 5 | Templates |
6 | 6 | ========= |
7 | | -Flask S3Viewer provides CLI to help customize templates. |
8 | 7 |
|
9 | | -Get template source |
10 | | --------------------------------------- |
11 | | -You can customize the template with CLI tool. |
| 8 | +Since v1.0, Flask S3 Viewer ships a single unified UI built with |
| 9 | +**Tailwind CSS + HTMX**, with light/dark mode and inline heroicons. |
| 10 | +The legacy ``base/`` and ``mdl/`` template bundles are removed and the |
| 11 | +``template_namespace`` constructor argument is deprecated — passing it |
| 12 | +emits :class:`DeprecationWarning` and is otherwise ignored. |
| 13 | + |
| 14 | +Use the CLI to scaffold a copy of the bundled templates into your own |
| 15 | +repository, edit them, then point the viewer at the scaffolded |
| 16 | +directory via ``template_folder=``. |
| 17 | + |
| 18 | +Scaffold the templates |
| 19 | +---------------------- |
12 | 20 |
|
13 | 21 | See help. |
14 | 22 |
|
15 | 23 | .. code-block:: bash |
16 | 24 |
|
17 | | - # You can see the details |
18 | 25 | flask_s3_viewer -h |
19 | 26 | =================== Flask S3Viewer Command Line Tool ==================== |
20 | 27 |
|
21 | 28 | optional arguments: |
22 | 29 | -h, --help show this help message and exit |
23 | 30 | -p PATH, --path PATH Enter the directory path where the template will be |
24 | | - located |
25 | | - -t {base,mdl}, --template {base,mdl} |
26 | | - Enter the name of the template to import. (mdl means |
27 | | - material-design-lite and base means not designed |
28 | | - template). |
| 31 | + located. |
| 32 | + --with-static Also copy the bundled static assets (CSS / HTMX / |
| 33 | + core.js) alongside the templates. |
29 | 34 |
|
30 | | -Get the template to your repository. |
| 35 | +Copy just the Jinja templates (most common): |
31 | 36 |
|
32 | 37 | .. code-block:: bash |
33 | 38 |
|
34 | | - # Get a Material-design-lite template |
35 | | - flask_s3_viewer --path templates/mdl --template mdl |
| 39 | + flask_s3_viewer -p ./fsv-templates |
36 | 40 |
|
37 | | - # Get a base template (not designed at all) |
38 | | - flask_s3_viewer -p templates/base -t base |
| 41 | +Or fork the whole UI bundle (templates + ``static/css/app.css`` + HTMX + |
| 42 | +``core.js``) when you need to restyle from scratch: |
39 | 43 |
|
| 44 | +.. code-block:: bash |
40 | 45 |
|
41 | | -When you run the command, you can see the |
42 | | -``{repository}/{path}/{template}`` has been created on your |
43 | | -repository. then rerun the Flask application. |
| 46 | + flask_s3_viewer -p ./fsv-templates --with-static |
44 | 47 |
|
45 | | -And you can also change template directory if you want. |
| 48 | +After scaffolding, the directory contains: |
46 | 49 |
|
47 | | -For examples, Get Material-design-lite template to ``templates/customized`` directory on your root path. |
| 50 | +- ``layout.html`` — page chrome, theme toggle, brand widget, ``extra_head`` block |
| 51 | +- ``files.html`` — full listing page |
| 52 | +- ``_file_list.html`` — HTMX partial swapped on navigation / search / pagination |
| 53 | +- ``_pagination.html`` — pager partial |
| 54 | +- ``_upload_form.html`` — upload UI partial |
| 55 | +- ``error.html`` / ``_error_panel.html`` — error states |
48 | 56 |
|
49 | | -.. code-block:: bash |
| 57 | +Wire the override |
| 58 | +----------------- |
50 | 59 |
|
51 | | - flask_s3_viewer -p templates/customized -t mdl |
| 60 | +Point the viewer at the scaffolded directory: |
52 | 61 |
|
53 | | -Then change template_namespace. it will be routed to defined directory (``templates/customized``). |
| 62 | +.. code-block:: python |
| 63 | + :linenos: |
54 | 64 |
|
55 | | -.. code-block:: bash |
| 65 | + FlaskS3Viewer( |
| 66 | + app, |
| 67 | + namespace='my-bucket', |
| 68 | + template_folder='./fsv-templates', |
| 69 | + config={...}, |
| 70 | + ) |
| 71 | +
|
| 72 | +Behind the scenes the extension prepends a ``FileSystemLoader`` to the |
| 73 | +Flask app's Jinja loader via ``ChoiceLoader``, so any template you |
| 74 | +didn't override still resolves against the bundled defaults and other |
| 75 | +blueprints' templates remain unaffected. |
| 76 | + |
| 77 | +Inject CSS / JS without forking |
| 78 | +------------------------------- |
| 79 | + |
| 80 | +For the common case where you only need to add a stylesheet, script, or |
| 81 | +meta tag, extend ``layout.html`` and use the ``extra_head`` block — no |
| 82 | +``template_folder=`` needed if you place this template on Flask's |
| 83 | +existing search path: |
| 84 | + |
| 85 | +.. code-block:: jinja |
| 86 | +
|
| 87 | + {% extends "flask_s3_viewer/layout.html" %} |
| 88 | + {% block extra_head %} |
| 89 | + <link rel="stylesheet" href="{{ url_for('static', filename='custom.css') }}"> |
| 90 | + {% endblock %} |
| 91 | +
|
| 92 | +Branding without overriding templates |
| 93 | +------------------------------------- |
| 94 | + |
| 95 | +If you only want a custom title and logo, prefer the constructor |
| 96 | +options over a template override: |
| 97 | + |
| 98 | +.. code-block:: python |
| 99 | + :linenos: |
56 | 100 |
|
57 | | - s3viewer = FlaskS3Viewer( |
58 | | - ... |
59 | | - template_namespace='customized', |
60 | | - ... |
61 | | - ) |
| 101 | + FlaskS3Viewer( |
| 102 | + app, |
| 103 | + namespace='my-bucket', |
| 104 | + title='ACME File Vault', |
| 105 | + logo_path='/opt/acme/assets/logo.svg', # local file, auto-inlined as data: URI |
| 106 | + # logo_url='https://cdn.acme.io/logo.svg', # alternatively, any URL |
| 107 | + config={...}, |
| 108 | + ) |
62 | 109 |
|
63 | | -.. warning:: |
64 | | - The template folder of Flask S3Viewer is fixed as ``templates``. so if you change ``template_namespace``, It will be routed **{repository}/templates/{defined template_namespace_by_you}**. |
| 110 | +``logo_path`` reads the file once at construction time and embeds it as |
| 111 | +a ``data:`` URI, so you don't need to expose it via a separate static |
| 112 | +route. ``logo_url`` accepts any browser-resolvable URL. ``logo_path`` |
| 113 | +takes precedence over ``logo_url`` when both are provided. |
0 commit comments