From 2a330d67168a4b2b1491f1ab2335106c2e2be2d2 Mon Sep 17 00:00:00 2001 From: Eduardo Oliveira Date: Thu, 31 Mar 2022 22:05:07 -0300 Subject: [PATCH] add versioned documentation --- .../customization/_category_.json | 5 + .../version-0.1.5/customization/colors.md | 23 ++ .../inline_admin/_category_.json | 5 + .../version-0.1.5/inline_admin/tutorial.md | 160 ++++++++++ docs/versioned_docs/version-0.1.5/intro.md | 69 +++++ .../version-0.1.5/widget/_category_.json | 5 + .../version-0.1.5/widget/resumed.md | 48 +++ .../version-0.1.5/widget/tutorial.md | 278 ++++++++++++++++++ .../version-0.1.5-sidebars.json | 8 + docs/versions.json | 1 + 10 files changed, 602 insertions(+) create mode 100644 docs/versioned_docs/version-0.1.5/customization/_category_.json create mode 100644 docs/versioned_docs/version-0.1.5/customization/colors.md create mode 100644 docs/versioned_docs/version-0.1.5/inline_admin/_category_.json create mode 100644 docs/versioned_docs/version-0.1.5/inline_admin/tutorial.md create mode 100644 docs/versioned_docs/version-0.1.5/intro.md create mode 100644 docs/versioned_docs/version-0.1.5/widget/_category_.json create mode 100644 docs/versioned_docs/version-0.1.5/widget/resumed.md create mode 100644 docs/versioned_docs/version-0.1.5/widget/tutorial.md create mode 100644 docs/versioned_sidebars/version-0.1.5-sidebars.json diff --git a/docs/versioned_docs/version-0.1.5/customization/_category_.json b/docs/versioned_docs/version-0.1.5/customization/_category_.json new file mode 100644 index 00000000..6c375f90 --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/customization/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Customization", + "position": 4 + } + \ No newline at end of file diff --git a/docs/versioned_docs/version-0.1.5/customization/colors.md b/docs/versioned_docs/version-0.1.5/customization/colors.md new file mode 100644 index 00000000..3b199b86 --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/customization/colors.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 1 +--- + +# Colors + +To customize the image uploader widget colors you can use your own css file to override the css variables defined by the `image-uploader-inline.css`, `image-uploader-inline.min.css`, `image-uploader-widget.css` and `image-uploader-widget.min.css`. See an example, taken from another personal private project: + +```scss +body { + --iuw-background: #{$dashdark} !important; + --iuw-border-color: #{$dashborder} !important; + --iuw-color: #{$dashgray} !important; + --iuw-placeholder-text-color: #{$dashgray} !important; + --iuw-dropzone-background: #{$dashlight} !important; + --iuw-image-preview-border: #{$dashborder} !important; + --iuw-image-preview-shadow: rgba(0, 0, 0, 0.3); + --iuw-add-image-background: #{$dashlight} !important; + --iuw-add-image-color: #{$dashgray} !important; +} +``` + +**Observation**: To see better the variables name, check the scss file at the GitHub repository: [here](https://github.com/inventare/django-image-uploader-widget/blob/main/src/styles/_variables.scss). diff --git a/docs/versioned_docs/version-0.1.5/inline_admin/_category_.json b/docs/versioned_docs/version-0.1.5/inline_admin/_category_.json new file mode 100644 index 00000000..a0fdd5f3 --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/inline_admin/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Inline Admin", + "position": 3 + } + \ No newline at end of file diff --git a/docs/versioned_docs/version-0.1.5/inline_admin/tutorial.md b/docs/versioned_docs/version-0.1.5/inline_admin/tutorial.md new file mode 100644 index 00000000..6f17db91 --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/inline_admin/tutorial.md @@ -0,0 +1,160 @@ +--- +sidebar_position: 1 +--- + +# Tutorial + +First, we need of some context: the image uploader inline is an inline admin editor (like the [StackedInline](https://docs.djangoproject.com/en/4.0/ref/contrib/admin/#django.contrib.admin.StackedInline) or the [TabularInline](https://docs.djangoproject.com/en/4.0/ref/contrib/admin/#django.contrib.admin.TabularInline) of the original django). This inline editor is created to make an multiple images manager widget using an model with an image field. + +## Creating a django project + +First, create a project folder. Here we call it as `my-ecommerce`: + +```bash +mkdir my-ecommerce +cd my-ecommerce +``` + +And, now, create a django project in this folder: + +```bash +django-admin startproject core . +``` + +And, then, we have the folder structure: + +``` +| - my-ecommerce + | - core + | - asgi.py + | - __init__.py + | - settings.py + | - urls.py + | - wsgi.py + | - manage.py +``` + +Create our **django** application by running the command: + +``` +python manage.py startapp ecommerce +``` + +And, now, we have a new, and more complex, folder structure: + +``` +| - my-ecommerce + | - core + | - asgi.py + | - __init__.py + | - settings.py + | - urls.py + | - wsgi.py + | - ecommerce + | - migrations + | - __init__.py + | - admin.py + | - apps.py + | - __init__.py + | - models.py + | - tests.py + | - views.py + | - manage.py +``` + +## Installing the widget + +To install the widget, is possible to use the same instructions of the [Introduction](../intro.md), and the first step is to install the package with pip: + +```bash +pip install django-image-uploader-widget +``` + +then, add it to the `INSTALLED_APPS` on the `settings.py`, in the case of this example: `core/settings.py` file. To understand better the Applications, see the django documentation: [Applications](https://docs.djangoproject.com/en/3.2/ref/applications/). + +```python +# core/settings.py +# ... + +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + 'django.contrib.contenttypes', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.staticfiles', + 'image_uploader_widget', +] + +# ... +``` + +### Warning + +**Observation**: note that the application name to be added on the `INSTALLED_APPS` are not equals to the pip package name / install name. + +## Using the inline editor + +This inline editor is created to be used directly with the django-admin interface. To show how to use it, go to create two basic models inside the `ecommerce` app (Add your app, `ecommerce` in my case, at `INSTALLED_APPS` is recommended): + +```python +# ecommerce/models.py +from django.db import models + +class Product(models.Model): + name = models.CharField(max_length=100) + + def __str__(self): + return self.name + + class Meta: + verbose_name = 'Product' + verbose_name_plural = 'Products' + +class ProductImage(models.Model): + product = models.ForeignKey( + Product, + related_name="images", + on_delete=models.CASCADE + ) + image = models.ImageField("image") + + def __str__(self): + return str(self.image) + + class Meta: + verbose_name = 'Product Image' + verbose_name_plural = 'Product Images' +``` + +Now, inside our admin, we can create an primary ModelAdmin for the product: + +```python +# ecommerce/admin.py +from django.contrib import admin +from ecommerce.models import Product, ProductImage + +@admin.register(Product) +class ProductAdmin(admin.ModelAdmin): + pass +``` + +And, now, we can define our inline widget: + +```python +# ecommerce/admin.py +from django.contrib import admin +from ecommerce.models import Product, ProductImage +from image_uploader_widget.admin import ImageUploaderInline + +class ProductImageAdmin(ImageUploaderInline): + model = ProductImage + +@admin.register(Product) +class ProductAdmin(admin.ModelAdmin): + inlines = [ProductImageAdmin] +``` + +And we got the inline editor working as well: + +![Image Uploader Widget](/img/tutorials/admin_demo.png) diff --git a/docs/versioned_docs/version-0.1.5/intro.md b/docs/versioned_docs/version-0.1.5/intro.md new file mode 100644 index 00000000..a53953d4 --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/intro.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 1 +--- + +# Introduction + +The **django-image-uploader-widget** is a widget to **django**, specially **django-admin** to handle better image uploads with a modern and beautiful user interface. + +## Features + +Some of the features of this widget is: + +- Beautiful user interface. +- Handle drop files from your file manager. +- Handle select file by click in the widget or by droping the image (previous item). +- Inline editor provided to work with multiple images. +- Modal to view the full image (The images are adjusted as cover in the preview box, then, in some cases, that is very useful). + +![Drag and Drop Image](/img/beautiful.gif) + +![Select by click](/img/click.gif) + +![Inline handle](/img/inline_multiple.gif) + +## Getting Started + +To get started, install this plugin with the pip package manager: + +```sh +pip install django-image-uploader-widget +``` + +then, go to the `settings.py` file and add the `image_uploader_widget` to the installed apps: + +```python +INSTALLED_APPS = [ + 'my_app.apps.MyAppConfig', + 'django.contrib.admin', + 'django.contrib.auth', + 'django.contrib.contenttypes', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.staticfiles', + 'django.forms', + 'image_uploader_widget', +] +``` + +## Using + +Now, you must be able to use the widget in your forms: + +```python +# forms.py +from django import forms +from image_uploader_widget.widgets import ImageUploaderWidget + +class ExampleForm(forms.ModelForm): + class Meta: + widgets = { + 'image': ImageUploaderWidget(), + } + fields = '__all__' +``` + +## Code Example + +For code direct examples, check the `image_uploader_widget_demo` folder in the Github [repository](https://github.com/inventare/django-image-uploader-widget). + diff --git a/docs/versioned_docs/version-0.1.5/widget/_category_.json b/docs/versioned_docs/version-0.1.5/widget/_category_.json new file mode 100644 index 00000000..41e4c71d --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/widget/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Widget", + "position": 2 + } + \ No newline at end of file diff --git a/docs/versioned_docs/version-0.1.5/widget/resumed.md b/docs/versioned_docs/version-0.1.5/widget/resumed.md new file mode 100644 index 00000000..b7282f9b --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/widget/resumed.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 2 +--- + +# Resumed + +If you want to read a more complete description of how to use this widget, see the [Tutorial](./tutorial.md). But, if you is an advanced user, only install the package: + +```bash +pip install django-image-uploader-widget +``` + +and add the `image_uploader_widget` to the `INSTALLED_APPS` in the `settings.py`: + +```python +# ... + +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + 'django.contrib.contenttypes', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.staticfiles', + 'image_uploader_widget', +] + +# ... +``` + +And go to use it with your forms: + + +```python +from django.forms import ModelForm +from ecommerce.models import Product +from image_uploader_widget.widgets import ImageUploaderWidget + +class ProductForm(ModelForm): + class Meta: + model = Product + fields = ['name', 'image'] + widgets = { + 'image': ImageUploaderWidget() + } +``` + +![Image Uploader Widget](/img/tutorials/form_demo.png) diff --git a/docs/versioned_docs/version-0.1.5/widget/tutorial.md b/docs/versioned_docs/version-0.1.5/widget/tutorial.md new file mode 100644 index 00000000..d59f10aa --- /dev/null +++ b/docs/versioned_docs/version-0.1.5/widget/tutorial.md @@ -0,0 +1,278 @@ +--- +sidebar_position: 1 +--- + +# Tutorial + +First, we need of some context: the image uploader widget is a widget to handle image uploading with a beautiful interface with click to select file and a drop file behaviour handler. It is used with django forms. + +This is a more long and for newbies tutorial of how to use this widget. If you is an advanced user, see the [Resumed](./resumed.md) version. + +To write this tutorial of this documentation we go to create an empty django project, then if you don't want to see this part, skip to [using the widget section](#installing-the-widget). Another information is: we're assuming you already know the basics of **django** and already have it installed in your machine. + +## Creating a django project + +First, create a project folder. Here we call it as `my-ecommerce`: + +```bash +mkdir my-ecommerce +cd my-ecommerce +``` + +And, now, create a django project in this folder: + +```bash +django-admin startproject core . +``` + +And, then, we have the folder structure: + +``` +| - my-ecommerce + | - core + | - asgi.py + | - __init__.py + | - settings.py + | - urls.py + | - wsgi.py + | - manage.py +``` + +Create our **django** application by running the command: + +``` +python manage.py startapp ecommerce +``` + +And, now, we have a new, and more complex, folder structure: + +``` +| - my-ecommerce + | - core + | - asgi.py + | - __init__.py + | - settings.py + | - urls.py + | - wsgi.py + | - ecommerce + | - migrations + | - __init__.py + | - admin.py + | - apps.py + | - __init__.py + | - models.py + | - tests.py + | - views.py + | - manage.py +``` + +## Installing the widget + +To install the widget, is possible to use the same instructions of the [Introduction](../intro.md), and the first step is to install the package with pip: + +```bash +pip install django-image-uploader-widget +``` + +then, add it to the `INSTALLED_APPS` on the `settings.py`, in the case of this example: `core/settings.py` file. To understand better the Applications, see the django documentation: [Applications](https://docs.djangoproject.com/en/3.2/ref/applications/). + +```python +# core/settings.py +# ... + +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + 'django.contrib.contenttypes', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.staticfiles', + 'image_uploader_widget', +] + +# ... +``` + +### Warning + +**Observation**: note that the application name to be added on the `INSTALLED_APPS` are not equals to the pip package name / install name. + +## Using the widget + +We have two basic modes to use this widget: + +1. creating a ORM `Model` and using an `ModelForm` to it setting the widget. + +2. creating an custom `Form` with any other behaviour. + +### With ModelForm + +First, go to our ecommerce app models `ecommerce/models.py` and create a basic django model with an `ImageField`: + +```python +# ecommerce/models.py +from django.db import models + +class Product(models.Model): + name = models.CharField(max_length=100) + image = models.ImageField() + + def __str__(self): + return self.name + + class Meta: + verbose_name = 'Product' + verbose_name_plural = 'Products' +``` + +Now, we go to create our `ModelForm`. Create a empty file on `ecommerce/forms.py` to store our django forms. And create our own `ProductForm`: + +```python +# ecommerce/forms.py +from django.forms import ModelForm +from ecommerce.models import Product + +class ProductForm(ModelForm): + class Meta: + model = Product + fields = ['name', 'image'] +``` + +And, here, we can declare the widget that our `image` field uses: + +```python +# ecommerce/forms.py +from django.forms import ModelForm +from ecommerce.models import Product +from image_uploader_widget.widgets import ImageUploaderWidget + +class ProductForm(ModelForm): + class Meta: + model = Product + fields = ['name', 'image'] + widgets = { + 'image': ImageUploaderWidget() + } +``` + +#### Creating and applying migrations + +Our Model, declared in the above section, needs to be inserted on our database using the [migrations](https://docs.djangoproject.com/en/3.2/topics/migrations/). To create our migrations, we need to add our `ecommerce` app to `INSTALLED_APPS` on the `settings.py`: + +```python +# core/settings.py +# ... + +INSTALLED_APPS = [ + 'django.contrib.admin', + 'django.contrib.auth', + 'django.contrib.contenttypes', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.staticfiles', + 'image_uploader_widget', + 'ecommerce', +] + +# ... +``` + +Now, we go to create the migrations using the command: + +```bash +python manage.py makemigrations +``` + +If you found an `ecommerce.Product.image: (fields.E210) Cannot use ImageField because Pillow is not installed.` error, just run an: + +```bash +pip install Pillow +``` + +and re-run the makemigrations command. Now, we go to apply the migrations with: + +```bash +python manage.py migrate +``` + +And, now, we can run the development server to see our next steps coding: + +```bash +python manage.py runserver +``` + +#### See it in the action + +To see the widget in action, just go to the ecommerce app and create, in the `views.py`, an view that renders an form: + +```python +# ecommerce/views.py +from django.shortcuts import render +from ecommerce.forms import ProductForm + +def test_widget(request): + context = { 'form': ProductForm() } + return render(request, 'test_widget.html', context) +``` + +Now, we can create an `templates` folder in the `ecommerce` application and inside it we need to create a `test_widget.html`: + +```html + + + + + + + + Document + {{ form.media }} + + + + {{ form.as_p }} + + + +``` + +And register this view in the `core/urls.py`: + +```python +# core/urls.py +from django.contrib import admin +from django.urls import path +from ecommerce.views import test_widget + +urlpatterns = [ + path('admin/', admin.site.urls), + path('test_widget/', test_widget), +] +``` + +And go to the browser in `http://localhost:8000/test_widget/` and see the result: + +![Image Uploader Widget](/img/tutorials/form_demo.png) + + +### With Form and custom behaviour + +It's very like the above item and we need only to change some things in the `forms.py`: + +```python +from django import forms +from ecommerce.models import Product +from image_uploader_widget.widgets import ImageUploaderWidget + +class ProductForm(forms.Form): + image = forms.ImageField(widget=ImageUploaderWidget()) + + class Meta: + fields = ['image'] +``` + +And we not need to change nothing more. It works. + +### Comments about using with django-admin + +The use with **django-admin** is very like it: we only needs to create `ModelForm` for our models and in the `ModelAdmin` ([django documentation](https://docs.djangoproject.com/en/3.2/ref/contrib/admin/#django.contrib.admin.ModelAdmin)) we set our form ([here is an example](https://docs.djangoproject.com/en/3.2/ref/contrib/admin/#django.contrib.admin.ModelAdmin.form)). diff --git a/docs/versioned_sidebars/version-0.1.5-sidebars.json b/docs/versioned_sidebars/version-0.1.5-sidebars.json new file mode 100644 index 00000000..caea0c03 --- /dev/null +++ b/docs/versioned_sidebars/version-0.1.5-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index 1d8ad1ac..45f4905f 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "0.1.5", "0.1.4", "0.1.3", "0.0.6"