Django Tutorial Proposal

django-tutorial-proposal.txt

TITLE: 手把手學 Django

Django 是什麼？
	Short Version (不是一節)
	Python
	Django 的歷史
	現在的 Django
	我應該學 Django 嗎？
	先行技能
		Command line 使用技能
		基本的 Python 與 HTML 知識 -- 可以邊學邊補充
		Git/Mercurial (至少從現在開始學!)
	其他資源
		Codedata (for Python)
		Official documentation

建立開發環境
	開發環境 != 部屬環境
		盡量讓兩者相符, 但不要無限上綱
	初學者建議 Linux, 習慣 OS X 就繼續使用, 如果你懂 Python 和 C compiler, Windows 也行！
	Django 只是一個 Python 套件
		輔助工具不一定如此
	開發環境建制
		共通概念
			virtualenv + virtualenvwrapper
			pip
				pip vs easy_install
			C modules
		Linux
		OS X
		Windows
	
Hello, Django! (良葛格風格)
	Let's Do It!
		mkvirtualenv hellodjango
		pip install django
		django-admin.py startproject hellodjango
		Edit (new file) hellodjango/views.py
		Edit hellodjango/urls.py
		python manage.py runserver
		Visit localhost:8000 in browser
		Ctrl+c
		我到底做了什麼？
			一個 Django 專案！
			馬上就會解釋前面的步驟
	django-admin.py
	startproject
	Project template, 以及裡面的東西
		1.5 修改了預設的模板結構, 不過該有的都會在
		settings.py
			先不要教 TSOD-style, 等講 production 時再說明
			簡介就好, 先不要講裡面東西的詳細意義
		manage.py
			django-admin.py 的 wrapper
			在 Un*x-system 上可以 chmod +x
			Windows -- manage.py.bat
		其他檔案
			__init__.py
				為什麼專案 root 不是 Python module？
					因為不能是！
			urls.py
			wsgi.py
		startproject --template
			我們在這個教學中都會用內建的, 不會自訂 template
	startapp
		Django app 是什麼東西
		其實 hellodjango/hellodjango 本身也是一個 app
		下一章馬上會用到
		
Model—Template—View
	簡介
	每一個 Django app (除了專案同名 app 之外) 都可以有獨立的架構
	把  hellodjango 模組化
		新建一個 hello app
			tests.py 與 models.py...先不要管它們, 不過不用刪掉
			INSTALLED_APPS
		把 views.py 與 urls.py 移出 hellodjango
			同名 app 通常只會用來放專案 global 的資料
		用 render 與 template 重寫 views.py
			有時候 HttpResponse 還是頗方便, 不過...
				Content-Type header
				HTML escaping
			還有一個 render_to_response, 不過目前用 render 就好
			render 還有其他功能！...以後再說			
		進行重寫...
	簡述 template 目錄結構
		TEMPLATE_LOADERS 與 TEMPLATE_DIRS
			filesystem.Loader 與 app_directories.Loader
	
你的第一個 Model
	重造輪子來當示範：你的個人網站
		Blog
		Static pages
		Forum
	django-admin.py startproject mysite
		BTW, 如果你想把剛剛的 hellodjango 刪掉...
	設定 database
		為了演示方便, 我們會用 SQLite, 不過如果你未來想要把這個 project 上線, 請不要這樣做
		除了 SQLite 的資料庫都需要 C binding, 請參見開發環境建立的章節
		settings.DATABASES
			注意是複數
		SQLite
			Django 內建 (基於 Python 的內建模組), 不用裝任何東西
			設定範例
		PostgreSQL
			Django 官方推薦
			libpostgres 與 psycopg2
			設定範例
		MariaDB 與 MySQL
			等等, 我聽過 MySQL, MariaDB 是什麼鬼？
			libmysql 與 MySQLdb
			Python 3
			設定範例
		Oracle 與其他非官方方案
	基本的 model
		Forum "Topic"
		(刻意忽略 comments 與文章作者的問題, 以後再帶出作法)
	實作 models
		django-admin.py startapp forum
			怎麼幫你的 app 取名
				App 名稱必須 *unique*！注意這包括 Django 內建的 apps
		class Topic
			CharField
			隱性 AutoField "id"
			TextField
			DateTimeField
				DateField
				時區, Python datetime, 以及資料庫型態
				auto_now 與 auto_now_add
					MySQL TIMESTAMP
						再論時區
			class Meta
				ordering, get_latest_by 與 order_with_respect_to
		其他內建欄位與 Meta options
			可以自己寫新的 field type (不過不教)
			Meta options 簡介就好, 大部分很少用到; verbose name 系列後述
			(先不提 contrib 裡面的東西, ManyToManyField 稍微講就好, 後面詳述)
	測試
		為什麼要測試
		Testing DB != 真正的資料！
			Django fixtures, dumpdata 與 loaddata
		寫一個測試 auto_now_add 與 get_latest_by 的 testcase
	manage.py syncdb
		建立 user 的提示...先不要 (後述)

