lethain / django-userskins

A pluggable Django app for allowing users to pick among a variety of skins for webapps.

This URL has Read+Write access

django-userskins / README.markdown
raw normal view history
0eac769b » lethain 2008-10-27 Updated README to reflect c... 1
baf4193c » lethain 2008-10-27 Rectifying horrifying word ... Comment 2 # CONCEPT
14ec608e » lethain 2008-10-27 Updated README to explain t... 3
baf4193c » lethain 2008-10-27 Rectifying horrifying word ... Comment 4 The purpose of django-userskins is to facilitate Django apps
14ec608e » lethain 2008-10-27 Updated README to explain t... 5 to allow users to select from a variety of provided skins
6 to customize how a site looks for them. Essentially, to
7 provide the functionality exposed in Twitter's recent
8 update where users can choose from a handful of different
9 appearances for how Twitter appears when they visit the
10 site.
11
12
13 # IMPLEMENTATION
14
15 Django-userskins' implementation is designed to minimize
16 additional hits on the database, but to allow the skin
17 preference to persist across cleanings of the cookie cache.
18
19 The implementation is split into a template processing context,
20 a template tag, and a middleware.
21
22 #### userskins.context.userskins
23
24 The behavior of the custom template processing context
25 is:
26
27 1. Check if the user has a cookie named ``userskins``.
28 If so, use its value to select the skin.
29
30 2. Otherwise use the default skin.
31
32 #### userskins.middleware.UserskinsMiddleware
33
34 The behavior of the middleware is to examine all
35 HttpResponse objects and:
36
37 1. If the HttpResponse object has a cookie named
38 ``userskins``, do nothing.
39
40 2. If the response does not have a cookie named ``userskins``,
41 then if the user is anonymous give it a ``userskins`` cookie
42 for the default skin.
43
44 If the user is authenticated, then attempt to retrieve a
45 ``userskins.SkinPreference`` object with the logged in user
46 as the value of its ``user`` foreign key.
47
48 (Note that this is the only hit on the database that the
49 userskins app will cause. Meaning, it will only hit the
50 database for logged in users who don't already have a
51 userskins cookie. When it does hit the database, it will
52 set a cookie for the user, so it should only be necessary
53 to hit the database once each time a user cleans their
a7108658 » lethain 2008-10-27 Added support for the USERS... 54 cookie cache. Also note, that you may use the
55 ``USERSKINS_NEVER_ACCESS_DATABASE`` setting value to
56 disable the middleware, and thus remove all database
57 accesses, although skin preferences will no longer
58 persist across cookie cleanings.)
14ec608e » lethain 2008-10-27 Updated README to explain t... 59
60 Set the value of the ``userskins`` cookie to the value stored
61 in the ``SkinPreference`` object if one exists, otherwise set
62 it to the default skin.
63
64 #### userskins.templatetags.userskins
65
66 The ``userskins`` template tag library contains one template
67 tag, ``userskin``, which takes no arguments and handles outputing
68 the correct CSS include or (if you have the correct settings enabled)
69 django-compress group.
70
71
72 # SETUP
0eac769b » lethain 2008-10-27 Updated README to reflect c... 73
74 1. Add ``django-userskins.userskins`` to your Python path.
115e9b68 » lethain 2008-10-27 Updated README. 75
76 2. Add ``userskins`` to your applications ``INSTALLED_APPS``
77 setting in settings.py.
78
79 3. Add the ``userskins.context.userskins`` template context
80 processor in ``settings.py`` (note that this will be a
81 new setting in your settings.py file, by default it is
82 not shown):
0eac769b » lethain 2008-10-27 Updated README to reflect c... 83
84 TEMPLATE_CONTEXT_PROCESSORS = (
85 "django.core.context_processors.auth",
86 "django.core.context_processors.debug",
87 "django.core.context_processors.i18n",
88 "django.core.context_processors.media",
89 "userskins.context.userskins",
90 )
91
0117e893 » lethain 2008-10-27 Updated README for using th... 92 4. Add the ``userskins.middleware.UserskinsMiddleware``
93 middleware to your project's middleware.
94
95 MIDDLEWARE_CLASSES = (
96 'django.middleware.common.CommonMiddleware',
97 'django.contrib.sessions.middleware.SessionMiddleware',
98 'django.contrib.auth.middleware.AuthenticationMiddleware',
99 'userskins.middleware.UserskinsMiddleware',
100 )
101
102 The position of the ``UserskinsMiddleware`` shouldn't be
103 signifigant.
104
105 5. Establish values for the ``USERSKINS_DEFAULT``, ``USERSKINS_DETAILS``
115e9b68 » lethain 2008-10-27 Updated README. 106 and ``USERSKINS_USE_COMPRESS_GROUPS_INSTEAD`` values in your
107 settings.py file.
0eac769b » lethain 2008-10-27 Updated README to reflect c... 108
109 USERSKINS_DEFAULT = "light"
110 USERSKINS_DETAILS = {
111 'light':'light.css',
112 'dark':'dark.css',
113 }
a7108658 » lethain 2008-10-27 Added support for the USERS... 114 USERSKINS_USE_COMPRESS_GROUPS = False # optional
115 USERSKINS_NEVER_ACCESS_DATABASE = False # optional
0eac769b » lethain 2008-10-27 Updated README to reflect c... 116
42fc3bd4 » lethain 2008-10-27 Fixed typo in context.py an... 117 ``USERSKINS_USE_COMPRESS_GROUPS`` is to support integration
0eac769b » lethain 2008-10-27 Updated README to reflect c... 118 with the django-compress project. In that case, the values of keys
119 in ``USERSKINS_DETAILS`` are ignored, and the keys themselves are
120 passed to the django-compress template tags as names of compressed
a7108658 » lethain 2008-10-27 Added support for the USERS... 121 css groups. The default value of ``USERSKINS_USER_COMPRESS_GROUP``
122 is False.
0eac769b » lethain 2008-10-27 Updated README to reflect c... 123
124 It is highly recommended to use django-userskins along with
125 django-compress, as it will allow you to provide users with
126 selectable skins without increasing the median bandwith per
127 request or the median number of http requests per page.
128
a7108658 » lethain 2008-10-27 Added support for the USERS... 129 There is also the ``USERSKINS_NEVER_ACCESS_DATABASE`` option,
130 which is what you should use if you want skin preferences to
131 be entirely cookie based (and never check the database if
132 the user has an associated SkinPreference object). The default
133 value of ``USERSKINS_NEVER_ACCESS_DATABASE`` is False.
134
135 7. Sync your database to create the relevant models.
136 Note that this is not necessary if you use
137 ``USERSKINS_NEVER_ACCESS_DATABASE = True``.
138
139 python manage.py syncdb
140
141 8. Now modify your base template (or wherever you want to use skins)
115e9b68 » lethain 2008-10-27 Updated README. 142 to resemble this code:
0eac769b » lethain 2008-10-27 Updated README to reflect c... 143
115e9b68 » lethain 2008-10-27 Updated README. 144 {% load userskins %}
145 <html><head>
146 <title> Some title </title>
147 {% userskin %}
148 </head>
149 <body>
150 {% block content %}{% endblock %}
151 </body>
152 </html>
08d18107 » lethain 2008-10-27 first commit 153
a7108658 » lethain 2008-10-27 Added support for the USERS... 154 9. The last stage of setup is to setup a mechanism for
155 allowing users to select skins. Depending on your needs,
156 this may be as simple as a view that sets an appropriate
157 cookie and redirects to the page they came from, or it may
158 be part of a user preferences panel.
08d18107 » lethain 2008-10-27 first commit 159
a7108658 » lethain 2008-10-27 Added support for the USERS... 160 More details coming soon, for the time being look at the
161 userskins.models.SkinPreference model and the
162 dev_userskins.urls file for some ideas.