Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
generic:mods:theming [2017/09/17 12:14] matthias [Folders & Files] |
generic:mods:theming [2017/09/17 13:29] (current) matthias [FAQ] |
||
---|---|---|---|
Line 3: | Line 3: | ||
===== Folders & Files ===== | ===== Folders & Files ===== | ||
+ | On the webpage, all URLs and links (JS & CSS) are absolute URLs agains ''/content/..''. | ||
=== /opt/piratebox/www === | === /opt/piratebox/www === | ||
Line 9: | Line 10: | ||
=== /opt/piratebox/www_content === | === /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. | **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/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). | + | __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 === | === /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/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/img === | === /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 === | === /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 ===== | ===== 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. | 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 ==== | ==== Customization hints ==== | ||
+ | Beside of HEADER.txt and README.txt you can easily exchange the ''/opt/piratebox/share/content'' folder with your own. | ||
=== Language files === | === 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 ==== | ==== FAQ ==== | ||
=== Redirect loops === | === 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. | ||