Web アプリケーションでは非常に一般的に、フォームやその他のユーザーインプットのプロセスの後、ユーザーに向けて一過性の通知メッセージ ("フラッシュメッセージ" とも言われます) を表示する必要があります。
\nDjango は、anonymous および認証済みユーザーの両方に対して、Cookie とセッションをベースにしたメッセージングを完全にサポートしています。このメッセージフレームワークは、一時的に一つのリクエスト内にメッセージを保管し、その後のリクエスト (通常、直後のリクエスト) 内で表示するために、これらを検索することを可能にします。全てのメッセージは、優先順位 (たとえば info、warning、error) を決定づける特定の level でタグづけされます。
メッセージは、 ミドルウェア クラスと、それに対応する コンテキストプロセッサー を通して実行されます。
\ndjango-admin startproject によって生成されたデフォルトの settings.py は、メッセージ機能を有効にするために必要な設定を全て含んでいます:
'django.contrib.messages' は、INSTALLED_APPS の中にあります。
MIDDLEWARE は 'django.contrib.sessions.middleware.SessionMiddleware' と 'django.contrib.messages.middleware.MessageMiddleware' を含みます。
デフォルトの ストレージバックエンド は sessions に依存します。そのため SessionMiddleware を有効にして、 MIDDLEWARE 内で MessageMiddleware より前に記述する必要があります。
TEMPLATES 設定で定義した DjangoTemplates バックエンドの 'context_processors' オプションは、'django.contrib.messages.context_processors.messages' を含みます。
メッセージを使いたくない場合は、INSTALLED_APPS から 'django.contrib.messages' を、MIDDLEWARE から MessageMiddleware 行を、そして TEMPLATES から messages コンテキストプロセッサーを削除できます。
メッセージフレームワークは、一時的なメッセージを保管するために、異なるバックエンドを使うことができます。
\nDjango は、django.contrib.messages の中で、以下の3つのビルトインのストレージクラスを提供しています:
このクラスは、すべてのメッセージをリクエストのセッション内部に保管します。ゆえに、Django の contrib.sessions アプリケーションが必要となります。
このクラスは、複数のリクエストにわたって通知を保持するために、Cookie (改ざんを防ぐため秘密のハッシュで署名されます) にメッセージデータを保管します。古いメッセージは Cookie データのサイズが 2048 バイトを超えると破棄されます。
\nこのクラスは、まず CookieStorage を使い、単一の Cookie に合わないメッセージに対して SessionStorage を使います。Django の contrib.sessions アプリケーションも必要となります。
この動作は、可能な限りセッションへの書き込みを避けます。一般的なケースでは最高のパフォーマンスを提供するはずです。
\nFallbackStorage はデフォルトのストレージクラスです。もしあなたのニーズに合わないときは、MESSAGE_STORAGE を完全な import パスに設定することで他のストレージクラスを選べます。次に例を示します。
MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"\n独自のストレージクラスに書き込むためには、 django.contrib.messages.storage.base 内の BaseStorage クラスをサブクラス化して、 _get と _store メソッドを実装してください。
メッセージフレームワークは、Python ロギングモジュールに似た、設定可能なレベルアーキテクチャに基づきます。メッセージレベルは、タイプによるグループメッセージを可能にします。これにより、ビューやテンプレートの中で異なるフィルタおよび表示ができるようになります。
\ndjango.contrib.messages から直接インポートできるビルトインのレベルは以下の通りです:
定数 | \n目的 | \n
|---|---|
| \nプロダクション環境では無視 (ないし削除) される、開発に関連したメッセージ | \n
| \nユーザーに何か情報を伝えるメッセージ | \n
| \nあるアクションが成功した、例えば "あなたのプロフィールは無事に更新されました" | \n
| \n問題は起きなかったが、問題になり得る | \n
| \nあるアクションが成功 しなかった か、他の問題が発生した | \n
MESSAGE_LEVEL 設定は、最小限の記録されたレベルを変更するため (もしくは リクエストごとに変更 するため)に使うことができます。これ以下のレベルのメッセージを追加しようとしても無視されます。
メッセージを付与するには、以下を呼び出してください:
\nfrom django.contrib import messages\n\nmessages.add_message(request, messages.INFO, "Hello world.")\nいくつかのショートカットメソッドは、一般的に使われるタグ (通常、メッセージのHTMLクラスとして表されます) とともにメッセージを付与する標準的な方法を提供します:
\nmessages.debug(request, "%s SQL statements were executed." % count)\nmessages.info(request, "Three credits remain in your account.")\nmessages.success(request, "Profile details updated.")\nmessages.warning(request, "Your account expires in three days.")\nmessages.error(request, "Document deleted.")\nテンプレート では、次のようなものを使ってください:
\n{% if messages %}\n<ul class="messages">\n {% for message in messages %}\n <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>\n {% endfor %}\n</ul>\n{% endif %}\nコンテキストプロセッサーを使っている場合、テンプレートは RequestContext でレンダリングされる必要があります。もしくは、 messages をテンプレートコンテキストに対して有効にしてください。
メッセージが一つしかないとわかっている場合でも、 messages 配列をイテレートする必要があります。そうしないとメッセージストレージは次のリクエストのためにクリアされないからです。
コンテキストプロセッサーは、メッセージレベルの名前と数値を対応付ける DEFAULT_MESSAGE_LEVELS 変数も提供します:
{% if messages %}\n<ul class="messages">\n {% for message in messages %}\n <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>\n {% if message.level == DEFAULT_MESSAGE_LEVELS.ERROR %}Important: {% endif %}\n {{ message }}\n </li>\n {% endfor %}\n</ul>\n{% endif %}\nテンプレート以外では、 get_messages() を使うことができます:
from django.contrib.messages import get_messages\n\nstorage = get_messages(request)\nfor message in storage:\n do_something_with_the_message(message)\nたとえば、すべてのメッセージを取得して、TemplateResponseMixin の代わりに JSONResponseMixin で返すことができます。
get_messages() は設定されたストレージバックエンドのインスタンスを返します。
Message クラスLink to this heading#テンプレート内のメッセージのリストをループさせると、 Message クラスのインスタンスが得られます。これらのインスタンスにはいくつかの属性しかありません:
message: メッセージの実際のテキストです。
level: メッセージのタイプを説明する数値です (詳細は上述の message levels セクション)。
tags: スペースによって区切られた、全てのメッセージのタグを結合する文字列 (extra_tags と level_tag) です。
extra_tags: スペースによって区切られた、メッセージのカスタムタグを含む文字列です。空がデフォルトです。
level_tag: レベルを表す文字列です。デフォルトでは定数名の小文字バージョンですが、MESSAGE_TAGS 設定によって変更できます。
メッセージレベルは実際には単なる整数なので、独自のレベル定数を定義して、よりカスタマイズされたユーザーフィードバックを作成できます。次に例を示します。
\nCRITICAL = 50\n\n\ndef my_view(request):\n messages.add_message(request, CRITICAL, "A serious error occurred.")\n独自のメッセージレベルを作成するときには、既存のレベルを上書きしないように気をつけてください。ビルトインのレベルで使われている値は以下の通りです:
\nレベル定数 | \n値 | \n
|---|---|
| \n10 | \n
| \n20 | \n
| \n25 | \n
| \n30 | \n
| \n40 | \n
HTML や CSS の中で独自のレベルを指定する必要がある場合は、MESSAGE_TAGS 設定を通してマップを提供する必要があります。
最小記録レベルは、set_level メソッドを使用してリクエストごとに設定できます。
from django.contrib import messages\n\n# Change the messages level to ensure the debug message is added.\nmessages.set_level(request, messages.DEBUG)\nmessages.debug(request, "Test message...")\n\n# In another request, record only messages with a level of WARNING and higher\nmessages.set_level(request, messages.WARNING)\nmessages.success(request, "Your profile was updated.") # ignored\nmessages.warning(request, "Your account is about to expire.") # recorded\n\n# Set the messages level back to default.\nmessages.set_level(request, None)\n同様に、現在の有効レベルは get_level を使って取得できます。
from django.contrib import messages\n\ncurrent_level = messages.get_level(request)\n最小記録レベルが機能する仕組みについての詳細は、上記の Message levels を参照してください。
\n再利用可能なアプリ (または他のコード) を書いており、メッセージング機能を含めたいが、利用者に無理に有効化させたくない場合は、任意の add_message ファミリーのメソッドに fail_silently=True という追加のキーワード引数を渡すことができます。たとえば:
messages.add_message(\n request,\n messages.SUCCESS,\n "Profile details updated.",\n fail_silently=True,\n)\nmessages.info(request, "Hello world.", fail_silently=True)\nFormView をベースにしたクラスに、成功メッセージ属性を追加します。
cleaned_data はフォームからのクリーンなデータであり、文字列フォーマットに使用されます。
Example views.py:
\nfrom django.contrib.messages.views import SuccessMessageMixin\nfrom django.views.generic.edit import CreateView\nfrom myapp.models import Author\n\n\nclass AuthorCreateView(SuccessMessageMixin, CreateView):\n model = Author\n success_url = "/success/"\n success_message = "%(name)s was created successfully"\nform からのクリーン済みデータは、 %(field_name)s 構文を使用して文字列補完に利用できます。ModelForms の場合、保存された object からフィールドにアクセスが必要な場合は、 get_success_message() メソッドをオーバーライドしてください。
ModelForms 用の views.py の例:
\nfrom django.contrib.messages.views import SuccessMessageMixin\nfrom django.views.generic.edit import CreateView\nfrom myapp.models import ComplicatedModel\n\n\nclass ComplicatedCreateView(SuccessMessageMixin, CreateView):\n model = ComplicatedModel\n success_url = "/success/"\n success_message = "%(calculated_field)s was created successfully"\n\n def get_success_message(self, cleaned_data):\n return self.success_message % dict(\n cleaned_data,\n calculated_field=self.object.calculated_field,\n )\nメッセージは、ストレージインスタンスがイテレートされる際にクリアされるようにマークされています (そして、応答が処理される際にもクリアされます)。
\nメッセージがクリアされるのを避けるために、イテレートの後にメッセージストレージを False に設定できます:
storage = messages.get_messages(request)\nfor message in storage:\n do_something_with(message)\nstorage.used = False\nクッキー (そしてセッション) の仕組みから、同じクライアントが複数の要求を並行して行い、メッセージを設定または取得する場合、クッキーやセッションを使用するバックエンドの動作は定義されていません。たとえば、クライアントが1つのウィンドウ (またはタブ) でメッセージを作成する要求を開始し、別のウィンドウで未読メッセージを取得する要求を開始するとき、最初のウィンドウがリダイレクトされる前に、そのメッセージが最初ではなく、代わりに2番目のウィンドウに表示されることがあります。
\n要するに、同じクライアントからの複数の同時リクエストが関わると、メッセージがそれらを作成した同じウィンドウに必ず届くわけではなく、場合によっては全く届かないことがあります。ほとんどのアプリケーションでは通常問題とならず、HTML5では各ウィンドウ/タブが独自の閲覧コンテキストを持つため、これは問題にならなくなります。
\nいくつかの 設定 を使用して、メッセージの動作を制御できます。
\n\nCookiesを使用するバックエンドでは、Cookieの設定はセッションCookieの設定から取得されます。
\n\nこのモジュールは、HttpResponse に添付されたメッセージをテストするためのカスタマイズされたテストアサーションメソッドを提供しています。
このアサーションを利用するには、クラス階層に MessagesTestMixin を追加してください。
from django.contrib.messages.test import MessagesTestMixin\nfrom django.test import TestCase\n\n\nclass MsgTestCase(MessagesTestMixin, TestCase):\n pass\n次に、テストで MsgTestCase を継承してください。
response に追加された messages が expected_messages と一致することをアサートします。
expected_messages は Message オブジェクトのリストです。
デフォルトでは、比較は順序に依存します。これを無効にするには、 ordered 引数を False に設定します。