Notes on listFiles.php

Notes on listFiles.php

Overview

listFiles.php is a library that can be used to automatically generate a list of links to files in a folder under doc/ .

You can render the list of files either as a bulleted ("unordered") list or a table.

Why you should NOT use this

If you're bleeding, your first thought should be to apply a bandage, not a tourniquet. This is a tourniquet.

In particular,

• It does an end-run around the WCMS. The WCMS has no idea what this program is doing, so you can't see a preview in the WCMS, and changes in the WCMS could break it.
• The link text has to match (most of) the filename. This means many characters, such as commas, parentheses, question marks, exclamation marks,  and colons can't be used in the link text. You can't even use spaces in filenames, since that breaks CAS, though we do have a workaround.
• The process to list your files in a particular order is pretty cumbersome.
• You'll have to learn how to use it, and the quirks and limitations.
• The tables version is fairly hack-y. It checks the screen dimensions at runtime by launching a JavaScript program that relaunches the page and treats it like a form. The upshot is that the page has to be rendered twice, and if someone refreshes a page with the tables version, they will get a dialog asking if they are sure they want to resubmit the (invisible) form.

Why you SHOULD use this

You have a lot of files that need to be displayed with link text that can be put in the filename.

How to use this

Upload your files to the appropriate folder under doc/ . Make sure the name of every file (not including the extension) exactly matches what you want the text of the link to say on the webpage, with two exceptions:

1. Don't put spaces in your filenames. Use underscores "_" instead. The program will translate the underscores to spaces when it makes the list.
2. The program will list the documents in order of filenames, i.e., in order of link text. If this isn't what you want, you can force an order by putting digits followed by an underscore at the start of the filename. The program will drop the digits (and underscore) when it makes the list. For example: If you want to list "Spring 2016" followed by "Fall 2016", you could name your files 1_Spring_2016.pdf and 2_Fall_2016.pdf .

Be sure to publish your doc/ folder. (If you need to limit access to the docs, make sure Raja has put in the .htaccess file for you.)

Create a Code Chunk within the WCMS. Copy and paste one of the following code examples:

Displaying files in a bulleted list:

Displaying files as a table

Note 1: Be sure to change the path and pattern you give to displayFilesAsList( ) appropriately. For instance, if you wanted to list *.xlsx files in doc/walnuts/ , you would change the path to:

'/ip/uirrwww/wwws/doc/walnuts/*.xlsx'

If you only wanted to list PDF files in /doc/walnuts that started with the word Fall , you could do

'/ip/uirrwww/wwws/doc/walnuts/Fall*.pdf'

and so on.

Note 2: When you're displaying a table, specify the number of columns after the path. The table example above is for 3 columns; change that as appropriate.

Once you have put in your code chunk, click Submit. When you do so, you'll see the preview. The preview will NOT include your file list; remember, we're doing an end-run around the WCMS.

Publish your page to Test.

Open a new browser window (or tab) and view the page on Test.

If you see any problems, edit your code chunk, Submit, and publish.

New Feature: Reverse list

If you want to reverse the order of items in a list, append an extra flag: 'rev' . So for example,

displayFilesAsList('/ip/uirrwww/wwws/doc/walnuts/Syrup_20*.pdf', 'rev');

would display the files in doc/walnuts/ with a name matching Syrup_20*.pdf in reverse order. So, for instance, 'Syrup 2015' would display above 'Syrup 2014'. The 'rev' flag works with both lists and tables.

Questions? Problems?

Ask Raja or Justin or the mailing list.