feat: added re-usable Link widget and JSON endpoint

.github/workflows/lint.yml

@@ -14,7 +14,7 @@ jobs:
         with:
           python-version: 3.9
       - name: Install flake8
-        run: pip install --upgrade flake8
+        run: pip install --upgrade flake8 flake8-pyproject
       - name: Run flake8
         uses: liskin/gh-problem-matcher-wrap@v1
         with:

.github/workflows/test.yml

@@ -8,32 +8,45 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.10", "3.11", "3.12"]  # latest release minus two
+        python-version: [ "3.9", "3.10", "3.11", "3.12"]  # latest release minus two
         requirements-file: [
           dj42_cms311.txt,
           dj42_cms41.txt,
           dj50_cms311.txt,
           dj50_cms41.txt,
+          dj51_cms41.txt,
         ]
         os: [
           ubuntu-20.04,
         ]
+        exclude:
+          - requirements-file: dj50_cms311.txt
+            python-version: 3.9
+          - requirements-file: dj50_cms41.txt
+            python-version: 3.9
+          - requirements-file: dj51_cms311.txt
+            python-version: 3.9
+          - requirements-file: dj51_cms41.txt
+            python-version: 3.9
 
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
 
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
+        pip install -U setuptools
         pip install -r tests/requirements/${{ matrix.requirements-file }}
         python setup.py install
 
-    - name: Run coverage
-      run: coverage run setup.py test
+    - name: Run test coverage
+      run: coverage run -m pytest
 
     - name: Upload Coverage to Codecov
-      uses: codecov/codecov-action@v1
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }} # required

.pre-commit-config.yaml

@@ -24,6 +24,7 @@ repos:
     rev: 7.1.0
     hooks:
       - id: flake8
+        additional_dependencies: [Flake8-pyproject]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0

.tx/config

@@ -1,8 +1,11 @@
 [main]
 host = https://www.transifex.com
 
-[djangocms-link.djangocms_link]
-file_filter = djangocms_link/locale/<lang>/LC_MESSAGES/django.po
-source_file = djangocms_link/locale/en/LC_MESSAGES/django.po
-source_lang = en
-type = PO
+[o:divio:p:djangocms-link:r:djangocms_link]
+file_filter            = djangocms_link/locale/<lang>/LC_MESSAGES/django.po
+source_file            = djangocms_link/locale/en/LC_MESSAGES/django.po
+source_lang            = en
+type                   = PO
+replace_edited_strings = false
+keep_translations      = false
+

CHANGELOG.rst

@@ -2,8 +2,20 @@
 Changelog
 =========
 
+5.0.0 (unreleased)
+==================
+
+* Major refactor
+* New re-usable LinkWidget, LinkFormField, and LinkField
+* New re-usable JSON endpoint for internal links
+* New template tags (``get_url`` tag and ``to_url`` filter) to convert link
+  fields into URLs. This allows multiple LinkFields per model
+* Fixed cross-site linking which reduces the number situations of the hostname
+  needing to be part of a link
+* Droped django-select2 dependency in favor of django admin's autocomplete
+
 4.0.0 (2024-07-22)
-================
+==================
 
 * Added support for django CMS 4.1
 * Added support for python 3.10 to 3.12

MANIFEST.in

@@ -2,4 +2,6 @@ include LICENSE
 include README.rst
 recursive-include djangocms_link/locale *
 recursive-include djangocms_link/templates *
+recursive-include djangocms_link/static *
 recursive-exclude * *.py[co]
+recursive-exclude tests *

README.rst

@@ -2,17 +2,15 @@
 django CMS Link
 ===============
 
-|pypi| |build| |coverage|
+|pypi| |coverage| |python| |django| |djangocms| |djangocms4|
 
-**django CMS Link** is a plugin for `django CMS <http://django-cms.org>`_ that
+**django CMS Link** is a plugin for `django CMS <https://django-cms.org>`_ that
 allows you to add links on your site.
 
 This plugin supports child plugins. If you add an other plugin as a
 child it will take this content instead of the link name as the content of the link.
 
