Repository files navigation

django CMS Link is a plugin fordjango CMS thatallows you to add links on your site.

This plugin supports child plugins. If you add an other plugin as achild it will take this content instead of the link name as the content of the link.

This addon is compatible withDivio Cloud.

This is a an open-source project. We'll be delighted to receive yourfeedback in the form of issues and pull requests. Before submitting yourpull request, please review ourcontribution guidelines.

We're grateful to all contributors who have helped create and maintain this package.Contributors are listed at thecontributorssection.

One of the easiest contributions you can make is helping to translate this addon onTransifex.

SeeREQUIREMENTS in thesetup.pyfile for additional dependencies:

django CMS Link has a weak dependency on django Filer. Ifdjango Fileris installed and configured appropriately, django CMS Link will allow linkingfiles.

• Django Filer 1.7 or higher
• djangocms-atrributes-field 1.0 or higher

For a manual install:

• runpip install djangocms-link
• adddjangocms_link to yourINSTALLED_APPS
• runpython manage.py migrate djangocms_link

Note that the provided templates are very minimal by design. You are encouragedto adapt and override them to your project's requirements.

This addon provides adefault template for all instances. You can provideadditional template choices by adding aDJANGOCMS_LINK_TEMPLATESsetting:

DJANGOCMS_LINK_TEMPLATES= [    ('feature',_('Featured Version')),]

You'll need to create thefeature folder insidetemplates/djangocms_link/otherwise you will get atemplate does not exist error. You can do this bycopying thedefault folder inside that directory and renaming it tofeature.

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 thetel: ormailto:scheme, respectively, in the external link field.

By changing theDJANGOCMS_LINK_ALLOWED_LINK_TYPES setting you can limitthe 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 #]

Added in version 5:

By default, django CMS Link will autodetect which Django or Django CMS models itcan create internal links to. To make a model appear in the list of internallinks, you need to

• register a model admin for the model and provide asearch_fieldsattribute. django CMS Link uses the same search logic as the Django admin.
• provide aget_absolute_url() method on the model. This method shouldreturn the URL of the model instance.

If you do not want to use auto detection, you can provide a list of modelsin theDJANGOCMS_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'sget_queryset method to retrievethe list of objects. If you want to add custom filters, sorting or sitehandling, you can add aget_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)

If you have a large number of internally linkable models, you can use theDJANGOCMS_LINK_MINIMUM_INPUT_LENGTH setting to require a minimum number ofcharacters typed before the search is triggered. The higher the number, thesmaller the average result set size. The default is 0:

# Require at least 2 characters to be typed before searching for pagesDJANGOCMS_LINK_MINIMUM_INPUT_LENGTH = 2

By default django CMS Link will paginate the search results. You can change thepage size by setting theDJANGOCMS_LINK_PAGINATE_BY setting.The default is 50:

# Show 100 results per "page"DJANGOCMS_LINK_PAGINATE_BY = 100

Note, that in the admin paginated search results repeat the model's verbose name.

For multi-site installations, django CMS Link provides a site selector. It can beswitched on or off by setting theDJANGOCMS_LINK_SITE_SELECTOR setting toTrue orFalse. The default isTrue:

# Enable the site selectorDJANGOCMS_LINK_SITE_SELECTOR = True

To support environments where non-standard URLs would otherwise work, thisproject supports the defining of an additional RegEx pattern for validating thehost-portion of the URL.

For example:

# RFC1123 Pattern:DJANGOCMS_LINK_INTRANET_HOSTNAME_PATTERN=r'[a-z,0-9,-]{1,15}'

Either of these might accept a URL such as:

http://SEARCHHOST/?q=some+search+string

If left undefined, the normal Django URLValidator will be used.

Added in version 5:

django CMS Link provides a re-usable link model field, form field and formwidget. This allows you to use the link field in your own models or admin forms.

fromdjangocms_link.fieldsimportLinkField,LinkFormField,LinkWidgetclassMyModel(models.Model):link=LinkField()# or LinkField(blank=True) for optional linksclassMyForm(forms.Form):link=LinkFormField(required=False)

LinkField is a subclass ofJSONField and stores the link data asdjangocms_link.helpers.LinkDict, a direct subclass ofdict.(An empty link will be{}.)

To render the link field in a template, convert theLinkDict to string,use theLinkDict propertyurl or the new template tagto_url.Thetype property returns the link type:

{# Variant 1 #}{% if obj.link %}    <a href="{{ obj.link }}">Link available</a>  {# str(obj.link) gives the URL #}{% endif %}{# Variant 2 #}{% if obj.link %}    <a href="{{ obj.link.url }}">Link</a>  {# explicitly get the URL #}{% endif %}{% if obj.link.type == "external_link" %}  {# evaluate link type #}    <a href="{{ obj.link.url }}">External link</a>{% endif %}

To turn theLinkField'sLinkDict dictionary into a URL in python code,use theurl property. (It will hit the database if needed. Results arecached.):

obj = MyModel.objects.first()url = obj.link.url

Theto_url template filter and theget_obj_link helper function can be used toget the full url for any Django model instance. This is useful on multi-site installations.to_url assumes that the model instance's site is found in itssite property. If themodel belongs to a different site than the current, it prepends the domain name of that site.

Example:

{% load djangocms_link_tags %}{% if obj %}    <a href="{{ obj|to_url }}">Link to object</a>  {# will include the site domain if needed #}{% endif %}

You can run tests by executing:

virtualenv envsource env/bin/activatepip install -r tests/requirements.txtpytest

django CMS Link 5 is a rewrite of the plugin. If you are updating fromversion 4 or lower, you will notice

• thenew re-usable link widget, greatly simplifying the user interface
• animproved management of multi-site situations, essentially avoiding theunnecessary additon of the host name to the URL in plugin instances thatare not in a page placeholder (such as links on aliases or static placeholder)
• are-usable admin endpoint for querying available links which can be usedby other apps such as djangocms-text.
• Links are generated by template tags or template filters instead of themodel'sget_link() method. This allows multiple links in future models. Theget_link() method on the plugin's model is still available for backwardscompatibility.

Migrations should automatically existing plugin instances to the new modelfields.

WARNING: We strongly recommend to backup your database before updating toversion 5. The migration is tested but they do remove unused fields fromthe database. If you encounter any issues, please report them onGitHub.