root/docs/everes/20090425_django_hands_on_b/docs/HandsOnB.txt @ 32779

=======================================================
Django Hands on for beginners.
=======================================================

超基本
-------------------------------------------------------------------------
* Webの仕組み

* Modelって何？


→ 拙著 `Django×Python`_ 等の入門書を読んでください。


.. _`Django×Python`: http://www.amazon.co.jp/dp/477413760X


Djangoの超基本(BASE)
-------------------------------------------------------------------------
マルチユーザblogっぽいものを作ろう！

ブログのモデルを考える
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* エントリー → タイトル、本文、タグ、公開日、書いた人
* タグ → タグ名、持ち主


エントリーのモデルサンプル: ForeignKeyやManyToManyに指定するモデルは、
指定よりも先に定義が読み込まれていなければならない。
どうしようもない場合には文字列で定義すればよい。
::


  class Tag(models.Model):
    name = models.CharField(u'タグ名', max_length=50)
    user = models.ForeignKey(User)
    
    class Meta:
      ordering = ['user', 'name']
  
  class Entry(models.Model):
    title = models.CharField(u'タイトル', max_length=50)
    body = models.TextField(u'本文')
    tags = models.ManyToManyField(Tag, blank=True)
    pub_date = models.DateTimeField(default=datetime.now)
    author = models.ForeignKey(User)
  
    class Meta:
        ordering = ['pub_date']


アプリケーション構成を考える
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
タグを別にしてもよいので、せっかくだから別にする。


* Entry → ブログのメインモデル
* Tag → ブログに限らず使える


* 必要なPYTHONPATHを通す


  システムのPYTHONPATHか、自分のPYTHONPATHを通す。
  
  Windows
  ::
  
    > set PYTHONPATH=%PYTHONPATH%;C:¥¥hackathon_handson
  
  bash
  ::
  
    $ export PYTHONPATH=$PYTHONPATH:/home/hoge/hackathon_handson


* プロジェクトを作る


  ::
  
    django-admin.py startproject hackathon


* アプリケーションを二つ作る（PYTHONPATHを通したディレクトリ直下に作る）


  プロジェクトの直下ではなく、他の場所に作ってみる。名前は他とかぶらないものにした方が良い。とりあえず駄目な名前を付ける。
  ::
  
    django-admin.py startapp blog
    django-admin.py startapp tags


* settings.pyに最低限の設定をする


  データベースの設定
  ::
  
    import os
    BASE_DIR = os.path.dirname(os.path.abspath(__file__))
    DATABASE_ENGINE = 'sqlite3'
    DATABASE_NAME = os.path.join(BASE_DIR, 'data.sqlite3')


  アプリケーションの設定
  ::
  
    INSTALLED_APPS = (
    #元から書いてあるもの
      'blog',
      'tags',
    )
  
  タイムゾーンを日本にする
  ::
  
    TIME_ZONE = 'Japan'


* テーブルを作る


  syncdbする。スーパーユーザは作っておく
  ::
  
    $ chmod 755 ./manage.py
    $ ./manage.py syncdb
  


