FileTree is the answer if you have anything between a dozen or several thousand files on a web server that you want people to browse. It’s particularly good for large digital archives of images or PDF files. This clever stack saves you from the monotonous chore of manually setting and linking long lists of files - and the frustrating repetitiveness of needing to update things when files move! FileMan can safely exclude file types you do not want listed. Plus it will display little Font Awesome 5 file type icons next to each file.

Why not just enable FollowSymLinks on the web server to allow directory listing and file navigation in the browser window? Because this isn't a particularly pretty way for people to navigate files on your hosting server. It can also be potentially hazardous, as it can expose files or directories you may not want the outside world to see! FileTree offers a more integrated and refined approach for the RapidWeaver user.

Part of FileTree is loosely derived from the free PHP File Tree plugin, written in 2007. However the PHP code in FileTree stack has been rewritten to address PHP 7.x compatibility issues. Much work has also been done to completely rewrite the CSS codebase with Font Awesome 5 Icon support; which subsequently adds big visual improvements, compared to little 'fuzzy' GIF icons.

FileTree will do its best to reuse your RapidWeaver theme styling; like link colours and font faces you set in Page Inspector > Themes Styles. The file type icons are fully customisable via CSS, if you need to change them. We include size, indentation and line height options for you too in the stack settings.

For such a powerful stack, FileTree is easy to setup. Simply provide a relative path in the stack settings, to the location of where you want FileTree to start building its navigation from. This can be any public directory on your hosting account, including a section or your website or a folder of resources you have added in the Resources panel of RapidWeaver.

Example

The example below uses the default settings. FileTree has been configured to read a directory of files from the Stacks4Stacks website and output a file list in the webpage. Try clicking on the directory names, to navigate the file tree:
 
In our quick example here, files open in the same browser window. However there are several different 'actions' you can choose to apply instead (including links opening in new tabs and lightbox support), which are documented below.

Setup

Firstly, make sure you have Stacks 3 or greater installed on your computer and that your web server is running PHP 7.1 or later. Follow these instructions carefully for using FileTree:
  1. Once downloaded and installed into Stacks 3 / RapidWeaver, open your Stacks library. Search for 'FileTree'.
  2. Drag and drop a copy of FileTree into an existing or new webpage. The file extension is automatically changed to .php in the Page Inspector.
  3. In the stack settings, configure the relative path, to the point at which you want FileTree to begin constructing its directory / file list. If you are unsure what a relative path is or looks like, please see the information below.
  4. Change any of the other settings, if applicable. It is possible to edit the CSS markup for the icons, adjust the list styling and setup an array of acceptable file types you want listed.
  5. Preview and publish your webpage when done.

A mock file tree is displayed in RapidWeaver preview mode. This provides a quick playground to test settings against and approximate what the finished thing will look like. This mock file tree is replaced with your actual file tree, after you export or publish your website.

You can safely use multiple FileTree stacks on the same webpage. FileTree can also integrate seamlessly with the TopBox Enabler or TopBox lightbox stacks (sold separately) if you want to lightbox simple files like images, PDFs, audio or video. FileTree is only able to construct a file tree of directories and files stored on the same web server the website has been published on.

What is a relative path?

