django - exploration notes
-------------------------------

setup -
-----------------------------------

add routes & register app
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. register your app (which is the folder containing migration, apps, models, etc *not* the site one)
    #. in mysite/urls.py. Then add `path('django_demo_00/', include('django_demo_00.urls'))` to the `url_patterns` variable.
#. `myapp` also needs a urls.py file
    #. copy that from the site's one (PC doesn't include one by default for some reason)
    #. add `path('/', views.index, name='index'),` to `urlpatterns`
    #. e.g. `path('url/to/endpoint', views.endpoint_handler_method, name='somename')`
#. `views.py` needs an handler as defined in `myapp/urls.py`
    #. add a `def myenpoint(rsqt)` similar to cherrypy
    #. call the buzlogic to handle stuff, return a response etc.

So essentially, 3 things to do: register your app in mysite/urls.py, register your app's endpoints in myapp/urls.py and create views (endpoint handlers) in myapp/views.py

database setup
~~~~~~~~~~~~~~~~~~~~~~~~

* `mySite/settings.py` is useful here. not much to do if using the default db (sqlite3) but you could set a different backend.

* need to add something like `django_app.apps.DjangoAppConfig` to your INSTALLED_APPS

    * behavior of the app is defined in DjangoAppConfig (or whatever your app,s named)

* `makemigrations`, `migrate`, and `sqlmigrate` - what's the difference?
    * `makemigrations` creates the migration roadmap based on model changes since last migration
    * `migrate` applies all those changes, to the DB (but potentially to other stuff like auth etc. if anything changed there)
    * `slqmigrate appname migration_number` prints the SQL that will be applied for a migration
        * it needs an active DB connexion to resolve constraints
        * it will NOT apply stuff
        * needs to know for which app (appname) and a 000X number (the migration number)

defining your model (and db schema)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. this is done in models.py

#. each class is a db table
    #. each class attribute is a db field

#. once all that is done, run `python manage.py makemigrations myapp`
    #. this will build the migration details, that include all changes to the db schema
    #. a new migrations will be under myapp/migrations/xxxx_mymigration.py
    #. this migration details all that has changed since the last migration (or the firt mig if its the first).
#. then run `python manage.py migration` to actually apply stuff


define the views (front end)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* views are defined in views.py. a view has a handler (method) in views.py that defines what happens

* the views must be mapped to urlpatterns in myapp/urls.py. that allows each endpoint to know what to display/render at .../myapp/myendpoint/

* templates are used to decouple the views and the http response.

* a view returns a template, therefore we can easily chg/update a template without touching the code

templates
^^^^^^^^^^^^^^^^^^

templates are managed in `myapp/templates/myapp/mypage.html`. **you do need to repeat the appname after /templates/**. this is django's linker that needs it to ensure proper matching of html & views. this only matters for a site with multiple apps (most sites will have multiple apps)

steps to enable templates:

#. create some `/django_app/templates/django_app/mypage.html` files. will contain jquery-like {{var.attribute}} syntax, with {% [ some python code ] %}
#. update the endpoint treatement method in views.py, since we now want to return a certain template not directly the response
#. they are one of the options for front-end with django. Within django, jinja2 also exists
#. don't allow users to directly submit templates - templates can use other templates( risks of xss attackts etc.)

loading a template
++++++++++++++++++++++

in an endpoint in `views.py`,  a few ways to get/open/load a template with the engine:

#. get_template(tplt_name)
    #. given a template name, finds it in TEMPLATE["DIRS"]
    #. parse it each templating engines
#. select_template(tplt_name_list)
    #. provide one or many tplt names inthe list
    #. returns the first that,s successfully parsed by engine
    #. allows u to provide fallback options (if error etc.)




what's a template
^^^^^^^^^^^^^^^^^^^^^^^^

* it's written in *django's teamplate language*.
* you can extend it
* the `philosophy <https://docs.djangoproject.com/en/3.0/ref/templates/language/#the-django-template-language>`_ behind the template language:
    * making people edit xml is "sadistic" according to docs
    * meant to express presentation, not program logic
    * it doesn't execute arbitrary python code
    * it's *not* a straight processing of {{% python-ish code %}} within tags in an html file
    * it can be extended


logging stuff
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* django initiates its logs pretty early in the launch

* logs shoulds be initiated in settings.py, so that they are available as soon as possible @ startup

* my current setup closerly follows the `documentation <https://docs.djangoproject.com/en/3.0/topics/logging/#examples>`_. Use defaults as much as possible, need to nerd basis. I have basic logging, including the django specific stuff, so I'm happy.


the installed apps
^^^^^^^^^^^^^^^^^^^^^^^^^^

* these are things that django will "build" when you `python manage.py migrate` (& similar cmds)

* eventually our app (when it has models defined) will be added to the `INSTALLED_APPS[]` list.

the adminuser on db
^^^^^^^^^^^^^^^^^^^^^^^^

* django has an admin setup/region to manage the db. **see how it compares with the integrated db management in pycharm - might just opt for that instead**

creation of adminuser
+++++++++++++++++++++++++++++

#. `python manage.py createsuperuser`
    * will be some shell interactions, choose usernamer & password
    * let,s default to username: admin, pass: sonjewer, email logiconabstractions
#. to access the admin page:
    * `python manage.py runserver`
    * go to 0.0.0.0:8000/admin & login with prev. credentials
#. adding stuff to manage
    #. by default, our models elements (class of models.py) aren't included in the administratable area
    #. to add them, need to register them in `myapp/admin.py`.
    #. add a line admin.site.register(MyModelClass)
    #. ultimately this is kind of a pgmyadmin with postgres

**this feature is overall pretty cool and I wouldn't bother much with PC's integrated stuff. Except perhaps to run sql-lite cmds instead of using a UI.**


quick useful cmds
--------------------

* `python manage.py runserver [port:8000]`

* `python manage.py makemigrations`, `python manage.py sqlmigrate myapp 000x`

* `python manage.py shell`  (interact with db/model live)

gotchas, common error msg etc.
------------------------------------------

* when running the server or migrate: complaints about "duplicate label" is probably that you have  registered the application twice in the `INSTALLED_APPS`

very high-lvl notes on django
-----------------------------------------

#. migrations (updates to the database) are done on a differential basis
    #. this means that the sql generate for a migration assumes the previous state of the database is as expected based on the model evolution
    #. deleting/moving/reformating the directory structure should be done with care, otherwise this may break the db

#. django app are meant to be REALLy small
    #. think of them more as a single class than as a server application
    #. from ` a blog post<https://justin.abrah.ms/this-and-that/fitures_model_subdir.html>`_, you should probably not NEED much to have a complex dir structure under myapp/models/[bunch of models classes]
    #. from django's perspective, different apps should foces on a clear purpose and do just only that. if you need to more classes, you probably need more apps.