モデルの扱いに慣れる
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* tags/models.pyにTagクラスを、blog/models.pyにEntryを記述する。

  * ASCII以外の文字をスクリプトファイルに書く場合にはエンコーディングの指定を忘れないこと。ファイルのエンコーディングはutf-8にする。
    ::
    
      # encoding:utf-8
  
  * ForeignKeyで指定しているモデルのインポートを忘れずにする。Entryモデルは、公開日のデフォルトとして現在日時を使うのでdatetime.datetimeのインポートも忘れずに。
    ::
    
      #tags/models.py
      from django.contrib.auth.models import User
    
      #blog/models.py
      from django.contrib.auth.models import User
      from tags.models import Tag
      from datetime import datetime

  * プロジェクトの設定を持ったままインタラクティブシェルを起動する。
    ::
    
      $ ./manage.py shell
      >>>

  * データ操作するためのモデルをインポートする。
    ::
    
      >>> from blog.models import Entry
      >>> from tags.models import Tag
      >>> from django.contrib.auth.models import User

  * スーパーユーザを取得しておく
    ::
    
      >>> spruser = User.objects.all()[0]

  * エントリを登録してみる。
    ::
    
      >>> from datetime import datetime
      >>> ent = Entry(title=u'Test Entry', body=u'Entry Body. Test, Test, Test', pub_date=datetime.now())
      >>> ent.author = spruser
      >>> ent.save()

  * データベースに保存されたエントリを取り出してみる
    ::
    
      >>> db_ent = Entry.objects.get(pk=1)
      >>> print db_ent.title
      Test Entry

  * タグを登録してみる。ForeignKey（author）に値を設定する方法
    ::
    
      #fkを表すフィールドにUserインスタンスを設定
      >>> tg1 = Tag(name=u'Test Tag1', user=spruser)
      >>> tg1.save()
      
      #fk_idにUserインスタンスのpkを設定
      >>> tg2 = Tag(name=u'Test Tag2', user_id=spruser.id)
      >>> tg2.save()
      
      #インスタンスのfkを表すフィールドにUserインスタンスを設定
      >>> tg3 = Tag(name=u'Test Tag3')
      >>> tg3.user = spruser 
      >>> tg3.save()

  * エントリにタグを設定してみる。
    ::
    
      >>> ent.tags.add(tg1)
      >>> ent.tags.all()
      [<Tag: Tag object>]

  * エントリからタグを取り除く
    ::
    
      >>> ent.tags = []
      >>> ent.tags.all()
      []

  * エントリに複数のタグを一度に設定する
    ::
    
      >>> ent.tags.add(tg1, tg2)
      >>> ent.tags.all()
      [<Tag: Tag object>, <Tag: Tag object>]

  * エントリに複数のタグを一度に設定する（代入）
    ::
    
      >>> ent.tags.clear() #これでもタグの設定を消せる
      >>> ent.tags.all()
      >>> ent.tags = [tg1,tg2]
      >>> ent.tags.all()
  
遅延評価とキャッシュを理解する
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* SQLをデバッグアウトするために、下準備をする

  * eggでインストールしていなければ、django.db.backends.utilのCursorDebugWrapperのexecuteでsqlをprintする。
  * eggでインストールしている場合には、django.db.connection.queriesを都度デバッグアウトする。

* 一度参照したFKはキャッシュされる
  ::
  
    >>> db_ent.author
    #SQL
    <User: hoge>
    >>> db_ent.author
    <User: hoge>

* managerを使ってQuerysetを生成・評価すると毎回SQLが発行される。毎回新しいQuerysetが生成されるため。
  ::
  
    >>> db_ent.tags.all()
    #SQL
    [<Tag: Tag object>, <Tag: Tag object>]
    >>> db_ent.tags.all() #
    #SQL
    [<Tag: Tag object>, <Tag: Tag object>]

* Querysetは評価されたタイミングでSQLが発行され、一度評価されたQuerysetは再度評価されない
  ::
  
    >>> query = db_ent.tags.all()
    >>> query #Querysetを評価した時点でSQLが発行される
    #SQL
    [<Tag: Tag object>, <Tag: Tag object>]
    >>> query #一度評価したQuerysetは再度評価されない
    [<Tag: Tag object>, <Tag: Tag object>]

* 一度評価されたQuerysetも結果がキャッシュされているだけで、通常のQuerysetのまま
  ::
  
    #一度評価したQuerysetのfilterを呼ぶと、きちんと新しいQuerysetが生成される。
    >>> x = query.filter(pk=1)
    #つまり、評価すると正しい条件のついたSQLを発行する
    >>> x
    #SQL
    [<Tag: Tag object>]
    #一度評価したQuerysetのfilterを呼び出す。
    #再度Queryset評価しても、何もなかったかのように振る舞う。
    >>> query
    [<Tag: Tag object>, <Tag: Tag object>]

Djangoの必修(BASE)
-------------------------------------------------------------------------