-This addon is compatible with `Divio Cloud <http://divio.com>`_ and is also available on the
-`django CMS Marketplace <https://marketplace.django-cms.org/en/addons/browse/djangocms-link/>`_
-for easy installation.
+This addon is compatible with `Divio Cloud <http://divio.com>`_.
 
 .. image:: preview.gif
 
@@ -39,12 +37,13 @@ Documentation
 See ``REQUIREMENTS`` in the `setup.py <https://github.com/divio/djangocms-link/blob/master/setup.py>`_
 file for additional dependencies:
 
-|python| |django| |djangocms|
+django CMS Link has a weak dependency on django Filer. If
+`django Filer <http://django-filer.readthedocs.io/en/latest/installation.html>`_
+is installed and configured appropriately, django CMS Link will allow linking
+files.
 
 * Django Filer 1.7 or higher
-
-Make sure `django Filer <http://django-filer.readthedocs.io/en/latest/installation.html>`_
-is installed and configured appropriately.
+* djangocms-atrributes-field 1.0 or higher
 
 
 Installation
@@ -60,6 +59,9 @@ For a manual install:
 Configuration
 -------------
 
+Link templates
+..............
+
 Note that the provided templates are very minimal by design. You are encouraged
 to adapt and override them to your project's requirements.
 
@@ -73,11 +75,89 @@ setting:
         ('feature', _('Featured Version')),
     ]
 
-You'll need to create the `feature` folder inside ``templates/djangocms_link/``
+You'll need to create the ``feature`` folder inside ``templates/djangocms_link/``
 otherwise you will get a *template does not exist* error. You can do this by
 copying the ``default`` folder inside that directory and renaming it to
 ``feature``.
 
+Link types
+...........
+
+By default, django CMS Link provides three major link types: internal, external,
+and file link (if django-filer is installed).
+
+Phone links or email links can be entered by using the ``tel:`` or ``mailto:``
+scheme, respectively, in the external link field.
+
+By changing the ``DJANGOCMS_LINK_ALLOWED_LINK_TYPES`` setting you can limit
+the type of links accepted. The default is::
+
+    DJANGOCMS_LINK_ALLOWED_LINK_TYPES = [
+        'internal_link',  # Pages and other models
+        'external_link',  # Hand-typed URLs
+        'file_link',      # Files from django-filer
+        'tel',            # Phone numbers as external links using the tel: scheme
+        'mailto',         # Email addresses as external links using the mailto: scheme
+        'anchor',         # Anchors in the current page as external links using #
+    ]
+
+Linkable models
+...............
+
+*Changed in version 5:*
+
+By default, django CMS Link will autodetect which Django or Django CMS models it
+can create internal links to. To make a model appear in the list of internal
+links, you need to
+
+* register a model admin for the model and provide a ``search_fields``
+  attribute. django CMS Link uses the same search logic as the Django admin.
+* provide a ``get_absolute_url()`` method on the model. This method should
+  return the URL of the model instance.
+
+If you do not want to use auto detection, you can provide a list of models
+in the ``DJANGOCMS_LINKABLE_MODELS`` setting using dotted strings::
+
+    DJANGOCMS_LINKABLE_MODELS = [
+        'myapp.mymodel',
+    ]
+
+Attention: ``Page`` objects are always linkable.
+
+django CMS Link will use the model admin's ``get_queryset`` method to retrieve
+the list of objects. If you want to add custom filters, sorting or site
+handling, you can add a ``get_link_queryset`` method to the model admin::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def get_link_queryset(self, request, site_id):
+            """Only used by djangocms-link: returns queryset to select link targets from."""
+            qs = self.get_queryset(request)
+            return qs.filter(is_public=True)
+
+Large search-sets
+..................
+
+If you have a large number of internally linkable models, you can use the
+``DJANGOCMS_LINK_MINIMUM_INPUT_LENGTH`` setting to require a minimum number of
+characters typed before the search is triggered. The higher the number, the
+smaller the average result set size. The default is 0::
+
+    # Require at least 2 characters to be typed before searching for pages
+    DJANGOCMS_LINK_MINIMUM_INPUT_LENGTH = 2
+
+By default django CMS Link will paginate the search results. You can change the
+page size by setting the ``DJANGOCMS_LINK_PAGINATE_BY`` setting.
+The default is 100::
+
+    # Show 5 results per page
+    DJANGOCMS_LINK_PAGINATE_BY = 100
+
+Note, that in the admin paginated search results repeat the modle verbose name.
+
+
+Non-standard hostnames
+......................
+
 To support environments where non-standard URLs would otherwise work, this
 project supports the defining of an additional RegEx pattern for validating the
 host-portion of the URL.