PHP (which FileTree uses) is a server-side programming language. PHP cannot see web addresses in the same way you see them in a web browser address bar (e.g. https://example.com). PHP needs to use relative paths instead, to traverse your file structure internally. You use ../ to count how many levels down the FileTree webpage is from root (root is another word for your homepage):

../../

In the above example, we can assume my FileTree page is two directories down from the homepage, at a location like https://example.com/about-us/file-viewer/. Then it is just a case of instructing FileTree the path to the directory containing the files you want to display:

../../shared-files/

Now FileTree will construct a file tree from all the files stored in https://example.com/shared-files/ and display them in https://example.com/about-us/file-viewer/. Relative paths may look complicated, but are quite easy to do. Plus very fast and secure for machines to use. Search online if you need more help with relative paths.

FileTree Actions

FileTree has a set of actions you can choose from in the Link Action select menu. These let you change the behaviour of FileTree and more specifically what happens when a user clicks or taps on a file link.
  • Do Nothing - only displays the file name. Clicking or tapping the link has no effect. Useful to show people lists of files, but not necessarily let them open or download them.
  • Download - attempts to force the download of files using the HTML5 download attribute in supported web browsers. Worth noting that some file types (like anything compressed as a .zip package) will always download by default.
  • New Tabs - opens files in new browser tabs. This may make navigation easier, depending on the clientele using your FileTree stack.
  • Normal Navigation (default) - an end user can navigate and open files in the same browser window as normal. For novice users, this can often prove easier and more predictable; compared with files opening in new tabs.
  • TopBox Lightbox - Opens the files within the free TopBox Enabler or paid TopBox lightbox stacks. This should only be used for FileTree stacks containing images, PDF, audio or video, because TopBox does not support other content types.

Also of note, there is a special Always Keep File Lists Expanded option in the stack settings. As this implies, the file tree will be kept permanently open (expanded) at all times and behave like a conventional sitemap. With this setting enabled, the end user cannot expand or collapse directories; everything is always shown. Clicking or tapping directory names will have no effect.

Websafe File Names

Any directories or files you upload to the internet must always have web safe file names. That means the file name must never contain spaces, punctuation or other special characters. The only permitted characters are letters, numbers, hyphens, underscores. For image files, you can use an '@' character to denote a retina-optimised image. Never include things like brackets, quotes, colons, question marks or periods in names. If a directory or file uploaded to the internet contains illegal characters or symbols, there is a high probability end users will not be able to access it. Other functionality like lightboxes could also break. Adopting the use of web safe file names is certainly not difficult to do. It will help FileTree and other stacks work more reliably.

Something else to consider is that certain file types can only be viewed in the web browser if the person has the correct software installed on their computer or device. For example a Photoshop (.psd) file may only display correctly if the end user has a recent version of Adobe Photoshop installed. Files like JPG, PNG, GIF, MP3, MP4, PDF, HTML, RTF and TXT are typically safer to share over the internet. For other file types, you may need to convert them into a more universal standard (like PDF) or provide them as a .zip package download to circumvent previewing problems in the web browser.

FileTree Icons

It is not mandatory to edit the CSS markup for icons. We have already implemented a good icon set for you to use in any theme with Font Awesome 5 Icon support and carefully chosen complimentary icon colours to match. You only need to edit the FileTree icons if you want to change icons or colours. And if you want to add support for new file types, you need to edit the CSS too. For everyone else, you can skip past this stage.

Icons form a significant part of the FileTree stack. They can provide a colour-coded visual guide to end users; helping them to understand what each file format is. For example, most users would quickly recognise the blue 'W' icon of a Microsoft Word document or a free 'X' icon of an Excel spreadsheet. It is a good idea to follow similar design practices for your icons.

We use Font Awesome 5 Icons and CSS markup to control the icon colouring. FileTree assumes that your RapidWeaver theme already includes Font Awesome 5 icons. Nearly all the free and paid themes at ThemeFlood include Font Awesome 5 support as standard. If your theme uses an older version of Font Awesome (like Font Awesome 4), you may have to check the icons still work and amend the markup accordingly (especially if you are seeing squares instead of icons).

If you are using a theme with no Font Awesome 5 Icon support, you will either need to find a simple way of adding Font Awesome icon support to your webpage (like one of the methods suggested on the 'Font Awesome getting started' page) or switch to using a better theme, like those listed on ThemeFlood. Alternatively if Font Awesome icons are not to your taste, you can use practically any other font icon library of your choosing. FileTree is very flexible, in this respect.

You double-click the CSS code shown in edit mode to change it. We recommend that you paste it into an external code editor (like Atom, TextWrangler or Visual Studio Code) as the syntax highlighting and auto-complete may make things a lot easier for you.

All icons share this CSS code:

/* Font styling for all icons */
.filetree-stack .filetree-stack-directory:before,
.filetree-stack li:before {
  font-family: 'Font Awesome 5 Free';
  font-style: normal;
  font-weight: normal;
  text-decoration: inherit;
}

Directories and unknown file types have the following CSS code:

/* Directories (folders) */
.filetree-stack .filetree-stack-directory:before { content: '\f07b'; color: #F6CC4F; }

/* Unknown file type */
.filetree-stack li.filetree-stack-file:before { content: '\f15c'; color: #333333; }


Recognised file types have the following CSS code:

.filetree-stack li.ext-jpg:before { content: '\f1c5'; color: #709A44; }


You can hopefully start to see patterns emerging in the code, even if you don't fully understand what the code means. The letters typed after ext- are the name of the file extension you are looking for (the above example uses 'jpg'). The four letters or numbers after the backslash character (e.g. f1c5) are the Font Awesome 5 unicode; which can be obtained for each desired icon from the Font Awesome Icons website. And finally you have the hexadecimal colour value for the icon (e.g. #709A44).

Assuming we wanted to add a new icon type for Adobe Photoshop files, we could do something like this:

.filetree-stack li.ext-psd:before { content: '\f1c5'; color: #2E356F; }

This would create a dark blue image file icon (similar to the Photoshop app icon), displayed alongside any file ending with a .psd Photoshop extension.

TopBox lightbox support

Add a free TopBox Enabler or the paid TopBox stack to the webpage. Preferably place TopBox below your FileTree stack, so that TopBox is able to capture the links being loaded. Simple file types like images, audio, video and PDF are supported. Be sure your file tree does not include complicated file types (like text files, office documents and .zip packages) as these will not work inside the lightbox. You can control what files are listed in the FileTree settings, to remove those that are not supported by TopBox. Customise your lightbox effect as you normally would, using the TopBox settings. You can change the TopBox Grouping option to only show lightbox navigation links for files within that directory, lightbox navigation links for all files in FileTree, or turn off the lightbox navigation links. The file name of your file can be displayed as the lightbox title, by using the Title Tooltips setting.
 

Contribute

If you find this stack element useful in your personal or commercial web projects; please consider making a small contribution towards ongoing support and updates. There are many different ways you can contribute to the Stacks4Stacks project, and benefits for doing so.