====== Theme - Guide ======
Among on the forums are several confusions about customizing PirateBox. Let's sum up the possibilities and make clear howto get to you custom Theme. Please provide feedback or help with unclear points in the [[https://forum.piratebox.cc/read.php?16,21261|Piratebox forum]].

===== Folders & Files =====
On the webpage, all URLs and links (JS & CSS) are absolute URLs agains ''/content/..''.

=== /opt/piratebox/www ===
This is the original webroot folder. You land on this folder when you enter ''http://piratebox.lan'' or any url without a path suffix. ''index.html'' is containing the absolute URL to the box' name and is changed with the ''/opt/piratebox/bin/install_piratebox.sh'' script. It 'always' refers to ''http://piratebox.lan/content''. This also used to forward in case of an unknown (404). PirateBox 1.1.3 still contains ''redirect.html'' which will be removed in the future.
Usually you do not have do modify the content here. In the folder the generated HTML pages for the Shoutbox and the disk usage bar is stored. All CSS & JS is in ''/opt/piratebox/www/content'' .

=== /opt/piratebox/www_content ===
**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 ===
__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 ===
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/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 ===
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.

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.
If you decided to use the USB stick as a storage option on RPi, you can easily edit the files on the USB stick.

The easiest way to make the needed folders writable for you is:

  sudo chmod a+w <folder>

for example for the content folder:

  sudo chmod a+w /opt/piratebox/share/content

After you are done with the customization, the recommendation is to perform the following commands:

  sudo chmod a-w <folder>
  sudo chown nobody:nogroup -R <folder>

**Note:** nobody:nogroup may be different on custom installations.

==== Customization hints ====
Beside of HEADER.txt and README.txt you can easily exchange the ''/opt/piratebox/share/content'' folder with your own.
=== Language files ===
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 ===
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.