| 1 |
===================================== |
| 2 |
Writing your first Django app, part 8 |
| 3 |
===================================== |
| 4 |
|
| 5 |
This tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>` left off. We've |
| 6 |
built our web-poll application and will now look at third-party packages. One of |
| 7 |
Django's strengths is the rich ecosystem of third-party packages. They're |
| 8 |
community developed packages that can be used to quickly improve the feature set |
| 9 |
of an application. |
| 10 |
|
| 11 |
This tutorial will show how to add :pypi:`Django Debug Toolbar |
| 12 |
<django-debug-toolbar>`, a commonly used third-party package. The Django Debug |
| 13 |
Toolbar has ranked in the top three most used third-party packages in the |
| 14 |
Django Developers Survey in recent years. |
| 15 |
|
| 16 |
.. admonition:: Where to get help: |
| 17 |
|
| 18 |
If you're having trouble going through this tutorial, please head over to |
| 19 |
the :doc:`Getting Help</faq/help>` section of the FAQ. |
| 20 |
|
| 21 |
Installing Django Debug Toolbar |
| 22 |
=============================== |
| 23 |
|
| 24 |
Django Debug Toolbar is a useful tool for debugging Django web applications. |
| 25 |
It's a third-party package that is maintained by the community organization |
| 26 |
`Django Commons <https://github.com/django-commons>`_. The toolbar helps you |
| 27 |
understand how your application functions and to identify problems. It does so |
| 28 |
by providing panels that provide debug information about the current request |
| 29 |
and response. |
| 30 |
|
| 31 |
To install a third-party application like the toolbar, you need to install |
| 32 |
the package by running the below command within an activated virtual |
| 33 |
environment. This is similar to our earlier step to :ref:`install Django |
| 34 |
<installing-official-release>`. |
| 35 |
|
| 36 |
.. console:: |
| 37 |
|
| 38 |
$ python -m pip install django-debug-toolbar |
| 39 |
|
| 40 |
Third-party packages that integrate with Django need some post-installation |
| 41 |
setup to integrate them with your project. Often you will need to add the |
| 42 |
package's Django app to your :setting:`INSTALLED_APPS` setting. Some packages |
| 43 |
need other changes, like additions to your URLconf (``urls.py``). |
| 44 |
|
| 45 |
Django Debug Toolbar requires several setup steps. Follow them in `its |
| 46 |
installation guide |
| 47 |
<https://django-debug-toolbar.readthedocs.io/en/latest/installation.html>`_. |
| 48 |
The steps are not duplicated in this tutorial, because as a third-party |
| 49 |
package, it may change separately to Django's schedule. |
| 50 |
|
| 51 |
Once installed, you should be able to see the DjDT "handle" on the right side |
| 52 |
of the browser window when you browse to ``http://localhost:8000/admin/``. |
| 53 |
Click it to open the debug toolbar and use the tools in each panel. See the |
| 54 |
`panels documentation page`__ for more information on what the panels show. |
| 55 |
|
| 56 |
__ https://django-debug-toolbar.readthedocs.io/en/latest/panels.html |
| 57 |
|
| 58 |
Getting help from others |
| 59 |
======================== |
| 60 |
|
| 61 |
At some point you will run into a problem, for example the |
| 62 |
toolbar may not render. When this happens and you're unable to |
| 63 |
resolve the issue yourself, there are options available to you. |
| 64 |
|
| 65 |
#. If the problem is with a specific package, check if there's a |
| 66 |
troubleshooting guide or FAQ in the package's documentation. For example the |
| 67 |
Django Debug Toolbar has a `Tips section |
| 68 |
<https://django-debug-toolbar.readthedocs.io/en/latest/tips.html>`_ that |
| 69 |
outlines troubleshooting options. |
| 70 |
#. Search for similar issues on the package's issue tracker. Django Debug |
| 71 |
Toolbar’s is `on GitHub <https://github.com/django-commons/django-debug-toolbar/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc>`_. |
| 72 |
#. Consult the `Django Forum <https://forum.djangoproject.com/>`_. |
| 73 |
#. Join the `Django Discord server <https://chat.djangoproject.com>`_. |
| 74 |
|
| 75 |
Installing other third-party packages |
| 76 |
===================================== |
| 77 |
|
| 78 |
There are many more third-party packages, which you can find using the |
| 79 |
fantastic Django resource, `Django Packages <https://djangopackages.org/>`_. |
| 80 |
|
| 81 |
It can be difficult to know what third-party packages you should use. This |
| 82 |
depends on your needs and goals. Sometimes it's fine to use a package that's |
| 83 |
in its alpha state. Other times, you need to know it's production ready. |
| 84 |
`Adam Johnson has a blog post |
| 85 |
<https://adamj.eu/tech/2021/11/04/the-well-maintained-test/>`_ that outlines |
| 86 |
a set of characteristics that qualifies a package as "well maintained". |
| 87 |
Django Packages shows data for some of these characteristics, such as when the |
| 88 |
package was last updated. |
| 89 |
|
| 90 |
As Adam points out in his post, when the answer to one of the questions is |
| 91 |
"no", that's an opportunity to contribute. |
| 92 |
|
| 93 |
What's next? |
| 94 |
============ |
| 95 |
|
| 96 |
The beginner tutorial ends here. In the meantime, you might want to check out |
| 97 |
some pointers on :doc:`where to go from here </intro/whatsnext>`. |
| 98 |
|
| 99 |
If you are familiar with Python packaging and interested in learning how to |
| 100 |
turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to |
| 101 |
write reusable apps</intro/reusable-apps>`. |