Differences

This shows you the differences between two versions of the page.

--- generic:mods:theming [2017/09/17 11:57]
matthias [Folders & Files]
+++ generic:mods:theming [2017/09/17 13:29] (current)
matthias [FAQ]
@@ Line 3: / Line 3: @@
 ===== Folders & Files =====
+On the webpage, all URLs and links (JS & CSS) are absolute URLs agains ''/content/..''.
 === /opt/piratebox/www ===
@@ Line 9: / Line 10: @@
 === /opt/piratebox/www_content ===
-This folder contains the original unmodified version of the landing page. It is a backup of the default theme and is copied to ''/opt/piratebox/share/content'' during first initialization. PirateBox keeps a copy of the folder in case of (accidentally) removing the ''content'' folder on the USB stick- this folder will be placed again to /opt/piratebox/share/content if ''content'' is missing during startup.
 **Note:** It is not necessarily needed to modify this folder.
+This folder contains the original unmodified version of the landing page. It is a backup of the default theme and is copied to ''/opt/piratebox/share/content'' during first initialization. PirateBox keeps a copy of the folder in case of (accidentally) removing the ''content'' folder on the USB stick- this folder will be placed again to /opt/piratebox/share/content if ''content'' is missing during startup.
 === /opt/piratebox/share/content ===
-''/opt/piratebox/www/content'' is a symlink to ''/opt/piratebox/share/content'' , which means, that those are //kind of// identical. As the ''share'' folder is typically on the USB stick or the expanded storage medium, you can backup, edit and exchange this folder on your computer (in case of USB stick). __This is the folder which you should focus on adding on your modifications.__
+__This is the folder which you should focus on adding on your modifications.__ ''/opt/piratebox/www/content'' is a symlink to ''/opt/piratebox/share/content'' , which means, that those are //kind of// identical. As the ''share'' folder is typically on the USB stick or the expanded storage medium, you can backup, edit and exchange this folder on your computer (in case of USB stick). **favicon.ico** is stored here.
+=== /opt/piratebox/share/content/locales ===
+In this folder the different language files are stored.
+If you want a multi-language box, you may want to adjust these text files. If you only want to have //your// modification only, it is better to disable the language feature (see below).
 === /opt/piratebox/share/content/js ===
-=== /opt/piratebox/share/content/css ===
+Contains custom Javascript code including jQuery and the l10n script. jQuery might be referred by the directory listing in ''http://piratebox.lan/Shared''.
-=== /opt/piratebox/share/content/locales ===
 === /opt/piratebox/share/content/img ===
+The PirateBox logo files are located here. You may just replace the file itself (with the same name) or add other files.
+=== /opt/piratebox/share/content/css ===
+Here is the CSS file ''page_style.css'' for the landing page and the __directory listing__.
 === /opt/piratebox/share/Shared ===
-HEADER.txt & README.txt
+Due to legacy reasons, this is the most difficult part for customizations. PirateBox uses the most ressource-free method to create the directory listing, which is the lighttpd built in listing. The initial configuration is in ''/opt/piratebox/conf/lighttpd/ligghtpd.conf'' at this point a reference to ''/content/css/page_style.css'' is included and to add ''HEADER.txt'' (head) and ''README.txt'' (bottom) of each page. In summary, this creates the PirateBox theme look & feel of the directory listing.
-=== /opt/piratebox/src/*.txt ===
-HEADER.txt & README.txt
+You have to make sure, that ''page_style.css'' is available or the directory listing redirect to the landing page. You can directly edit HEADER.txt and README.txt in the ''/opt/piratebox/share/Shared'' folder. After you finished editing these files, copy your modified version over to ''/opt/piratebox/src''.  __Create a backup of these files__, instead of the ''/content'' folder, these files are overwritten during an upgrade.
+If you already have a larger folder structure, you can you PirateboxScripts to distribute your version of ''HEADER.txt'' and ''README.txt'' over to these folders. Run:
+  sudo /opt/piratebox/bin/distribute_files.sh /opt/piratebox/share/Shared 'true'
+**Note:** i10n Feature is not enabled for directory listing.
 ===== Permissions =====
 On OpenWrt based PirateBox your are typically working as root and the USB Stick does not reflect a the Linux file permissions, you do not have to deal with it here. On RPi based or normal Linux based PirateBox it is a bit more difficult. The normal installation changes the permissions of the www folders (see above) to the owner/group ''nobody/nogroup'' and the files are read-writable for user&group only, while the user login is ''alarm''. For a normal webserver setup, this is sufficient- but for customization it is difficult.
@@ Line 43: / Line 55: @@
 ==== Customization hints ====
+Beside of HEADER.txt and README.txt you can easily exchange the ''/opt/piratebox/share/content'' folder with your own.
 === Language files ===
-=== Deactivate i8n feature ===
+The ''data-<lang>.properties'' are containing the text which is inserted **during pageload**. The text you can see in the files located in ''/opt/piratebox/share/content'' is a space holder, which is used if no corresponding ''data-<lang>.properties'' file is found. (Language files needs to be referred in ''locales.ini'').
+=== Deactivate i10n feature ===
+If you want to edit directly the text in the HTML file, you might want to disable i10n.
+To disable that feature, find & remove the following line in ''/opt/piratebox/share/content/index.html'':
+<code html>
+   <script type="text/javascript" src="/content/js/l10n.js"></script>
+</code>
 ==== FAQ ====
 === Redirect loops ===
-=== In case of an upgrade of PirateBox ===
+Redirect loops usually happen, if you refer to a not existing file, which creates a HTTP 404 - which results in a redirect to the landing page... which is referring to a not existing file ... which creates HTTP 404 - you can imagine. To debug this issue, you might want to use the [[https://developers.google.com/web/tools/chrome-devtools/network-performance/resource-loading|features of your browser]] to identify the 404. If you can not find it like this, you might want to disable the automatic redirect in lighttpd configuration (OpenWrt - omit sudo)
+  sudo sed -i -e "s/^server.error-handler-404/#server.error-handler-404/" \
+      /opt/piratebox/conf/lighttpd/lighttpd.conf
+You might want to restart the piratebox or just the service.
+OpenWrt:
+   cd /
+   /etc/init.d/piratebox restart
+RPi:
+   sudo systemctl restart piratebox
+To re-enable it, just run the following command:
+  sudo sed -i -e "s/^#server.error-handler-404/server.error-handler-404/" \
+      /opt/piratebox/conf/lighttpd/lighttpd.conf
+Restart Piratebox again.
+=== In case of an upgrade of PirateBox ===
+During a reboot the following happens to your customization
+  - ''/opt/piratebox/share/content'' stays completely untouched.
+  - ''README.txt'' and ''HEADER.txt'' **is overwritten** with a new version.
+  - Customization it ''/opt/piratebox/conf'' **is overwritten** and lost.