|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+================================
|
|
|
2
|
+How to change Oscar's appearance
|
|
|
3
|
+================================
|
|
|
4
|
+
|
|
|
5
|
+This is a guide for Front-End Developers (FEDs) working on Oscar projects, not
|
|
|
6
|
+on Oscar itself. It is written with Tangent's FED team in mind but should be
|
|
|
7
|
+more generally useful for anyone trying to customise Oscar and looking for the
|
|
|
8
|
+right approach.
|
|
|
9
|
+
|
|
|
10
|
+Overview
|
|
|
11
|
+========
|
|
|
12
|
+
|
|
|
13
|
+Oscar ships with a set of HTML templates and a collection of static files
|
|
|
14
|
+(eg images, javascript). Oscar's default CSS is generated from LESS
|
|
|
15
|
+files.
|
|
|
16
|
+
|
|
|
17
|
+Templates
|
|
|
18
|
+---------
|
|
|
19
|
+
|
|
|
20
|
+Oscar's default templates use the mark-up conventions from the Bootstrap
|
|
|
21
|
+project. Classes for styling should be separate from classes used for
|
|
|
22
|
+Javascript. The latter must be prefixed with ``js-``, and using data attributes
|
|
|
23
|
+is often preferable.
|
|
|
24
|
+
|
|
|
25
|
+Frontend vs. Dashboard
|
|
|
26
|
+----------------------
|
|
|
27
|
+
|
|
|
28
|
+The frontend and dashboard are intentionally kept very separate. They
|
|
|
29
|
+incidentally both use Bootstrap, but may be updated individually.
|
|
|
30
|
+The frontend is based on Bootstrap's LESS files and ties it together with
|
|
|
31
|
+Oscar-specific styling in ``styles.less``.
|
|
|
32
|
+
|
|
|
33
|
+On the other hand, ``dashboard.less`` just contains a few customisations that
|
|
|
34
|
+are included alongside a copy of stock Bootstrap CSS - and at the time of
|
|
|
35
|
+writing, using a different Bootstrap version.
|
|
|
36
|
+
|
|
|
37
|
+LESS/CSS
|
|
|
38
|
+--------
|
|
|
39
|
+
|
|
|
40
|
+By default, CSS files compiled from their LESS sources are used rather than the
|
|
|
41
|
+LESS ones. To use Less directly, set ``USE_LESS = True`` in your settings file.
|
|
|
42
|
+You will also need to ensure that the ``lessc`` executable is installed and is
|
|
|
43
|
+configured using a setting like::
|
|
|
44
|
+
|
|
|
45
|
+ COMPRESS_PRECOMPILERS = (
|
|
|
46
|
+ ('text/less', 'lessc {infile} {outfile}'),
|
|
|
47
|
+ )
|
|
|
48
|
+
|
|
|
49
|
+A few other CSS files are used to provide styles for javascript libraries.
|
|
|
50
|
+
|
|
|
51
|
+Using offline compression
|
|
|
52
|
+~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
53
|
+
|
|
|
54
|
+Django compressor also provides a way of running offline compression which can
|
|
|
55
|
+be used during deployment to automatically generate CSS files from your LESS
|
|
|
56
|
+files. To make sure that compressor is obeying the ``USE_LESS`` setting and
|
|
|
57
|
+is not trying to compress CSS files that are not available, the setting has to
|
|
|
58
|
+be passed into the ``COMPRESS_OFFLINE_CONTEXT``. You should add something like
|
|
|
59
|
+this to your settings file::
|
|
|
60
|
+
|
|
|
61
|
+ COMPRESS_OFFLINE_CONTEXT = {
|
|
|
62
|
+ # this is the only default value from compressor itself
|
|
|
63
|
+ 'STATIC_URL': STATIC_URL,
|
|
|
64
|
+ 'use_less': USE_LESS,
|
|
|
65
|
+ }
|
|
|
66
|
+
|
|
|
67
|
+
|
|
|
68
|
+Javascript
|
|
|
69
|
+----------
|
|
|
70
|
+
|
|
|
71
|
+Oscar uses javascript for progressive enhancements. This guide used to document
|
|
|
72
|
+exact versions, but quickly became outdated. It is recommended to inspect
|
|
|
73
|
+``layout.html`` and ``dashboard/layout.html`` for what is currently included.
|
|
|
74
|
+
|
|
|
75
|
+Customisation
|
|
|
76
|
+=============
|
|
|
77
|
+
|
|
|
78
|
+Customising templates
|
|
|
79
|
+---------------------
|
|
|
80
|
+
|
|
|
81
|
+Oscar ships with a complete set of templates (in ``oscar/templates``). These
|
|
|
82
|
+will be available to an Oscar project but can be overridden or modified.
|
|
|
83
|
+
|
|
|
84
|
+The templates use Bootstrap conventions for class names and mark-up.
|
|
|
85
|
+
|
|
|
86
|
+There is a separate recipe on how to do this.
|
|
|
87
|
+
|
|
|
88
|
+Customising statics
|
|
|
89
|
+-------------------
|
|
|
90
|
+
|
|
|
91
|
+Oscar's static files are stored in ``oscar/static``. When a Django site is
|
|
|
92
|
+deployed, the ``collectstatic`` command is run which collects static files from
|
|
|
93
|
+all installed apps and puts them in a single location (called the
|
|
|
94
|
+``STATIC_ROOT``). It is common for a separate HTTP server (like nginx) to be
|
|
|
95
|
+used to serve these files, setting its document root to ``STATIC_ROOT``.
|
|
|
96
|
+
|
|
|
97
|
+For an individual project, you may want to override Oscar's static files. The
|
|
|
98
|
+best way to do this is to have a statics folder within your project and to add
|
|
|
99
|
+it to the ``STATICFILES_DIRS`` setting. Then, any files which match the same
|
|
|
100
|
+path as files in Oscar will be served from your local statics folder instead.
|
|
|
101
|
+For instance, if you want to use a local version of ``oscar/css/styles.css``,
|
|
|
102
|
+your could create a file::
|
|
|
103
|
+
|
|
|
104
|
+ yourproject/
|
|
|
105
|
+ static/
|
|
|
106
|
+ oscar/
|
|
|
107
|
+ css/
|
|
|
108
|
+ styles.css
|
|
|
109
|
+
|
|
|
110
|
+and this would override Oscar's equivalent file.
|
|
|
111
|
+
|
|
|
112
|
+To make things easier, Oscar ships with a management command for creating a copy
|
|
|
113
|
+of all of its static files. This breaks the link with Oscar's static files and
|
|
|
114
|
+means everything is within the control of the project. Run it as follows::
|
|
|
115
|
+
|
|
|
116
|
+ ./manage.py oscar_fork_statics
|
|
|
117
|
+
|
|
|
118
|
+This is the recommended approach for non-trivial projects.
|
|
|
119
|
+
|
|
|
120
|
+Another option is simply to ignore all of Oscar's CSS and write your own from
|
|
|
121
|
+scratch. To do this, you simply need to adjust the layout templates to include
|
|
|
122
|
+your own CSS instead of Oscar's. For instance, you might override ``base.html``
|
|
|
123
|
+and replace the 'less' block::
|
|
|
124
|
+
|
|
|
125
|
+ # project/base.html
|
|
|
126
|
+
|
|
|
127
|
+ {% block less %}
|
|
|
128
|
+ <link rel="stylesheet" type="text/less" href="{{ STATIC_URL }}myproject/less/styles.less" />
|
|
|
129
|
+ {% endblock %}
|
David Winterbottom
11 years ago