admin site, more crud operations

Author: norareidy

snooty.toml

@@ -26,7 +26,7 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 driver-short = "PyMongo"
 driver-long = "PyMongo, the MongoDB synchronous Python driver,"
 driver-async = "PyMongo Async"
-django-odm = "Django MongoDB"
+django-odm = "MongoDB Backend for Django"
 language = "Python"
 mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"

source/django-get-started.txt

@@ -27,6 +27,7 @@ Get Started with {+django-odm+}
    Create an Application </django-get-started/django-create-app/>
    Write Data to MongoDB </django-get-started/django-write-data/>
    Query MongoDB Data </django-get-started/django-query-data/>
+   Create an Admin Site </django-get-started/django-create-admin/>
    Next Steps </django-get-started/django-next-steps/>
 
 {+django-odm+} is a PyMongo integration that allows you to use the

source/django-get-started/django-create-admin.txt

@@ -0,0 +1,130 @@
+.. _django-get-started-create-admin:
+
+====================
+Create an Admin Site
+====================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: app, odm, code example
+
+You can create a Django admin site to edit your application's 
+data from a web interface. To learn more about the Django admin
+site and its features, see `The Django admin site <https://docs.djangoproject.com/en/5.1/ref/contrib/admin/>`__
+in the Django documentation.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create an admin user
+
+      Before creating an admin site, you must create a user
+      who can log in to the site. 
+      
+      From your project's root directory, run the following command to create
+      an admin user:
+      
+      .. code-block:: bash
+
+         python3 manage.py createsuperuser
+
+      Then, your terminal prompts you for a username, email address,
+      and password. For each prompt, enter the following information
+      to create a user with the specified credentials and press "enter"
+      after each entry:
+
+      .. code-block:: bash
+
+         Username: admin
+         Email address: [email protected]
+         Password: <admin-password>
+         Password (again): <admin-password>
+
+      Replace the ``<admin-password>`` placeholder with your user's password.
+
+   .. step:: Enter the admin site
+
+      Run the following code to start your server:
+    
+      .. code-block:: bash
+
+         python3 manage.py runserver
+
+      Once your server is running, visit the http://127.0.0.1:8000/admin/ 
+      URL to see the admin site. This site displays the following login
+      screen:
+
+      .. figure:: /includes/figures/django_admin_login.png
+         :alt: The login screen on the Django admin page.
+     
+      Enter the username and password created in the previous step to log in to
+      the site. 
+
+   .. step:: Access your sample_mflix app from the admin site
+
+      After logging in to the admin site, you can see the following index
+      page:
+
+      .. figure:: /includes/figures/django_admin_index.png
+         :alt: The initial content displayed on the Django admin site.
+
+      You can edit your project's authentication configuration by selecting
+      the :guilabel:`Groups` or :guilabel:`Users` row in the 
+      :guilabel:`Authentication and Authorization` table.
+      
+      To edit the data in the ``users`` sample collection, represented by your
+      ``Viewer`` model, navigate to your project's ``sample_mflix/admin.py`` file
+      and paste the following code:
+      
+      .. code-block:: python
+
+         from django.contrib import admin
+
+         from .models import Viewer
+
+         admin.site.register(Viewer)
+
+      Now, your admin site displays the following information:
+
+      .. figure:: /includes/figures/django_admin_model.png
+         :alt: The content displayed on the Django admin site after registering a model.
+   
+   .. step:: Select a Viewer object
+
+      You can view the data stored in a ``Viewer`` object that
+      has a ``name`` value of ``"Abigail Carter"``. You created
+      this object in the :ref:`django-get-started-write` step
+      of this tutorial.
+
+      Click on the :guilabel:`Viewers` row of the :guilabel:`SAMPLE_MFLIX`
+      table to see a list of viewers. The admin site displays the following
+      list:
+      
+      .. figure:: /includes/figures/django_admin_viewers.png
+         :alt: The list of viewers displayed on the admin site.
+      
+      Then, click on :guilabel:`Abigail Carter` at the top of the list.
+      The site displays the :guilabel:`Name`, :guilabel:`Email`, and :guilabel:`Password`
+      of the selected viewer:
+
+      .. figure:: /includes/figures/django_admin_edit_viewer.png
+         :alt: The information of your selected viewer.
+
+   .. step:: Edit the data in a Viewer object
+
+      To edit the ``email`` field of the viewer, select the 
+      box that contains the text ``"[email protected]"``.
+      Delete this text and replace it with ``"[email protected]"``,
+      as shown in the following image:
+      
+      .. figure:: /includes/figures/django_admin_new_email.png
+         :alt: The updated email address of your viewer.
+
+      Then, click the :guilabel:`SAVE` button below the viewer's 
+      information to save your changes.
+
+After completing these steps, you can access the Django
+admin site and use it to edit your ``Viewer`` objects.

