The GalleryWidget class

class galleryfield.widgets.GalleryWidget(upload_url=None, fetch_url=None, multiple=True, thumbnail_size='120x120', template='galleryfield/widget.html', attrs=None, options=None, jquery_file_upload_ui_options=None, disable_fetch=False, disable_server_side_crop=False, **kwargs)[source]

This is the default widget used by galleryfield.fields.GalleryFormField.

  • upload_url (str, optional) –

    An URL name or an URL of the upload handler view used by the widget instance, defaults to None. When not set, this param will be auto-configured if the parent galleryfield.fields.GalleryFormField is used by a galleryfield.fields.GalleryField, and the value will follow the naming rule. The value can also be None if set explicitly by:

    self.fields["images"].widget.upload_url = None

    In this case, upload ui won’t show upload buttons.

  • fetch_url (str, optional) – An URL name or an URL for fetching the existing images in the gallery instance, defaults to None. When not set, this param will be auto-configured if the parent galleryfield.fields.GalleryFormField is used by a galleryfield.fields.GalleryField, the value wil. follow the naming rule.

  • multiple (bool, optional) – Whether allow to select multiple image files in the file picker. Defaults to True.

  • thumbnail_size (int, optional) – The thumbnail size (both width and height), defaults to defaults.DEFAULT_THUMBNAIL_SIZE, which can be overridden by settings.DJANGO_GALLERY_FIELD_CONFIG["thumbnails"]["size"]. The value can be set after the widget is initialized.

  • template (str, optional) – The path of template which is used to render the widget. defaults to galleryfield/widget.html, which support template inheritance.

  • attrs (dict, optional) – Html attribute when rendering the field (Which is a django.forms.HiddenInput), defaults to None. See Django docs.

  • options (dict, optional) –

    Other options when rendering the widget. Implemented options:

    • accepted_mime_types (list, optional) - A list of MIME types used to filter files when picking files with file picker, defaults to ['image/*']

  • jquery_file_upload_ui_options (dict, optional) – The default template is using blueimp/jQuery-File-Upload package to render the ui and dealing with AJAX upload. See jquery_file_upload_ui_options for more information.

  • disable_fetch (bool, optional) – Whether disable fetching existing images of the form instance (if any), defaults to False. If True, the validity of fetch_url will not be checked.

  • disable_server_side_crop (bool, optional) – Whether disable server side cropping of uploaded images, defaults to False.


When a galleryfield.fields.GalleryField instance is initialized with galleryfield.BuiltInGalleryImage, the widget instance will automatically use URL names galleryfield-builtingalleryimage-upload galleryfield-builtingalleryimage-fetch for upload_url, fetch_url, respectively.

The URL params can be assigned after the formfield is initialized. For example:

 from my_app.models import MyGallery

 class MyGalleryForm(forms.ModelForm):
     class Meta:
         model = MyGallery
         fields = ["album"]

     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.fields["album"].widget.upload_url = "/path/to/my-upload-handler"

The validity of the URL params will be checked before rendering.


You NEED to make sure all the urls in the widget are handling the corresponding target_model before put into production. As a minimal precaution, when a galleryfield.fields.GalleryField instance ( or a galleryfield.fields.GalleryFormField instance, or image handling views ) is NOT initialized with galleryfield.BuiltInGalleryImage as the target_model, assigning built-in URL names ( i.e., galleryfield-builtingalleryimage-upload, galleryfield-builtingalleryimage-fetch) in widget params, or set galleryfield-builtingalleryimage-crop for crop_url_name in image handling views, ImproperlyConfigured will be raised when rendering. The reason is, those built-in views are handling built-in galleryfield.models.BuiltInGalleryImage instances.