View 負責擔任 Model 與 Template 之間的橋樑
	先寫出來給你看 (function based, 不過先不要講這個名詞, 實作就對了)
		def topic_list(request)
		def topic_detail(request, id)
	Model.objects
		Model Managers
	filter, exclude, get, 以及變種
		get 的例外
		get_object_or_404 與 get_list_or_404
			其實我沒有很喜歡, 不過要不要用是自由
	QuerySet 與 Manager 的關聯
		objects.all() 與 interface exposure
	雙底線語法
		exact
		
Template 負責把 View 傳出來的東西顯示成正確的格式
	Context 是 dict-like object
	先做兩個 templates 來看看 (先不用做的太完整, 有 HTML 格式就好了)
	Template syntax
		Tag
		Filter
		Variable
		"Dot" for key-value, index, method call, and attribute
			Auto type conversion
				None and ''
		{% url %} tag
	在 view 的 arguments 最後直接放上 template 檔名
		個人風格, 喜不喜歡隨你
	Template 繼承 (完整的 HTML best practice)
		blocks
	(先完全不要用到 tags, filters [除了 for 之類] 以及 static files 等等)
	Django template 超級簡單
		簡單與簡陋只是一線之隔
		替代品 (最後說明其實通常你通常不需要)

URLConf 負責把 URL 對應到正確的 view
	怎麼傳參數 -- positional args 與 keyword args
	URL naming
		namespace "blog"
	Model.get_absolute_url
		舊寫法 (permalink decorator)
		新寫法 (reverse function)
		namespace 怎麼加
	"include"
	跑起來看看！
		空無一物XD
		從 manage.py shell 新增一篇留言
			也太不方便
			所以我們來做一個可以新增留言的界面

Forms
	HTML 表單與 Django 表單
	Django 表單比較接近 View 的角色, 是 template 和 model 的中介
	def TopicForm(forms.Form)
		Model form
		Form factory 與其優缺點
	為這個 form 新增一個 view, 一個 url, 一個 template
	跑起來看看！
	
Authentication
	"contrib"
	@login_required
	manage.py createsuperuser
		還記得 syncdb 的時候 Django 有問你一個問題嗎？
		manage.py createsuperuser
			User vs staff (aka admin) vs superuser
	登入與登出
		settings.LOGIN_URL/LOGOUT_URL 與內建的 url/view/form/template
			通通可以 override
			URLConf 要自己加 :~
		其他有趣(?)的 authentication views
		class AnonymousUser
	在 view 與 template 中取得認證狀態

Model Relation
	class Reply:
		topic = ForeignKey(Topic)
		content
		created_at
	Model relation 與 Django 的 relation fields
		Topic-Reply UML
		為什麼 Django 要自動幫 model 建立 id
		多對一與多對多
		一對一：多對一的特例
		一對多？(RDB 的限制)
	在 view 中取出 replies
		另一種寫法：related_name
			是否要用預設的 _set 是 coding style, 我個人不愛, 而且喜歡明確寫出
			Refactor 起來很要命
			隱含的 database fetch 可能成為效能分析的地雷
			