@@ -98,16 +178,59 @@ Either of these might accept a URL such as:
 If left undefined, the normal Django URLValidator will be used.
 
 
-Django Select2
-~~~~~~~~~~~~~~
+Link fields
+-----------
 
-This plugin supports `django-select2 <https://github.com/applegrew/django-select2#installation>`_
-for simpler use of internal links. You need to manually enable it by:
+As of version 5, django CMS Link provides a re-usable link model field,
+form field and form widget. This allows you to use the link field in your own
+models or forms.
 
-* run ``pip install django-select2``
-* add ``django_select2`` to your ``INSTALLED_APPS``
-* add ``url(r'^select2/', include('django_select2.urls')),`` to your ``urls.py``
-* set ``DJANGOCMS_LINK_USE_SELECT2 = True`` in your ``settings.py``
+.. code-block:: python
+
+    from djangocms_link.fields import LinkField, LinkFormField, LinkWidget
+
+    class MyModel(models.Model):
+        link = LinkField()  # or LinkField(blank=True) for optional links
+
+    class MyForm(forms.Form):
+        link = LinkFormField(required=False)
+
+``LinkField`` is a subclass of ``JSONField`` and stores the link data as
+``djangocms_link.helpers.LinkDict``, a direct subclass of ``dict``.
+(An empty link will be ``{}``.)
+
+To render the link field in a template, use the ``LinkDict`` property ``url`` or
+the new template tag ``to_url``. The ``type`` property returns the link type::
+
+    {# Variant 1 #}
+    {% if obj.link %}
+        <a href="{{ obj.link.url }}">Link available</a>
+    {% endif %}
+
+    {# Variant 2 #}
+    {% load djangocms_link_tags %}
+    {% if obj.link %}
+        <a href="{{ obj.link|to_url }}">Link</a>
+    {% endif %}
+
+    {# Variant 3 #}
+    {% with url=obj.link|to_url %}
+    {% if url %}
+        <a href="{{ url }}">Link available</a>
+    {% endif %}
+    {% endwith %}
+
+    {% if obj.link.type == "external_link" %}
+        <a href="{{ obj.link.url }}">External link</a>
+    {% endif %}
+
+
+To turn the ``LinkField``'s ``LinkDict`` dictionary into a URL in python code,
+use the ``url`` property. (It will hit the database when needed. Results are
+cached.)::
+
+    obj = MyModel.objects.first()
+    url = obj.link.url
 
 
 Running Tests
@@ -118,35 +241,45 @@ You can run tests by executing::
     virtualenv env
     source env/bin/activate
     pip install -r tests/requirements.txt
-    python setup.py test
+    pytest
 
 
-.. |pypi| image:: https://badge.fury.io/py/djangocms-link.svg
-    :target: http://badge.fury.io/py/djangocms-link
-.. |build| image:: https://travis-ci.org/divio/djangocms-link.svg?branch=master
-    :target: https://travis-ci.org/divio/djangocms-link
-.. |coverage| image:: https://codecov.io/gh/divio/djangocms-link/branch/master/graph/badge.svg
-    :target: https://codecov.io/gh/divio/djangocms-link
-
-.. |python| image:: https://img.shields.io/badge/python-3.5+-blue.svg
-    :target: https://pypi.org/project/djangocms-link/
-.. |django| image:: https://img.shields.io/badge/django-2.2,%203.0,%203.1-blue.svg
-    :target: https://www.djangoproject.com/
-.. |djangocms| image:: https://img.shields.io/badge/django%20CMS-3.7%2B-blue.svg
-    :target: https://www.django-cms.org/
-
+Upgrading from version 4 or lower
+--------------------------------
 
-Updating from `cmsplugin-filer <https://github.com/django-cms/cmsplugin-filer>`_
---------------------------------------------------------------------------------
+django CMS Link 5 is a rewrite of the plugin. If you are updating from
+version 4 or lower, you will notice
 
-Historically, `cmsplugin-filer` was used to create file, folder, image, link, teaser & video plugins on your django CMS projects. Now `cmsplugin-filer` has been archived, you can still migrate your old instances without having to copy them manually to the new `djangocms-<file|picture|link|...>` plugins.
+* the **new re-usable link widget**, greatly simplifying the user interface
+* an **improved management of multi-site situations**, essentially avoiding the
+  unnecessary additon of the host name to the URL in plugin instances that
+  are not in a page placeholder (such as links on aliases or static placeholder)
+* a **re-usable admin endpoint** for querying available links which can be used
+  by other apps such as djangocms-text.
+* Links are generated by template tags or template filters instead of the
+  model's ``get_link()`` method. This allows multiple links in future models. The
+  ``get_link()`` method on the plugin's model is still available for backwards
+  compatibility.
 
-There's a third-party management command that supports your migration:
+Migrations should automatically existing plugin instances to the new model
+fields.
 
-`migrate_cmsplugin_filer.py <https://gist.github.com/corentinbettiol/84a6ea7e4d047fc01861b0af15fd60f0>`_
+**WARNING:** We strongly recommend to backup your database before updating to
+version 5. The migration is tested but they do remove unused fields from
+the database. If you encounter any issues, please report them on
+`GitHub <https://github.com/django-cms/djangocms-link/issues>`_.
 
-This management command is only a starting point. It *has* worked out of the box for some people, but we encourage you to read the code, understand what it does, and test it on a development environment before running it on your production server.
+.. |pypi| image:: https://badge.fury.io/py/djangocms-link.svg
+    :target: http://badge.fury.io/py/djangocms-link
+.. |coverage| image:: https://codecov.io/gh/django-cms/djangocms-link/branch/master/graph/badge.svg
+    :target: https://codecov.io/gh/django-cms/djangocms-link
 
-The management command is only configured to transfer your `cmsplugin_link`, `cmsplugin_file`, `cmsplugin_folder` and `cmsplugin_image` plugins to modern `djangocms_*` plugins. If you need to transfer other `cmsplugin_*` plugins, you'll have to write your own code.
+.. |python| image:: https://img.shields.io/badge/python-3.10+-blue.svg
+    :target: https://pypi.org/project/djangocms-link/
+.. |django| image:: https://img.shields.io/badge/django-4.2,%205.0,%205.1-blue.svg
+    :target: https://www.djangoproject.com/
+.. |djangocms| image:: https://img.shields.io/badge/django%20CMS-3.11%2B-blue.svg
+    :target: https://www.django-cms.org/
+.. |djangocms4| image:: https://img.shields.io/badge/django%20CMS-4-blue.svg
+    :target: https://www.django-cms.org/
 
-Alternatively you can use the `deprecate_cmsplugin_filer <https://github.com/ImaginaryLandscape/deprecate_cmsplugin_filer>`_ app, which only adds a small migration that transfer the old `cmsplugin-filer` plugins instances to the new `djangocms-<file|picture|link|...>` plugins.