Adminを使う
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* URLの設定

  Adminを使うため、hackathon/urls.pyのコメントアウトされている部分を外す。
  ::
  
    # Uncomment the next two lines to enable the admin:
    from django.contrib import admin
    admin.autodiscover()
    ....
      (r'^admin/(.*)', admin.site.root),

* Adminをインストールする

  hackathon/settings.pyのINSTALLED_APPSに次の行を追加
  ::
  
    'django.contrib.admin',
  
  データベースにテーブルを作る
  ::
  
    ./manage.py syncdb

* 開発サーバを起動する
  ::
  
    ./manage.py runserver
  
  起動したら、http://localhost:8000/admin/をブラウザで開いてログインする。

* Adminでまずすること

  * Sitesの設定を変更する
  
    ドメイン名にlocalhost:8000、表示名にdevelopmentと入力して保存。
  
  * グループを作成する
  
    Bloggerという名前で、blogとtagに権限を付与する。権限リストは動的に絞り込める。
    
    .. image:: images/create_group.png
  
  * ユーザを作成する
  
    今後のために2つ作成する。スタッフ権限にチェックを入れて、Bloggerグループに所属させる。
    
    .. image:: images/user_list.png

* EntryとTagをAdminに表示されるようにする。

  * admin.pyの追加
  
    tagsとblogにadmin.pyというファイルを作成して、Adminで使うモデルとしてAdminFormを登録する
    ::
    
      #tags/admin.py
      from django.contrib import admin
      from tags.models import Tag
      
      admin.site.register(Tag, admin.ModelAdmin)
      
      #blog/admin.py
      from django.contrib import admin
      from blog.models import Entry
      
      admin.site.register(Entry, admin.ModelAdmin)
  
  スーパーユーザでログインしているので、一度ログアウトしてBloggerグループのユーザでログインし直す。
  
  .. image:: images/blogger_admin_page.png

* モデルのデータ一覧で表示される項目を変更する

  Entryモデルの一覧を表示してみると、悲しい一覧が見えるはず。
  
  .. image:: images/sad_entry_list.png
  
  * admin.ModelAdminを継承したカスタムフォームを作成する
    ::
    
      #blog/admin.py
      class EntryModelAdmin(admin.ModelAdmin):
        list_display = ['title', 'author', 'pub_date']
      
      admin.site.register(Entry, EntryModelAdmin)
    
    幸せな一覧になった？
    
    list_displayにフィールド名をリストで設定すると一覧の表示をカスタマイズできます。
    
    .. image:: images/happy_entry_list.png
  
  * オブジェクトの自己表現を変更する
  
    **しかし！** 編集画面を表示すると、ManyToManyが酷いことになっています。
    
    .. image:: images/sad_object_repr.png
    
    関連の値は、関連のインスタンスを文字列表現にしたものを表示しています。
    
    文字列表現を操るため、Tagモデルに **__unicode__** メソッドを追加します。
    ::
    
      #tags/models.pyのTagクラスに以下を追加
        def __unicode__(self):
          return u'%s(%s)' % (self.name, self.user)
    
    ちょっと幸せになった？
    
    .. image:: images/happy_object_repr.png
    
    ついでに、Tagの一覧を表示してみると、同様の表記に変わっているはずです。
  
  * 編集画面のフィールド並び順を変更する
  
    最近のネットブックは画面の縦方向が異常に短いですよね。
    
    編集画面はモデルのフィールドが順番に縦に並んでいるだけなので、少し並べかえてみましょう。
    また、公開日はデフォルトのママにする可能性が高いので、普段は目に入らないようにしておきましょう。
    
    EntryModelAdminのlist_displayに続いてfieldsetsを追加します
    ::
    
      #blog/admin.py
      fieldsets = (
          ('Core Information', {
            'fields': (('title', 'author'), 'body',)
            }),
          ('Options', {
            'classes': ['collapse',],
            'fields': (('pub_date', 'tags'), )
            })
      )
    
    fieldsetsはフィールドの表示を制御します。
    
    とりあえずすっきりしました。
    
    .. image:: images/admin_fieldsets.png
    
    オプションは、クリックすると開きます。
    
    .. image:: images/admin_fieldsets_open.png
    
  * 一覧画面をごっちゃりする
  
    一覧といえば絞り込みですよね。
    
    .. image:: images/admin_more.png
    
    * list_filter
    
      list_filterにフィールド名をリストで設定すると一覧の右に絞り込み機能がつきます。
      
      指定できるフィールドはBooleanField、ForeignKeyやManyToManyFieldです。
    
    * date_hierarchy
    
      date_hierarchyに日付型のフィールド名を設定すると、リスト上部に日付での絞り込み機能がつきます。
      
      絞り込みは、年→年月→年月日で順に絞れます。また、絞り込みの候補にはデータの存在する対象しか出ません。
    
    * search_fields
    
      search_fieldsにフィールと名をリストで設定すると文字列検索機能がつきます。
  
  * ManyToManyFieldの表示をUserの権限リストのようにしてみる
  
    候補の数が増えてくるとどれを選択したのかわからなくなってきてしまいます。
    
    そもそも選択自体に困難が伴うこともあります。
    ::
    
      filter_horizontal = ('tags',)
    
    .. image:: images/happy_tags.png
      :scale: 70

  ここまでで、blog/admin.pyは次のようになりました。
  ::
  
    class EntryModelAdmin(admin.ModelAdmin):
      list_display = ['title', 'author', 'pub_date']
      fieldsets = (
          ('Core Information', {
            'fields': (('title', 'author'), 'body',)
            }),
          ('Options', {
            'classes': ['collapse',],
            'fields': (('pub_date', 'tags'), )
            })
      )
      list_filter = ['author', 'tags',]
      date_hierarchy = 'pub_date'
      search_fields = ('title, body',)
      filter_horizontal = ('tags',)

