Skip to content
This repository has been archived by the owner on May 3, 2024. It is now read-only.

Latest commit

 

History

History
196 lines (139 loc) · 11.6 KB

adding_new_django_aspects.adoc

File metadata and controls

196 lines (139 loc) · 11.6 KB
Raw

Adding New Django Aspects

Adding a New DB {url-django-wiki-models}[Model]

  • Your {url-django-wiki-models}[model class] must be added inside ratemymodule/models/__init__.py

  • Your {url-django-wiki-models}[model class] must {url-django-wiki-models-inheritance}[inherit] from CustomBaseClass (found within models/utils.py)

  • If you {url-wiki-python-method-overriding}[override the superclass'] {url-django-wiki-models-clean}[clean()] or {url-django-wiki-models-save}[save()] methods, you must {url-wiki-python-super}[call back to the superclass] using super().clean() or super().save(*args, **kwargs), respectively. (See {url-django-wiki-models-overriding-methods}[Django’s documentation on overriding model methods])

  • {url-django-wiki-models-fields-verbose-name}[The verbose_name] for every {url-django-wiki-models}#fields[field in your model] must be a {url-django-wiki-translatable-string}[translatable string]. (See the existing `User` model as an example)

  • {url-django-wiki-models-verbose-name}[The verbose_name] within {url-django-wiki-models-meta}[the class Meta: of your model] must be a {url-django-wiki-translatable-string}[translatable string]. (See the existing User model as an example)

  • Read-only shortcut accessors can be defined with {url-wiki-python-property-decorator}[the @property decorator]

  • Any {url-django-wiki-models}#fields[model fields] must not be {url-wiki-python-type-annotations}[type-annotated]

    Example 1. Correct model field without {url-wiki-python-type-annotations}[type-annotation]
    first_name = models.CharField(max_length=50)
    Example 2. Incorrect model field with {url-wiki-python-type-annotations}[type-annotation]
    first_name: str = models.CharField(max_length=50)

  • After finishing your {url-django-wiki-models}[model class], but before committing your changes, run these {url-django-wiki-manage-commands}[manage.py commands] to {url-django-wiki-models-migrations}[migrate your Python changes to the database]:

    $ makemigrations
    $ migrate

    (You can run these commands easily within {url-pycharm-wiki-run-django-manage}[PyCharm’s manage.py interface]. Open it using the shortcut kbd:[Ctrl+Alt+R])

Adding a Model to the Admin UI

  • Your new {url-django-wiki-admin-site-modeladmin}[admin-configuration class] must be added inside ratemymodule/admin/__init__.py

  • A calculation function can be made into a value that can be displayed within {url-django-wiki-admin-site}[the admin interface] with {url-django-wiki-admin-site-display-decorator}[the @admin.display() decorator]. (See the UserAdmin class as an example)

Adding a New Web {labelled-url-wiki-url}

  • Your new web {labelled-url-wiki-url} must be added inside {url-django-wiki-urls-urlpatterns}[the view_urlpatterns list], within web/urls.py

  • Your {labelled-url-wiki-url} must {url-django-wiki-urls}#example[not start with a leading forward-slash (/)]

  • Your new web {labelled-url-wiki-url} must {url-django-wiki-urls}#example[end with a trailing forward-slash (/)]

  • {url-django-wiki-urls-path}[The route string parameter] to {url-django-wiki-urls-path}[the django.urls.path() function] must be {url-wiki-python-raw-strings}[a raw string]. (See the existing {url-django-wiki-urls-urlpatterns}[URL patterns] within web/urls.py for examples)

  • Your {url-django-wiki-urls-path}[URL pattern] must be named, so that it can be {url-django-wiki-urls-reverse}[reverse referenced] throughout this project. (See {url-django-wiki-urls-naming}[Django’s documentation on naming URL patterns] for more information on why this is beneficial)

  • You must use the full expansion of the import location of {url-django-wiki-urls-path}[the path() function (django.urls.path())], to make it clear which path() function is being used

Adding a New HTMX API {labelled-url-wiki-url}

  • Your new HTMX API {labelled-url-wiki-url} must be added inside {url-django-wiki-urls-urlpatterns}[the urlpatterns list], within api_htmx/urls.py

  • Your new HTMX API {labelled-url-wiki-url} must {url-django-wiki-urls}#example[not start with a leading forward-slash (/)]

  • Your {labelled-url-wiki-url} must {url-django-wiki-urls}#example[end with a trailing forward-slash (/)]

  • {url-django-wiki-urls-path}[The route string parameter] to {url-django-wiki-urls-path}[the django.urls.path() function] must be {url-wiki-python-raw-strings}[a raw string]. (See the existing {url-django-wiki-urls-urlpatterns}[URL patterns] within api_htmx/urls.py for examples)

  • Your {url-django-wiki-urls-path}[URL pattern] must be named, so that it can be {url-django-wiki-urls-reverse}[reverse referenced] throughout this project. (See {url-django-wiki-urls-naming}[Django’s documentation on naming URL patterns] for more information on why this is beneficial)

  • You must use the full expansion of the import location of {url-django-wiki-urls-path}[the path() function (django.urls.path())], to make it clear which path() function is being used

Adding a New Web {url-django-wiki-views}[View]

  • Your new web {url-django-wiki-views}[view] must be added inside web/views/__init__.py

  • Your new web {url-django-wiki-views}[view] must be a {url-django-wiki-views-class-based}[classed-based view] that inherits from at least {url-django-wiki-views-template-response}[Django’s base View]

  • Your new web {url-django-wiki-views}[view] must be named using {labelled-url-wiki-pascal-case}. (E.g. HomeView)

  • Your new web {url-django-wiki-views}[view] must end with the word View. (E.g. HomeView)

  • Any configuration {url-wiki-python-class-attributes}[class-variables] must not be {url-wiki-python-type-annotations}[type-annotated] {url-wiki-python-type-annotations}

    Example 3. Correct class-variable without type-annotation
    template_name = "ratemymodule/home.html"
    Example 4. Incorrect class-variable with type-annotation
    template_name: str = "ratemymodule/home.html"

Adding a New HTMX API {url-django-wiki-views}[View]

  • Your new HTMX API {url-django-wiki-views}[view] must be added inside api_htmx/views/__init__.py

  • Your new HTMX API {url-django-wiki-views}[view] must be a {url-django-wiki-views-class-based}[classed-based view] that inherits from at least {url-django-wiki-views-base-view}[Django’s base View]

  • Your new HTMX API {url-django-wiki-views}[view] must be named using {labelled-url-wiki-pascal-case}. (E.g. LoginPopUpView)

  • Your new HTMX API {url-django-wiki-views}[view] must end with the word View. (E.g. LoginPopUpView)

  • Any configuration {url-wiki-python-class-attributes}[class-variables] must not be {url-wiki-python-type-annotations}[type-annotated]

    Example 5. Correct class-variable without type-annotation
    template_name = "ratemymodule/htmx_fragments/login_pop_up.html"
    Example 6. Incorrect class-variable with type-annotation
    template_name: str = "ratemymodule/htmx_fragments/login_pop_up.html"

Adding a New Web {url-django-wiki-templates}[HTML Template]

  • Your new web {url-django-wiki-templates}[HTML Template] must be added inside web/templates/ratemymodule/

  • Your new web {url-django-wiki-templates}[HTML template] must {url-django-wiki-templates-inheritance}[extend] from at least web/templates/ratemymodule/base.html. You can do this by adding the {url-django-wiki-templates-tags-extends}[extends]-template-tag {% extends "ratemymodule/base.html" %} to the top of your {url-django-wiki-templates}[HTML template]. ({url-django-wiki-templates-inheritance}[Extending] from base.html ensures your {url-django-wiki-templates}[HTML template] contains consistent styling, favicons and the header & footer, as defined in the base HTML template)

  • {url-django-wiki-templates-tags-static}[Referencing the location of static files] can be {url-django-wiki-templates-tags-load}[enabled] by adding the {url-django-wiki-templates-tags-static}[{% load static %}] {url-django-wiki-templates-tags}[template-tag] to the top of your {url-django-wiki-templates}[HTML template].

    Example 7. Using the {url-django-wiki-templates-tags-static}[static tag] to locate the source of a {url-wiki-static-web-files}[static] {url-wiki-image}[image file]
    <img src="{% static 'ratemymodule/icons/logo.svg' %}" alt="RateMyModule Logo" class="logo"/>

Adding a New HTMX API {url-django-wiki-templates}[HTML Template]

  • Your new HTMX API {url-django-wiki-templates}[HTML Template] must be added inside api_htmx/templates/ratemymodule/

  • Your new HTMX API {url-django-wiki-templates}[HTML template] must not {url-django-wiki-templates-inheritance}[extend] from any wider templates within web/templates/ratemymodule/. ({url-django-wiki-templates}[HTML template] fragments are {url-htmx-wiki-ajax}[delivered to HTMX on the client device] and {url-htmx-wiki-swapping}[placed within existing major HTML templates that have already been served to the client])

  • {url-django-wiki-templates-tags-static}[Referencing the location of static files] can be {url-django-wiki-templates-tags-load}[enabled] by adding the {url-django-wiki-templates-tags-load}[{% load static %}] {url-django-wiki-templates-tags}[template-tag] to the top of your {url-django-wiki-templates}[HTML template].

    Example 8. Using the static tag to locate the source of a static image file
    <img src="{% static 'ratemymodule/icons/logo.svg' %}" alt="RateMyModule Logo" class="logo"/>

Adding Static Files

  • Any new {url-wiki-static-web-files}[static files] (E.g. url-wiki-image[images]) must be stored within the web/static/ratemymodule/ directory

  • It may be useful to organise files into {url-wiki-subdirectory}[subdirectories] within the web/static/ratemymodule/ directory

    Example 9. Example: Organising static files into a subdirectory
    All files relating to {url-wiki-favicon}[favicons] could be stored inside web/static/ratemymodule/favicon/