source/django-get-started/django-create-app.txt

@@ -28,45 +28,61 @@ Create an Application
          The ``django-mongodb-app`` template ensures that your ``app.py`` file
          includes the line ``"default_auto_field = 'django_mongodb.fields.ObjectIdAutoField'"``.
 
-   .. step:: Create models for movie and user data
+   .. step:: Create models for movie, awards, and viewer data
 
       Open the ``models.py`` file in the ``sample_mflix`` directory and replace 
       its contents with the following code:
 
       .. code-block:: python
 
          from django.db import models
+         from django_mongodb.fields import EmbeddedModelField, ArrayField
 
-         class Movies(models.Model):
+         class Movie(models.Model):
             title = models.CharField(max_length=200)
             plot = models.TextField(null=True)
             runtime = models.IntegerField(default=0)
             released = models.DateTimeField("release date", null=True)
+            awards = EmbeddedModelField(Award)
+            genres = ArrayField(models.CharField(max_length=100), blank=True)
 
             class Meta:
-               managed = False
                db_table = "movies"
 
             def __str__(self):
                return self.title
+            
+         class Award(models.Model):
+            wins = models.IntegerField(default=0)
+            nominations = models.IntegerField(default=0)
+            text = models.CharField(max_length=100)
 
+            class Meta:
+               abstract = True
 
-         class Users(models.Model):
+         class Viewer(models.Model):
             name = models.CharField(max_length=100)
             email = models.CharField(max_length=200)
             password = models.CharField(max_length=100)
 
             class Meta:
-               managed = False
                db_table = "users"
 
             def __str__(self):
                return self.name
 
-      The ``Movies`` model represents the ``sample_mflix.movies`` collection
-      and stores information about movies. The ``Users`` model represents
-      the ``sample_mflix.users`` collection and stores account credentials
-      for users of a movie streaming platform.
+      The ``Movie`` model represents the ``sample_mflix.movies`` collection
+      and stores information about movies. This model contains an embedded 
+      model field named ``awards``, which stores an ``Award`` object. The
+      model also contains an array field named ``genres``, which stores
+      a list of genres that describe the movie.
+
+      The ``Award`` model does not represent a separate collection. Instead, it 
+      represents the embedded document values that the ``awards``
+      field of the ``Movie`` model stores.
+      
+      The ``Viewer`` model represents the ``sample_mflix.users`` collection
+      and stores account credentials for movie viewers.
 
    .. step:: Create views to display data
 
@@ -78,21 +94,22 @@ Create an Application
          from django.http import HttpResponse
          from django.shortcuts import render
 
-         from .models import Movies, Users
+         from .models import Movie, Viewer
 
          def index(request):
-            return HttpResponse("Hello! You've reached the Django MongoDB sample app landing page.")
+            return HttpResponse("Hello, world. You're at the application index.")
+
 
          def recent_movies(request):
-            movies = Movies.objects.all().order_by('-released')[:5]
+            movies = Movie.objects.all().order_by('-released')[:5]
             return render(request, 'recent_movies.html', {'movies': movies})
 
-         def users_list(request):
-            users = Users.objects.all().order_by('name')[:10]
-            return render(request, 'users_list.html', {'users': users})
+         def viewers_list(request):
+            viewers = Viewer.objects.all().order_by('name')[:10]
+            return render(request, 'viewers_list.html', {'viewers': viewers})
 
-      These views display a landing page message and information about your ``Movies``
-      and ``Users`` models.
+      These views display a landing page message and information about your ``Movie``
+      and ``Viewer`` models.
 
    .. step:: Configure URLs for your views
 
@@ -109,7 +126,7 @@ Create an Application
          urlpatterns = [
             path("", views.index, name="index"),
             path('recent_movies/', views.recent_movies, name='recent_movies'),
-            path('users_list/', views.users_list, name='users_list'),
+            path('viewers_list/', views.viewers_list, name='viewers_list'),
          ]
 
       Then, navigate to the ``quickstart/urls.py`` file and replace its contents with
@@ -158,20 +175,20 @@ Create an Application
       This template formats the movie data requested by the ``recent_movies`` view.
 
       Create another file in the ``sample_mflix/templates`` directory called
-      ``users_list.html`` and paste the following code:
+      ``viewers_list.html`` and paste the following code:
 
       .. code-block:: python
 
-         <!-- templates/users_list.html -->
+         <!-- templates/viewers_list.html -->
          <!DOCTYPE html>
          <html lang="en">
          <head>
             <meta charset="UTF-8">
             <meta name="viewport" content="width=device-width, initial-scale=1.0">