Forms, part 2
	實作 Reply form
		Relation form fields
	自動 assign topic ID
		Form prepopulation 與 HiddenInput
			Field 與 widget
			Widget overriding
				Custom form
				After initialization
				In factories
		Form.save, commit=False 與 Form.save_relation
			Field inclusion and exclusion (Don't exclude!)
			
為 Topic 和 Reply 增加 author 欄位
	get_user_model()
	Schema migration: South
		Django 的第三方套件
		(講 south 應該可以輕鬆填滿一整章...)
		--auto 支援的類型：add 與 remove (不包括 move!)
		convert_to_south
		Django 1.7
		

開放一般使用者註冊; user avatar
	(參考 The Django Book - Chapter 14 - Handling Registration)
		Custom form-posting view
	auth.User 與 auth.Permission
		Superuser is god
		@permission_required
	Custom user model
		完全複寫 Django 的 model
			Django 1.5 開始支援
			可以完全複寫 Django 的 authentication method
			為了示範, 我們這裡會用這個方法, 雖然我們其實不需要
		另一種作法 -- 增加 profile model
			Django 1.4 之前有 built-in profile model, 1.5 開始 deprecated
			可是不管怎樣, 你還是可以自己做一個, 沒人會阻止你 (OneToOneField)
	FileField 與 ImageField: 特殊的 fields
		MEDIA_URL 與 MEDIA_ROOT
		如何測試 file fields
		
Admin Site
	修改 URLConf 和 settings
	Magic!
	contrib.admin 是基於 contrib.auth
	為 Topic 和 Reply 增加 admin
		Model fields 的 verbose_name 和 help_text
		Model meta 的 verbose_name 和 verbose_name_plural
		ugettext 與 ugettext_lazy
			先不用解釋 i18n 設定, 反正照做就對了
	Admin customization
		list_display
		list_display_links
		list_editable
		還有很多！慢慢介紹

美化你的 template
	Static files
		STATIC_URL, STATIC_URL
		STATICFILES_DIRS 與 STATICFILES_FINDERS
			AppDirectoriesFinder
		{% static %} tag
	Form layout
		as_p 與 as_table
		Custom layout
			{% csrf_token %}
				簡述 CSRF 與這個 token 的作用
		field errors 與 non-field errors
	Filters
		Date time formatting
	Paginator
		In views
		參考 Mezzanine 的版本用 template tag 來簡化流程

Blog
	class Post
	No more syncdb, use schemamigration --initial
	HTML content and |safe
	TinyMCE in admin (不要用 django_tinymce, 自己土砲)
		class "Media" in ModelAdmin
		Admin widget
	各種第三方套件 (TinyMCE, Bootstrap WYSIWYG, jQuery-TinyMCE, Filebrowser)
	class Tag
		M2M field
			Through table
			Admin widgets
	Getting tags in view/template
		Relation object manager (好像不是叫這個名字...)

Blog, part 2
	為網站放一個 global navigation bar
		Context processor
	紀錄瀏覽次數
		Model "PageViewLog"
		Middleware
		其實這個方法沒有很好
			Google Analytics
			NoSQL databases
	側邊欄
		Tag cloud
			進階雙底線語法
		Template "include"
		熱門文章 (除了目前這篇 -- 應用 get_absolute_url 與 request object)
		用 inclusion tag 減少 code duplication

首頁與靜態網頁
	我推薦首頁有自己的 view -- 為什麼？
	Template tag/filter fun
	Flat pages
		Too many views
		contrib.flatpages
			https://docs.djangoproject.com/en/dev/ref/contrib/flatpages/
			TinyMCE admin
	把首頁和靜態頁面加入 navigation bar

I18n 與 L10n
	# https://docs.djangoproject.com/en/dev/topics/i18n/
	名詞解釋
	Internationalization
		Settings
			USE_I18N
				Why would I want to turn it off?
			LOCALE_PATHS, locale 目錄與語言目錄
		Language info (getting & setting)
			語言選擇依據
		Translation in Django
			GNU gettext
			ugettext vs ugettext_lazy
			Python side
			Template side
			JavaScript
		翻譯檔制作、撰寫、編譯
	Localization
		Settings
		Howto
	三論時區 (好像應該統一一下？)

Deployment
	為了您的健康, 請不要 deploy 到 Windows
	WSGI: 這是什麼？
		wsgi.py
	(HTTP Server -) WSGI Server - Django (或任何的 Python web framework)
		Static/media file serving
		HTTP server 千百種
	主流的部署模式
		簡單講一下優缺點
		mod_wsgi (+ Apache)
			Warning: 不要用 mod_python
		Gunicorn (+ HTTP server)
		uWSGI (+ HTTP server)
	DEBUG 與 collectstatic
	上線時如何隱藏 admin site 或至少換網址
	官方文件
	
Where to Go From Here
	Learn English
	
TODO:
	要在哪裡講 relation field 的 lazy initialization 與 model decoupling?
	文章的 Canonical URL
	用 Disqus 實作 blog comments?
	要不要有 for the interested 區來 tease 一些進階的和 internal 的東西？
	Ajax & CSRF & …?
				
附錄
	如何使用 Django 的官方文件
		注意對應的 Django 版本
	Django 的 deprecation policy