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`.
   5 Make sure you replace this by your module name everytime this is mentionend in this Howto.
   6
   7 ## Creating the structure
   8 At first create a new theme directory `themes/luci-theme-mytheme`.
   9
  10 Create a `Makefile` inside your theme directory with the following content:
  11 ```Makefile
  12 include $(TOPDIR)/rules.mk
  13
  14 LUCI_TITLE:=Title of mytheme
  15
  16 include ../../luci.mk
  17 # call BuildPackage - OpenWrt buildroot signature
  18 ```
  19
  20 Create the following directory structure inside your theme directory.
  21 * ipkg
  22 * htdocs
  23   * luci-static
  24     * `mytheme`
  25 * luasrc
  26   * view
  27    * themes
  28       * `mytheme`
  29 * root
  30   * etc
  31    * uci-defaults
  32
  33
  34 ## Designing
  35 Create two LuCI HTML-Templates named `header.htm` and `footer.htm` under `luasrc/view/themes/mytheme`.
  36 The `header.htm` will be included at the beginning of each rendered page and the `footer.htm` at the end.
  37 So your `header.htm` will probably contain a DOCTYPE description, headers,
  38 the menu and layout of the page and the `footer.htm` will close all remaining open tags and may add a footer bar.
  39 But hey that's your choice you are the designer ;-).
  40
  41 Just make sure your `header.htm` begins with the following lines:
  42 ```
  43 <%
  44 require("luci.http").prepare_content("text/html")
  45 -%>
  46 ```
  47
  48 This makes sure your content will be sent to the client with the right content type.
  49 Of course you can adapt `text/html` to your needs.
  50
  51
  52 Put any stylesheets, Javascripts, images, ... into `htdocs/luci-static/mytheme`.
  53 You should refer to this directory in your header and footer templates as: `<%=media%>`.
  54 That means for a stylesheet `htdocs/luci-static/mytheme/cascade.css` you would write:
  55 ```html
  56 <link rel="stylesheet" type="text/css" href="<%=media%>/cascade.css" />
  57 ```
  58
  59 ## Making the theme selectable
  60 If you are done with your work there are two last steps to do.
  61 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:
  62 ```sh
  63 #!/bin/sh
  64 uci batch <<-EOF
  65         set luci.themes.MyTheme=/luci-static/mytheme
  66         commit luci
  67 EOF
  68 exit 0
  69 ```
  70
  71 and another file `ipkg/postinst` with the following content:
  72 ```sh
  73 #!/bin/sh
  74 [ -n "${IPKG_INSTROOT}" ] || {
  75         ( . /etc/uci-defaults/luci-theme-mytheme ) && rm -f /etc/uci-defaults/luci-theme-mytheme
  76 }
  77 ```
  78
  79 This is some OpenWrt magic to correctly register the template with LuCI when it gets installed.
  80
  81 That's all. Now send your theme to the LuCI developers to get it into the development repository - if you like.