luci-base: zh_CN: update Simplified Chinese translation
[project/luci.git] / documentation / ThemesHowTo.md
1 # HowTo: Create Themes
2 *Note:* You should read the [Module Reference](Modules.md) and the [Template Reference](Templates.md) before.
3
4 We assume you want to call your new theme _mytheme_. Make sure you replace this by your module name every time this is mentionend in this Howto.
5
6
7
8 # Creating the structure
9 At first create a new theme directory *themes/_mytheme_*.
10
11 Create a _Makefile_ inside your theme directory with the following content:
12         
13         include ../../build/config.mk
14         include ../../build/module.mk
15         
16
17 Create the following directory structure inside your theme directory.
18 * ipkg
19 * htdocs
20   * luci-static
21    * _mytheme_
22 * luasrc
23   * view
24    * themes
25     * _mytheme_
26 * root
27   * etc
28    * uci-defaults
29
30
31
32 # Designing
33 Create two LuCI HTML-Templates named _header.htm'' and ''footer.htm'' under *luasrc/view/themes/''mytheme_*.
34 The _header.htm'' will be included at the beginning of each rendered page and the ''footer.htm_ at the end.
35 So your _header.htm'' will probably contain a DOCTYPE description, headers, the menu and layout of the page and the ''footer.htm_ will close all remaining open tags and may add a footer bar but hey that's your choice you are the designer ;-).
36
37 Just make sure your _header.htm_ *begins* with the following lines:
38         
39         <%
40         require("luci.http").prepare_content("text/html")
41         -%>
42         
43
44 This makes sure your content will be sent to the client with the right content type. Of course you can adapt _text/html_ to your needs.
45
46
47 Put any stylesheets, Javascripts, images, ... into *htdocs/luci-static/_mytheme_*.
48 You should refer to this directory in your header and footer templates as: _<%=media%>''. That means for a stylesheet *htdocs/luci-static/''mytheme_/cascade.css* you would write:
49         
50         <link rel="stylesheet" type="text/css" href="<%=media%>/cascade.css" />
51         
52
53
54
55 # Making the theme selectable
56 If you are done with your work there are two last steps to do.
57 To make your theme OpenWRT-capable and selectable on the settings page you should now create a file *root/etc/uci-defaults/luci-theme-_mytheme_* with the following contents:
58         
59         #!/bin/sh
60         uci batch <<-EOF
61                 set luci.themes.MyTheme=/luci-static/mytheme
62                 commit luci
63         EOF
64         
65
66 and another file *ipkg/postinst* with the following content:
67         
68         #!/bin/sh
69         [ -n "${IPKG_INSTROOT}" ] || {
70                 ( . /etc/uci-defaults/luci-theme-mytheme ) &&        rm -f /etc/uci-defaults/luci-theme-mytheme
71         }
72         
73
74 This is some OpenWRT magic to correctly register the template with LuCI when it gets installed.
75
76 That's all. Now send your theme to the LuCI developers to get it into the development repository - if you like.