* Adminのラベルを日本語に切り替える

  Adminのみではなく、Djangoの国際化されている文字列が全ての日本語で表示されます。
  ::
  
    LANGUAGE_CODE = 'ja'


テンプレート
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
opendesignからもってきたテンプレートを使います。

* http://www.opendesigns.org/preview/?template=1182

  .. image:: images/template_sample.png
    :scale: 50

* 画面の各要素がブロックがどのページに表示されるべきかを検討する

  * 全ての画面に必要なもの
  
    .. image:: images/template_everypage.png
      :scale: 50
  
  * トップページにだけ必要なもの
  
    .. image:: images/template_toppage.png
      :scale: 50
  
  * 各ページで内容の変わるもの
  
    .. image:: images/template_content.png
      :scale: 50

* Djangoのテンプレートを使う場合の定石に従ってテンプレートを構成する

 * 定石1
 
   アプリケーションのモデル一覧・詳細はアプリケーションディレクトリに配備する
   
   命名規則: 一覧 → APP/MODEL_list.html 、 詳細 → APP/MODEL_detail.html
   
   アプリケーションディレクトリ直下のtemplatesディレクトリがデフォルトでテンプレート格納ディレクトリになる。
   blogディレクトリ直下にtemplates/blogというディレクトリを作成する（templatesを作ってその中にblogを作る）
   
   **Entryモデルの一覧用** blog/templates/blog/entry_list.html
   
   **Entryモデルの章採用** blog/templates/blog/entry_detail.html
 
 * 定石2
 
   各テンプレートは同一階層のbase.htmlを継承し、base.htmlは上位階層のbase.htmlを継承する。

 * 定石3
 
   プロジェクトのテンプレートディレクトリを用意し、base.htmlを作成する
 
