docs/ThemesHowTo.md

   1 # HowTo: Create Themes
   2 **Note:** You have already read the [Module Reference](./Modules.md) and the [Template Reference](./Templates.md).
   3
   4 We assume you want to call your new theme `mytheme`.
   5 Replace `mytheme` with your module name every time this is mentioned 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 ensures your content is 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 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, 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 correctly registers 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.