Initial commit

f

Co-Authored-By: Andy Babic <andy.babic@torchbox.com>

.gitignore

@@ -0,0 +1,82 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+*.sqlite3
+*.sqlite3-journal
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+poetry.lock
+.ruff_cache
+
+tests/test-media
+tests/test-static

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Torchbox
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,210 @@
+# Bynder integration for Wagtail
+
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![PyPI version](https://img.shields.io/pypi/v/wagtail-bynder.svg?style=flat)](https://pypi.org/project/wagtail-bynder)
+
+## Links
+
+- [Documentation](https://github.com/torchbox/wagtail-bynder/blob/main/README.md)
+- [Changelog](https://github.com/torchbox/wagtail-bynder/blob/main/CHANGELOG.md)
+- [Contributing](https://github.com/torchbox/wagtail-bynder/blob/main/CONTRIBUTING.md)
+- [Discussions](https://github.com/torchbox/wagtail-bynder/discussions)
+- [Security](https://github.com/torchbox/wagtail-bynder/security)
+
+[Bynder](https://www.bynder.com) is a Digital Asset Management System (DAMS) and platform that allows organisations 
+to manage their digital assets, which includes the images and documents used in Wagtail content.
+
+The data flow is one way: Bynder assets are always treated as the source of truth, and Wagtail uses read-only API access 
+to create copies of assets and keep them up-to-date.
+
+## How it works
+
+The main points of integration are Wagtail's image and document chooser views, which are patched by this app to show an 
+asset selection UI for Bynder instead of a list of Wagtail images or documents.
+
+When an asset is selected, Wagtail silently downloads the file and related metadata, and saves it as an `Image` or 
+`Document` object, allowing it to be used in a typical way. The ID of the selected asset (as well as a few other bits of data) 
+are saved on the object when this happens, helping Wagtail to recognise when it already has a copy of an asset, 
+and to help keep them up-to-date with changes made in Bynder.
+
+Currently, changes are synced from Bynder back to Wagtail via a couple of well optimised management commands, 
+intended to be run regularly (via a cron job):
+
+- `python manage.py update_stale_images`
+- `python manage.py update_stale_documents`
+
+## Installation
+
+In your project's Django settings, add the app your `INSTALLED_APPS` list (at the end is fine):
+
+```python
+INSTALLED_APPS = [
+  # ...
+  "wagtail_bynder",
+]
+```
+
+Then add the following to the `MIDDLEWARE` list (at the end is fine):
+
+```python
+MIDDLEWARE = [
+  #...
+  "wagtail_bynder.middleware.PatchWagtailURLsMiddleware",
+]
+```
+
+Import the abstract `BynderSyncedImage` model and have your project's custom image model definition subclass it instead 
+of `wagtail.images.models.AbstractImage`. For example
+
+```python
+# yourproject/images/models.py
+from wagtail_bynder.models import BynderSyncedImage
+
+
+class CustomImage(BynderSyncedImage):
+    pass
+```
+
+Import the abstract `BynderSyncedDocument` model and have your project's custom document model definition subclass it instead of 
+`wagtail.documents.models.AbstractDocument`. For example:
+
+```python
+# yourproject/documents/models.py
+from wagtail_bynder.models import BynderSyncedDocument
+
+
+class CustomDocument(BynderSyncedDocument):
+    pass
+```
+
+Finally, run Django's m`akemigrations` and `migrate` commands to apply any model field changes to your project
+
+```shell
+$ python manage.py makemigrations
+$ python manage.py migrate
+```
+
+### Optional: To use videos from Bynder
+
+To use videos from Bynder in content across the site, this app includes a specialised model to help store relevant data for videos, 
+plus blocks and chooser widgets to help use them in your project. However, because not all projects use video, 
+and project-specific requirements around video usage can be a little more custom, 
+the model is `abstract` - you need to subclass it in order to use the functionality.
+
+First, import the abstract `BynderSyncedVideo` model and subclass it within your project to create a concrete model. 
+For example:
+
+```python
+# yourproject/videos/models.py
+from wagtail_bynder.models import BynderSyncedVideo
+
+
+class Video(BynderSyncedVideo):
+    pass
+```
+
+Next, in your project's Django settings, add a `BYNDER_VIDEO_MODEL` item to establish your custom model as the 'official' 
+video model. The value should be a string in the format `"app_label.Model"`. For example:
+
+```python
+BYNDER_VIDEO_MODEL = "videos.Video"
+```
+
+Finally, run Django's `makemigrations` and `migrate` commands to create and apply the model changes in your project.
+
+```shell
+$ python manage.py makemigrations
+$ python manage.py migrate
+```
+
+## Configuration
+
+You can use the following settings to configure the integration:
+
+### `BYNDER_DOMAIN`
+
+Example: `"your-org.bynder.com"`
+
+Default: `None`
+
+The Bynder instance you want the environment to use.
+
+### `BYNDER_API_TOKEN`
+
+Example: `"60ae04f68460cfed1b289c4c1db4c9b273b238dx2030c51298dcad245b5ff1f8"`
+
+Default: `None`
+
+An API token for the back end to use when talking to the Bynder API.
+NOTE: This could be more permissive than `BYNDER_COMPACTVIEW_API_TOKEN`, so should be kept separate to avoid surfacing to Wagtail users.
+
+### `BYNDER_COMPACTVIEW_API_TOKEN`
+
+Example: `"64ae04f71460cfed1b289c4c1db4c9b273b238dx2030c51298dcad245b5ff1f8"`
+
+Default: `None`
+
+An API token for Bynder's JavaScript 'compact view' to use. The value is injected into the `admin_base.html` template for Wagtail 
+for the JavaScript to pick up, exposing it to Wagtail users. Because of this, it should be different to `BYNDER_API_TOKEN` 
+and only needs to have basic read permissions.
+
+### `BYNDER_IMAGE_SOURCE_THUMBNAIL_NAME`
+
+Example: `"WagtailSource"`
+
+Default: `"webimage"`
+
+The name of the automatically generated derivative that should be downloaded and used as the `file` value for the 
+representative Wagtail image (as it appears in `thumbnails` in the API representation).
+
+WARNING: It's important to get this right, because if the specified derivative is NOT present in the response for an 
+image for any reason, the ORIGINAL will be downloaded - which will lead to slow chooser response times and higher memory 
+usage when generating renditions.
+
+### `BYNDER_VIDEO_MODEL`
+
+Example: `"video.Video"`
+
+Default: `None`
+
+### `BYNDER_VIDEO_PRIMARY_DERIVATIVE_NAME`
+
+Default: `"Web-Primary"`
+
+### `BYNDER_VIDEO_FALLBACK_DERIVATIVE_NAME`
+
+Default: `"Web-Fallback"`
+
+### `BYNDER_VIDEO_POSTER_IMAGE_DERIVATIVE_NAME`
+
+Default: `"webimage"`
+
+### `BYNDER_SYNC_EXISTING_IMAGES_ON_CHOOSE`
+
+Example: `True`
+
+Default: `False`
+
+When `True`, local copies of images will be refreshed from the Bynder API representation whenever they are selected in 
+the chooser interface. This slows down the chooser experience slightly, but can be useful for seeing up-to-date data in 
+environments that might not be using the management commands or other means to keep images up-to-date with their Bynder counterparts.
+
+### `BYNDER_SYNC_EXISTING_DOCUMENTS_ON_CHOOSE`
+
+Example: `True`
+
+Default: `False`
+
+As `BYNDER_SYNC_EXISTING_IMAGES_ON_CHOOSE`, but for documents.
+
+### `BYNDER_DISABLE_WAGTAIL_EDITING_FOR_ASSETS`
+
+Example: `True`
+
+Default: `False`
+
+When `True`, hitting Wagtail's built-in edit view for an image or document will result in a redirect to the asset 
+detail view in the Bynder interface.
+
+The default is value is `False`, because it can be useful to use the Wagtail representation to check that file, metadata 
+and focal points are being accurately reflected.

pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "wagtail-bynder"
+description = "Wagtail integration with Bynder, a Digital Asset Management System"
+authors = [{name = "Andy Babic ", email = "andy.babic@torchbox.com"}]
+maintainers = [
+    {name = "Andy Babic ", email = "andy.babic@torchbox.com"},
+    {name = "Dan Braghis", email="dan.braghis@torchbox.com"}
+]
+readme = "README.md"
+license = {file = "LICENSE"}
+keywords = ["Wagtail", "Django", "Bynder", "DAMS", "digital asset management"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: Django",
+    "Framework :: Django :: 3.2",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Wagtail",
+    "Framework :: Wagtail :: 4",
+    "Framework :: Wagtail :: 5",
+]
+
+dynamic = ["version"]
+requires-python = ">=3.8"
+dependencies = [
+    "Django>=3.2",
+    "Wagtail>=4.1",
+    "bynder-sdk>=1.1.5,<2.0"
+]
+
+[project.optional-dependencies]
+testing = [
+    "dj-database-url>=2.1.0,<3.0",
+    "wagtail_factories>=4.1.0,<5.0",
+    "responses>=0.24,<1",
+    "coverage>=7.0,<8.0",
+]
+
+[project.urls]
+Source = "https://github.com/torchbox/wagtail-bynder"
+Changelog = "https://github.com/torchbox/wagtail-bynder/blob/main/CHANGELOG.md"
+
+
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "wagtail_bynder"
+
+[tool.flit.sdist]
+exclude = [
+    ".*",
+    "*.db",
+    "*.json",
+    "*.ini",
+    "*.yaml",
+    "tests",
+    "CHANGELOG.md",
+    "testmanage.py",
+]