* 実際の階層と、最初の状態は次のようになる

   ::
   
     #階層
     + hackathon
       + templates
          - base.html
     + blog
       + templates
         + blog
            - base.html
            - entry_list.html
            - entry_detail.html
     
     #blog/base.html
     {% extends 'base.html' %}
     
     #blog/entry_list.html
     {% extends 'blog/base.html' %}
     
     #entry_detail.html
     {% extends 'blog/entry_detail.html %}

* はやる気持ちを抑えつつ、静的ファイルの配信を準備する

  どこかにstaticという名前のディレクトリを作ってその中にstyle.cssとimagesを放り込む。
  
  次に、staticディレクトリ以下へのアクセスをdjango.views.static.serveに処理させる設定をプロジェクトのurls.pyに追加する。
  ::
  
    (r'^static/(?P<path>.*)$', 'django.views.static.serve', {'document_root': '/path/to/static'}),
  
* プロジェクトのbase.htmlにindex.htmlテンプレートの中身をコピーする

  * imagesという文字列の前に {{ MEDIA_URL }} という文字列を記述する
  
  * styles.cssの前に {{ MEDIA_URL }} という文字列を記述する
  
  * settings.pyのMEDIA_URLの設定を '/static/' に変更する
  
    ※ MEDIA_URLはContextProcessorsがテンプレートに渡してくれます。
    
    現在設定されているContextProcessorsを確認するには
    ::
    
      $ ./manage.py shell
      >>> from django.conf import settings
      >>> settings.TEMPLATE_CONTEXT_PROCESSORS
      ('django.core.context_processors.auth', 'django.core.context_processors.debug', 
       'django.core.context_processors.i18n', 'django.core.context_processors.media')
    
    http://code.djangoproject.com/browser/django/trunk/django/core/context_processors.py
    ::
    
      def media(request):
          """
          Adds media-related context variables to the context.
          """
          return {'MEDIA_URL': settings.MEDIA_URL}
    
    どのページでも必要な情報を渡すのに便利。取得のコストが高いものはキャッシュを使っても良いね。

* プロジェクトテンプレートのbase.htmlにブロックを定義してゆく

  * 基本的なブロック
  
    * HTMLのheadを囲むように head という名前のブロック
    
      * headの中のtitleタグ内に title という名前のブロック
      * headの終わりに extrahead という名前のブロック
    
    * footerが書いてあるdivを囲むように footer という名前のブロック
    * メインコンテンツが書いてあるdivを囲むように content という名前のブロック
  
  * プラスアルファで必要なブロック
  
    * トップにのみ表示する画像を置く部分に gallery という名前のブロック


実習
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* トップページの表示

  / へのアクセスに対して、汎用ビューでEntryデータを20件表示する
  
  *ヒント* django.views.generic.date_based.archive_index

* ユーザ毎一覧ページの表示

 /USER/ へのアクセスに対して、汎用ビューをラップてユーザのEntryデータを20件表示する
 
 *ヒント* django.views.generic.date_based.archive_index か、django.views.generic.list_detail.object_list
 
 *ヒント* archive_indexの場合は、テンプレート名はAPP/MODEL_archive.html
 
 *ヒント* month_format='%m'
 
 ギャラリーのブロックを非表示にしてみる

 余力があったらページングしてみる

* エントリ詳細ページの表示

 /USER/YEAR/MONTH/DAY/ID/ へのアクセスに対して、対象の日付の対象のデータのEntryデータを1件表示する
 
 *ヒント* django.views.generic.date_based.object_detail
 
 *ヒント* month_format='%m'

発展
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* 404/500ページを設定して、実際に表示させてみる（表示される条件を学ぶ）
* Commentフレームワーク(django.contrib.comments)を使ってエントリにコメントできるようにする

  * コメントが追加されたらメールをエントリの作者に送るようにする
  
    * コメントにコメントできるようにする
  
  * Akismetを使ってコメントスパムを防ぐ

* 写真をアップできるようにする

  * トップページに最新の3枚を表示する
  
    * 写真を四角に切り取って、サイズもトップページ用に変換する
  
  * IDEFを保存できるようにしてみる

* プロフィールを登録できるようにする

  * アイコンをアップロードできるようにする
  
* Google Sitemapsを出力する
* テストを書く
* 公開してみる

  * CGI/FastCGI/mod_python/mod_wsgi

あとは好きにしてくれ