-            <title>Users List</title>
+            <title>Viewers List</title>
          </head>
          <body>
-            <h1>Alphabetical Users List</h1>
+            <h1>Alphabetical Viewers List</h1>
             <table>
                <thead>
                      <tr>
@@ -180,22 +197,22 @@ Create an Application
                      </tr>
                </thead>
                <tbody>
-                     {% for user in users %}
+                     {% for viewer in viewers %}
                         <tr>
-                           <td>{{ user.name }}</td>
-                           <td>{{ user.email }}</td>
+                           <td>{{ viewer.name }}</td>
+                           <td>{{ viewer.email }}</td>
                         </tr>
                      {% empty %}
                         <tr>
-                           <td colspan="2">No users found.</td>
+                           <td colspan="2">No viewer found.</td>
                         </tr>
                      {% endfor %}
                </tbody>
             </table>
          </body>
          </html>
 
-      This template formats the user data requested by the ``users_list`` view.
+      This template formats the user data requested by the ``viewers_list`` view.
 
    .. step:: Include your app in your project
 
@@ -217,7 +234,7 @@ Create an Application
    .. step:: Create migrations for your new models
 
       From your project root, run the following command to create
-      migrations for the ``Movies`` and ``Users`` models and apply
+      migrations for the ``Movie``, ``Award``, and ``Viewer`` models and apply
       the changes to the database:
 
       .. code-block:: bash

source/django-get-started/django-query-data.txt

@@ -16,21 +16,24 @@ Query MongoDB Data
 
    .. step:: Query the users collection for a specified email
 
-      From the same Python shell as the :ref:`django-get-started-write`
-      step of this tutorial, run the following code to query the 
-      ``sample_mflix.users`` collection for a user whose email is 
+      Start a Python shell and include the required imports
+      by running the following code:
+      
+      
+      Then, run the following code to query the 
+      ``sample_mflix.users`` collection for a movie viewer whose email is 
       ``"[email protected]"``:
 
       .. code-block:: bash
 
-         Users.objects.filter(email="[email protected]").first()
+         Viewer.objects.filter(email="[email protected]").first()
 
       This code returns the name of the matching user:
 
       .. code-block:: bash
          :copyable: false
 
-         <QuerySet [<Users: Khal Drogo>]>
+         <QuerySet [<Viewer: Khal Drogo>]>
 
    .. step:: Query the movies collection for runtime values
 
@@ -40,23 +43,23 @@ Query MongoDB Data
 
       .. code-block:: bash
 
-         Movies.objects.filter(runtime__lt=10)
+         Movie.objects.filter(runtime__lt=10)
 
       This code returns a truncated list of the matching movies:
 
       .. code-block:: bash
          :copyable: false
 
-         <QuerySet [<Movies: Winsor McCay, the Famous Cartoonist of the N.Y.
-         Herald and His Moving Comics>, <Movies: Steamboat Willie>, <Movies:
-         Three Little Pigs>, <Movies: The Band Concert>, <Movies: Who Killed Cock Robin?>,
-         <Movies: Dots>, <Movies: The Cat Concerto>, <Movies: Begone Dull Care>,
-         <Movies: Mi adorado Juan>, <Movies: Neighbours>, <Movies: A Phantasy>,
-         <Movies: Duck Amuck>, <Movies: Duck Dodgers in the 24èth Century>,
-         <Movies: Blinkity Blank>, <Movies: One Froggy Evening>,
-         <Movies: What's Opera, Doc?>, <Movies: Lines: Horizontal>,
-         <Movies: Il fornaretto di Venezia>, <Movies: Dog Star Man: Part IV>,
-         <Movies: Now>, '...(remaining elements truncated)...']>
+         <QuerySet [<Movie: Winsor McCay, the Famous Cartoonist of the N.Y.
+         Herald and His Moving Comics>, <Movie: Steamboat Willie>, <Movie:
+         Three Little Pigs>, <Movie: The Band Concert>, <Movie: Who Killed Cock Robin?>,
+         <Movie: Dots>, <Movie: The Cat Concerto>, <Movie: Begone Dull Care>,
+         <Movie: Mi adorado Juan>, <Movie: Neighbours>, <Movie: A Phantasy>,
+         <Movie: Duck Amuck>, <Movie: Duck Dodgers in the 24èth Century>,
+         <Movie: Blinkity Blank>, <Movie: One Froggy Evening>,
+         <Movie: What's Opera, Doc?>, <Movie: Lines: Horizontal>,
+         <Movie: Il fornaretto di Venezia>, <Movie: Dog Star Man: Part IV>,
+         <Movie: Now>, '...(remaining elements truncated)...']>
 
 After completing this step, you can run queries on data stored in 
 your MongoDB deployment.