Utangulizi

Katika mifumo mingi mitandaoni tunahitaji kupokea picha kutoka kwa watumiaji: iwe profile picture, product, receipt, au document. Django ni moja ya frameworks zinazoruhusu kushughulikia hii kwa urahisi sana kwa kutumia ImageField, MEDIA_URL, na MEDIA_ROOT.

Leo tutajifunza mfumo mzima kuanzia configuration hadi uonyeshaji wa picha.

Sasa tuingie kwenye somo letu…

SEHEMU YA 1 — Kupanga SETTINGS za media (settings.py)

Kwa default Django haitumii media (files zinazopakiwa), hivyo tunahitaji kuongeza settings mbili muhimu:

1. MEDIA_URL

Hii ndiyo URL itakayotumika kuifikia picha kupitia browser.

Mfano:

MEDIA_URL = '/media/'

2. MEDIA_ROOT

Hiki ni kipath cha folder halisi kwenye computer ambako picha zitahifadhiwa.

Mfano:

import os
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

Mahali pa kuweka hizi settings

Zinawekwa ndani ya settings.py sehemu ya chini mara nyingi baada ya STATIC settings, mfano:

# Static files
STATIC_URL = '/static/'

# Media files
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

Kazi yake:

MEDIA_URL → Prefix ya kutembelea picha kupitia browser
MEDIA_ROOT → Folder ambapo picha zinawekwa kimwili

SEHEMU YA 2 — Kuandaa URL configuration ya media (urls.py)

Hii ni muhimu kwenye development environment; bila hii Django haitoweza kuserve picha.

Fungua project_name/urls.py na ongeza:

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... your URLs
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Kazi ya code hii:

Inaruhusu Django kuserve picha ukiwa kwenye development mode
Production haitumii hii (unakabidhi Nginx au cloud)

SEHEMU YA 3 — Kutengeneza Model yenye ImageField

Fungua app/models.py:

from django.db import models

class ProfilePicture(models.Model):
    title = models.CharField(max_length=100)
    image = models.ImageField(upload_to='uploads/')
    uploaded_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

Maelezo ya kandoni:

upload_to="uploads/" inasababisha picha kuwekwa ndani ya:
media/uploads/filename.jpg
ImageField inahitaji Pillow

Install Pillow:

pip install Pillow

SEHEMU YA 4 — Kufanya Migration

Baada ya kuongeza model:

python manage.py makemigrations
python manage.py migrate

Bila migration:

Django haitatengeneza jedwali
Huwezi kusave picha kwenye database
ImageField itatoa error

SEHEMU YA 5 — Kutengeneza Form ya kupokea picha

Fungua app/forms.py:

from django import forms
from .models import ProfilePicture

class PictureForm(forms.ModelForm):
    class Meta:
        model = ProfilePicture
        fields = ['title', 'image']

SEHEMU YA 6 — Kutengeneza View ya kupokea picha na kuisave

from django.shortcuts import render, redirect
from .forms import PictureForm

def upload_picture(request):
    if request.method == 'POST':
        form = PictureForm(request.POST, request.FILES)
        
        if form.is_valid():
            form.save()
            return redirect('picture_list')
    else:
        form = PictureForm()

    return render(request, 'upload_picture.html', {'form': form})

Maelezo ya kina:

request.FILES MUST → bila hili Django haisomi picha
form.save() → inaandika data DB, na kuhifadhi picha MEDIA_ROOT

SEHEMU YA 7 — Template ya Upload (HTML)

templates/upload_picture.html

<form method="POST" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form.as_p }}

    <button type="submit">Upload Picture</button>
</form>

Kwa nini `enctype="multipart/form-data"` ni lazima?

Bila hii browser haitatuma file
Hata kama form inaonekana sahihi, Django haitapokea picha

SEHEMU YA 8 — View ya kusoma picha zote

from django.shortcuts import render
from .models import ProfilePicture

def picture_list(request):
    pictures = ProfilePicture.objects.all()
    return render(request, 'picture_list.html', {'pictures': pictures})

SEHEMU YA 9 — Template ya kuonyesha picha

templates/picture_list.html

<h2>Uploaded Pictures</h2>

{% for pic in pictures %}
    <div style="margin-bottom:20px;">
        <h4>{{ pic.title }}</h4>
        <img src="{{ pic.image.url }}" width="200px">
    </div>
{% empty %}
    <p>No pictures uploaded.</p>
{% endfor %}

Maelezo:

{{ pic.image.url }} → Django automatically hutengeneza URL ya picha
Ikiwa MEDIA_URL = "/media/", basi picha itapatikana kama:
127.0.0.1:8000/media/uploads/pic.jpg

Kwa utaratibu huu huu unaweza ku-upload PDF, documents, audio, videos au file lolote — ila badala ya ImageField utatumia FileField, na badala ya kuonyesha kwa <img> utaita file.url.