Server Requirements

• Operating Systems: Linux, Mac OSX, Windows Vista
• Apache 2+ (may work with 1.3+)
• PHP 5.2+
• NO DATABASE NEEDED
• mod_rewrite module (for clean URLs)
• GD Library (for auto-thumbnail generation)
• Server with Unicode support (PCRE UTF-8), if foreign character are needed.

Browser Compatibility

• Internet explorer : 6 and above
• Firefox: 3 and above
• Safari: 3 and above
• Opera: 9 and above
• Chrome: 2.0 and above

Not sure if your server is ready for Subfolio?

No problem, just download subfolio-compatibility.zip, unzip and upload the contents to the root of your domain or subdomain. Once uploaded, visit the following URL on your domain: http://www.yourdomain.com/subfolio-compatibility/

DOWNLOAD Subfolio 1.0.0

--> Download the app (latest): subfolio-master.zip

Recommended: To take advantage of Subfolio to the fullest extent, download the enhancer demo files

Introduction

Subfolio uses standard text files and folders. There is no installation files, no database setup and it will run on most any shared hosting environment.

Package contents

• directory/ is where you put all of your content
• config/ is the general settings, users & groups and themes
• engine/ is something you do not touch (unless you are an experience coder who wants to change the app itself)
• htaccess is a file sends instruction to your Apache server (must be renamed to .htaccess)

1-minute installation

1. Download the most recent version of Subfolio
   
2. Unzip the Subfolio package
   
3. Upload the package content to the ROOT of your domain (or subdomain)
   
4. Rename the file htaccess to .htaccess
   
5. Set all folder and file permissions to 755
   
6. And you're done. Visit URL and you should see a welcome page.

Setting file permissions

Whether you are using S/FTP or WebDAV, it is very important to set permissions on upload to 755 and that it "applies to all enclosed items". If you encounter problems, in some instances, you may have to set it to 777.

Enabling PHP5 on your server

Most servers have PHP5 installed, but maybe disabled by default. Depending on your server configuration, you may need to add a line of code to the .htaccess file in order to activate it (eg. SetEnv PHP_VER 5). See your system administrator or hosting provider documentation for further assistance.

Getting system information

To help with troubleshooting, visit the following URL on your domain: yourdomain.com/engine/info

Installing within a folder

At this time, you can't install Subfolio within a folder. The entire package content must live at the root of your domain or subdomain.

Uninstalling

Delete or remove it from your server.

Introduction

To find out your Subfolio version or to help with troubleshooting.

Getting system information

Visit the following URL on your domain: yourdomain.com/engine/info.

Disable System Information

If you wish to disable this page, create a blank file called disabled.php and put it here: /engine/info/disabled.php

Introduction

Subfolio is built so that updating is as easy as replacing the /engine/ folder, however sometimes we may tweak the default theme or settings files in order to add additional features. In most cases, we will make it so that theme or setting updates are optional.

An "upgrade" by definition is a more significant release and might affect the way things are done altogether. An upgrade — if needed — will happen only with major releases.

Before you start

• read the release notes (so you know what changes were made and what files were affected)
• make backups

DO NOT UPDATE /directory/

• this is where you keep your files, there will never be an update to this folder

Updating /engine/ (always required)

• rename the existing to "engine_old" and upload the new in its place
• if you've made modifications to the engine, you will need to redo or migrate over your changes manually

Updating /config/settings/ and /config/users/ (optional)

• upload and replace the "sample" files only
• compare your files with the new sample files for new settings (if applicable, see release notes)
• copy new settings from sample to your files as needed

Updating /config/themes/ (optional)

• rename the existing theme to "default_old" and upload the new in its place
• If you've only modified the theme options file, copy it over to the new theme
• compare with the new options.sample.yml file for new options (if applicable, see release notes)
• copy new options from sample to your files as needed
• if you are using a custom theme, you will need to reapply your modifications to the new theme

“Does Subfolio have special hosting needs?”

Nope. Subfolio was made to be drop and go as long as you have the correct system requirements. Of course each server is set-up differently so you might need to see with your system administrator to make a slight adjustment.

“Can I use Subfolio on a shared host or do I need a dedicated server?”

Yes you can. A dedicated server gives you more control of the environment (eg. if you'd like to use special characters in URL's) however all Subfolio features should work within a shared hosting environment.

“What do I need for storage and bandwidth?”

It really depends on you. From this perspective, Subfolio is no different than a normal website. If you are going to use Subfolio as a file server, you should consider a dedicated server with lots of storage. If you are famous and going to use Subfolio for your portfolio website, you should consider a hosting account with high bandwidth allowances.

“What if I don't want it for my main website?”

No problem, we recommend setting up a subdomain such as studio.example.com. Its clean and purdy.

Introduction

OK, you've just arrived to an existential fork in the road. Subfolio can be used in two ways - to share files or to showcase your work. What is the difference you ask?

Sharing mode

Subfolio can be used as a centralized repository to share files within a team — internally, with clients or even in the classroom. By default, Subfolio is configured for sharing mode.

You might want to learn more about:

• Access control

Showcase mode

Subfolio can be used as a portfolio website or just some place to showcase your stuff. Via theme options and settings, you can simply configure Subfolio to be more "website-like". And enhancers will take you the distance.

You might want to learn more about:

• Theme options
• Language settings
• Enhancers

Introduction

There is little-to-nothing you need to know about Subfolio to get started with basic usage. Subfolio is made to be extremely configurable but only if you want. Here are the basic things that most of you will probably want to customize.

Working with YAML: Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Defining the name and url

Go to /config/settings/settings.yml and change the name of your website and the URL.

Adding your logo and favicon

Go to /config/themes/default/options.yml and replace the Subfolio logo path. Can be a full or relative path. Link it from another location or put your logo here: config/themes/default/images/logos/.

You can change the favicon by going here: config/themes/default/images/logos/ and replacing the Subfolio favicon named favicon.png with your custom favicon.

Switching themes

If you are using the default theme, there is nothing to do. But if you have another theme you'd like to use, then put it here: /config/themes/ and then go here: /config/settings/settings.yml and change the theme.

Sharing vs. showcase

OK, you've just arrived to an existential fork in the road. Subfolio can be used in two ways - to share files or to showcase your work. What is the difference you ask?

Sharing mode:

Subfolio can be used as a centralized repository to share files within a team — internally, with clients or even in the classroom. By default, Subfolio is configured for sharing mode.

You might want to learn more about:

• Access control

Showcase mode:

Subfolio can be used as a portfolio website or just some place to showcase your stuff. Via theme options and settings, you can simply configure Subfolio to be more "website-like". And enhancers will take you the distance.

You might want to learn more about:

• Theme options
• General and language settings
• Enhancers

We’ve included a few features within the interface (theme) that hopefully help the user experience.

• Collapse header: conserve window space by removing logo

• Send page: email a link to the page

• Make tiny url: uses tinyurl.com to generate a short URL

• Updated since: option to see content updated since last week, last month or last visit (installs a cookie on users computer)

Working with themes: Subfolio supports interchangeable themes. This means that you can switch the user experience (eg. look and feel) without touching the engine or your files.

Theme options: Most interface elements can be turned on/off within the theme option file /config/themes/default/options.yml

Login and Log out (if applicable)

If a folder is password protected, the user will be prompted to enter their username and password. Once logged in, the user will have access to all folders they have been granted access too — individually or any group they belong too.

• Remember me: If user would like to stay logged in between visits, they have the option to select "Remember me".

• Direct linking: If a file or folder exists within a password-protected folder, user will be prompted to login.

• Access denied: If the user tries to click on a folder they do not have access to, they will get an access denied message.

Important note: A user can see any files and folders that are within a folder they have access too. If you don't want your user to see the other files and folders, then you must give them access only to the folder you wish them to have access too.

Clean URLs

Nobody like long and complex web addresses. They are impossible to remember and hard to share. Subfolio URL's directly match the location of the file. So if you or your client knows the file path, you know the URL. And if you are using Subfolio as a public website, this is great for Search Engine Optimization (SEO) too.

Adding content (pages and sections)

Add your files and folders in the /directory/ folder and Subfolio will instantly turn it into a website — folders become sections, files become pages. You can use any standard file kinds and Subfolio will recognize them automatically. If a file type is not recognized, it will be treated as a generic file kind.

Staying organized

Creating your website structure is just like organizing files and folders on your computer. But don't full victim to folder-structure madness by creating too many folders, it will make your website annoying to navigate. Our rule of thumb is to not create a subfolder unless you have at least 10+ files.

Ordering content

By default, content is ordered alphabetically by filename. Users can click on the column headers to sort by size, date or kind. You can also order content by appending a number (eg. 00, 01, 02, etc.) or date (eg. YY/MM/DD) to the beginning of the filename.

Working with existing file structures

Drop any existing file structure into Subfolio and you are done. Your file structure will remain in tact.

Hiding content

Any file or folder can be hidden by appending a dash - to the beginning of the file or folder name (eg. -folder/ or -image.jpg). It will not appear within the navigation, however it will appear through direct URL (eg. example.com/-hidden).

Working in Draft-mode

If you are working on a new section, hide it with a dash. You can still view it via direct URL and when you are ready to go live, simply remove the dash.

Getting content uploaded to your server

• S/FTP — You can use your favorite S/FTP app to connect to your server and upload files. Hint: some applications allow you to create local dropboxes or local mirrors in order to quickly upload items.

• WebDAV — If you are a group of individuals, we've found it useful to set up WebDAV. If you don't know what this is, basically it allows you to have your server as a local "drive" on your computer. It's great because its always there, its just like moving files on your computer. See your system administrator.

Setting file permissions

Whether you are using S/FTP or WebDAV, it is very important to set permissions on upload to allow "Read, Write, Execute" (777) access and that it applies to all enclosed items.

Tips from the trenches

If using Sufolio as a client studio

Come up with a standard folder-structure that you can duplicate for each client/project.

If many users are adding content

We recommend that you "jail" them into the directory folder and allow access to the engine and config folders only to a select few. See with your system administrator.

Give your local file server an interface

You don't have to use Subfolio over the web. You can install it locally as a "presentation layer" to your existing file server. Just install Subfolio locally and move your existing file structure into Subfolio.

Introduction

You can name your files whatever you want, with a few exceptions. We've strived to make it so that you can work just like you would locally. Unfortunately with the web, there are some limitations. Many of the limitation are ones that you have already learned to live.

Universal characters sets

Subfolio supports all language character sets (Unicode) which will allow you to use Russian, Arabic or Chinese (for example) most anywhere. All settings, enhancer and embedded text files must be encoded as Unicode (UTF-8) for them to work properly.

Using accents and foreign characters without using HTML

As long as your text files are saved as Unicode (UTF-8) and your server configuration supports it, then you don't have to use HTML for accents and special characters.

Using foreign accents in file names

Foreign accents and characters in file names are supported by Subfolio, however they might not be supported by your server. See your system administrator for assistance.

Unsupported special characters in file names

The web just doesn't want you to use certain special characters. We know, its selfish of the web to reserve these rights all for themselves. We've tried to work around this pertinacious behavior so that you can upload your files as they are on your computer. But depending on your server configuration, our workarounds may not work. See your system administrator for assistance.

To be safe, the following special characters should be avoided:

* ' ( ) ; : @ & = + $ , / ? % # [ ]

File extensions

You should use a file extension (eg. .pdf) for all files. Subfolio will work without one, however the file will be unrecognized and won't take advantage of many Subfolio features.

File extensions can be customized in the file kinds settings file at /config/settings/filekinds.yml.

Using spaces in filenames

You can use spaces in filenames, however in the URL, the space will be replaced with %20. We recommend using an underscore _ instead. Subfolio automatically substitute underscores with an actual space within the website interface.

Want to use dashes - instead? Or maybe you'd like to turn this feature off? You can configure many interface behaviors in the theme options /config/themes/default/options.yml.

File naming exceptions

Content in the root of the directory CANNOT be named:

login logout notfound denied

Naming conventions

Since section and page names are pulled from your files and folder names, coming up with good naming conventions is important. If you are using Subfolio as a client studio, document version naming will be important. We have two basic standards: appending a version (eg. -v01); or by appending a date (eg. YYMMDD).

Introduction

This is where Subfolio really shines. as it was made for presenting designs and photography.

Auto-generating thumbnails

1. Upload your image or photo files (thumbnails are for browser-viewable images only).
   
2. Thumbnails will be auto-generated by visiting the folder via web browser
   
3. Generated thumbnails are automatically stored in a folder named -thumbnails/
   
4. To regenerate thumbnails, simply delete the -thumbnails/ folder (or a specific thumbnail within)

Don't make your visitors wait

Since the first visit to a folder with images is the trigger for thumbnail generation — depending on how many images you are trying to process — the first visit to that folder is going to seem a bit slower. As part of your upload process, make it a habit to be the first to visit.

Default thumbnail size

Thumbnails are generated by resizing the original images to 240px height and a variable width (in order to maintain the aspect ratio). No cropping occurs. You can change the default thumbnail size (height only) here: /config/themes/default/options.yml.

Thumbnails for smaller images

If the image file is smaller than the default thumbnail size, then a thumbnail will not be created. Instead, the original image is displayed vertically aligned in a block the size of a default thumbnail.

Creating custom thumbnails

1. Create a folder called -thumbnails-custom within the same folder your images are in.
   
2. Design your custom thumbnails with any size you desire.
   
3. Upload your custom thumbnails to that folder, giving them the same filename as the image it is referencing.

If a -thumbnails-custom folder exists, any thumbnails within will override the -thumbnails folder content.

IMPORTANT: Thumbnail server settings

Thumbnails are generated using something called "GD Library" which is going to use your servers processor to generate the thumbnails. Meaning, if you upload 1,000 20MB images, your server is going to try and process and eventually fail. Each server is different, so you will have to find your servers limits.

By default, images larger than 5MB will not get thumbnails. You can change this setting here: /config/settings/settings.yml.

Introduction

Subfolio inherently has a hierarchical structure, which is somewhat "oldschool" in this day of tags and relational content.

Viewing files

• Files and folders are shown in a standard file browser list or grid view
• List view is sortable by filename, size, date and kind
• Grid view floats and has bigger icons (you can change to grid view in config/settings.yml file)
• Browser-viewable images will have thumbnails and will appear above the file listing
• Browser-viewable file kinds will appear on their detail page
• Files that are new or updated will get a cute little "updated" icon

Navigating files

• Clicking on a file or thumbnail will lead to a unique detail page for that file.
• Navigate from folder-to-folder or file-to-file using previous/next buttons
• Keyboard shortcut for navigation: left/right arrows. The 'T' key scroll the page to the top.
• Navigate via the "breadcrumb" file path
• Go up one level by clicking "Parent Directory"

Downloading files

• Any file can be downloaded from its detail page by clicking on the download link
• Browser-viewable file kinds: click the info icon to get the download link
• Unknown file kind will get a generic icon and be available for download

Customize the experience

Many of the default behaviors listed above can be configured in the settings files. Also, there are many cool things you can use with Enhancers.

Introduction

You can control access on the folder-level by creating users and/or groups and then restricting access to folders.

Working with YAML

Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Creating users

File location

You can edit your user here: /config/users/users.yml

For your reference or to revert to the default settings, there is a sample file here: /config/settings/users.sample.yml

Format

The user information is stored in the following format:

username:
 fullname: Full Name      
 password: yourpassword
 admin: true or false

For example:

john:
 fullname: John Doe
 password: gr8p4ssw0rd
 admin: true

Options

• username: users login name
• fullname: will display in breadcrumb when user is logged in
• password: unsecured plaintext password (see "hashed passwords" for more security)
• admin: by marking this "true", user will automatically have full access

Creating groups

Users can be assigned to one or more groups in order to simplify access control.

File location

You can edit your user here: /config/users/groups.yml

For your reference or to revert to the default settings, there is a sample file here: /config/settings/groups.sample.yml

Format

The group information is stored in the following format:

groupname:
 - username01
 - username02
 - etc.

For example:

clients:
 - apple
 - google
 - etc.

Options

• groupname: name of the group used for access control
• username: must be an existing user

Tips from the trenches

Shared folders

For us, we have certain files that apply to all clients (eg. contact lists, ftp login, etc.). In the root of our studio, we create a folder with access to our client group. And then we create a shortcut from the client folder to the shared folder. This keeps our client folders uncluttered and the client has access to the most up-to-date shared documents.

Groups are sometimes overkill

We really only use 3 groups: clients, freelancers and staff. And for clients, we rarely create a user for a specific person, but for the entire client (eg. if google was a client, we'd just create a user called "google" and then add them to the "client" group).

Introduction

Passwords can be encrypted and stored as hashed passwords instead of unsecured plaintext passwords.

Hashing a password

1. Entering the password here: http://www.yoursite.com/hash/yourpassword
   
2. The page will display the hashed version of the password. Copy it.
   
3. In the user information within the users.yml file, replace the password: option with hashed_password:
   
4. Replace the plaintext password with the hashed version of the password

For example:

john:
 fullname: John Doe
 hashed_password: 5b0fcd785081fa9422fd7b613b540ada
 admin: true

Retrieving a hashed password

You cannot retrieve a hashed password. If the user forgot the password, you will need to rehash a new one.

Introduction

You can allow or deny access to existing users and groups.

Working with YAML

Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Access control for a specific folder

1. Create a plaintext file and name it -access.
   
2. Put it in the folder you'd like to protect
   
3. Add the following code inside it:

Applies to all sub-folders:

allow_users: [username, username, etc]
allow_groups: [groupname, groupname, etc]
deny_users: [username, username, etc]
deny_groups: [groupname, groupname, etc]

Does not apply to sub-folders:

current_folder:
 allow_users: [username, username, etc]
 allow_groups: [groupname, groupname, etc]
 deny_users: [username, username, etc]
 deny_groups: [groupname, groupname, etc]

For example:

allow_users: [john, jane]
allow_groups: [staff]

current_folder:
  allow_users: [clients]

In this example, John, Jane and anyone who belongs to the group "staff" have access to this and all sub-folders. Anyone who belongs to the group "clients" only has access to the current folder.

Access control for a specific file

Unfortunately, this is not possible. Permissions work only on the folder-level. That is, if a user/group has access to a folder, then they can view/download anything within that folder.

Tips from the trenches...

Internal Folders

When setting up your folder structures, consider setting up different folders for different sets of permissions. For example, at AREA 17, we create an internal/ folder within each client/project folder that denies access to the client. So as we are working on something, we post to the internal folder and once we are ready to show the client, we move the work out of the internal folder.

Avoiding Gaffes

If a user/group has access to a folder, they can see all the content of the folder including folder they do not have access too. For example, if you create an internal folder like stated above, the client will see that this folder exists, they just can't access it. So just name your secured folders prudently.

As the expression goes, "measure twice, cut once"

Just because a folder have been secured, that doesn't mean it has the correct security. Often users in a rush may copy a folder structure from one client for another — forgetting to change the -access file. Later you think its secured since you see a little lock ... but really the other client has access to it and the new one doesn't. Doh!

Introduction

Many people want to rank high in search engines, but if you are just putting together a client studio area, then you don't want it scattered on the web, especially showing up in your clients name search results.

Using a robot text file

1. Create a plaintext file called robot.txt
   
2. Put it at the root of your domain (the same location as the /directory/, /config/ and /engine/ folders)
   
3. Add the following code inside it:

# robots.txt for http://www.yourdomain.com/
User-agent: *
Disallow: /

Then, add it to the root of your domain (the same location as the directory/, config/ and engine/ folders).

About robot text files

Learn more at http://en.wikipedia.org/wiki/Robot.txt

Introduction

General settings are where you edit global options (eg. name of site, preferences, etc.).

File location

You can edit your global options and preferences here: /config/settings/settings.yml

For your reference or to revert to the default settings, there is a sample file here: /config/settings/settings.sample.yml

Working with YAML

Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Global Settings

Defining the name and url

Name appears in the header and HTML title of the page. The URL appears in the breadcrumb navigation.

Defining the search engine meta description

You may not know this, but a Subfolio is dangerously SEO friendly ;) Take control of what search engines display by defining your site meta description. Keep it under 195 characters.

If you are trying to keep things private, read the documentation on hiding from search engines.

Adding a website content copyright to the footer

• locate the line # site_copyright: "© 2009 Subfolio — All rights reserved"
• change "Subfolio" to your legal name
• remove the # from the front of the line and it will appear

Adding your Google Analytics code

• locate the line # google_analytics_code: "UA-XXXXXX-X"
• change sample text to your Google Analytics Website Code
• remove the # from the front of the line and it will be activated
• please note that Google Analytics may take a bit to verify it

Content settings

Choosing your markup preference (Textile, Markdown or HTML)

I like textile, you like markdown and that other guy wants HTML. OK, quit your bickering, you can choose your flavor. For use in enhancers files (eg. embedding text, file comments, feature text, etc.).

Setting a max file size for thumbnail generation

Depending on your servers PHP settings, auto-generating thumbnails for very large images may be problematic. This limit allows you to set a cap (we recommend 5MB). You can create custom thumbnails for high resolution images instead.

Other settings

Defining the active theme

You can install and switch themes as often as you'd like, this is where you define which is the active theme.

Defining the location of your content

The default location is /directory/ however you can rename or change it all together. If you have multiple file structures, note that Subfolio will only protect the file structure specified here.

Defining the setting file names

There is probably little reason you'd want to change the name of your settings files, but if you so desire, you can do it here.

Introduction

Whether for language translation or because you don't like our copyrighting, you can change the interface language within the language setting file.

File location

You can edit your global options and preferences here: /config/settings/language.yml

For your reference or to revert to the default settings, there is a sample file here: /config/settings/language.sample.yml

Working with YAML

Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Changing the interface language

Format

The language description are stored in the following format:

    term_or_phrase: display text
    

For example (French):

    download: telecharger
    

Options

See language.sample.yml for all options.

Multi-language

At this time, Subfolio doesn't support multiple language files at one time, however it is being considered as a future enhancement.

Tips from the trenches...

If you translate your language file into another language, change the name of the file by appending the two-letter language suffix (eg. language_fr.yml).

Introduction

You can manage file kinds in the file kind settings.

• Add new file kinds
• Map multiple extensions to one file kind
• Change the display name or icon
• Add viewing/download instructions

File location

You can edit your global options and preferences here: /config/settings/filekinds.yml

For your reference or to revert to the default settings, there is a sample file here: /config/settings/filekinds.sample.yml

Working with YAML

Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Managing file kinds

Format

The file kinds are stored in the following format:

kind:
  extensions: [list, them, like, this]
  icon: kind
  display: Full Name
  instructions:>
    Your instructions here.

For example:

pdf:
  extensions: [pdf, pdf-x]
  icon: pdf
  display: PDF Document
  instructions:>
    You must have a PDF viewer to view this file. Download it Adobe Acrobat Reader.

Options

• kind — a unique identifier for the file kind you are defining
• extensions — contains a list of file extensions variations that should use this file kind
• icon — used to select the image icon that will be shown with this file kind*
• display — used to display the full name within the file listing
• instructions — used to display download or usage instructions on the file detail page

*Icons live in the theme /config/theme/default/images/icons. It is used to generate an image name that varies depending on whether the file has been recently updates, or the folder access is restricted.

Mapping extensions or adding new file kinds

If the file kind exists, however you just need it to recognize a different form of the extension (eg. jpeg instead of just jpg), then simply add the extension to the extension list within the file kind.

If the file kind you want to use does not exist in the list, then just create a new one by following the format listed above.

File kind examples

An example of every file kind that Subfolio supports by default. Download this package if you want to play around and see how each file kind is treated.

Download file kind examples: file_kinds.zip

Introduction

Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Learn more at yaml.org.

Where is it used

Subfolio uses a limited subset of YAML for settings, options and enhancer files.

Commenting within a YAML file

All text following a # character is considered a comment.

Common errors

Indentation, spacing and text case are super important. If something is not working, most likely its because of an indentation, spacing or text case mistake.

• Indentation is important (spaces only, no tabbing)
• Spaces are important (eg. space is different than no space)
• Capitalization is important (eg. “this” is different than “This”)

Important encoding note

YAML files MUST be unicode UTF-8 encoded to work correctly (eg. no Western-Latin, ISO-8859, etc.).

Introduction

Theme options is where you can configure a theme to your desired display preferences.

File location

The default theme location is here: /config/themes/default/options.yml

For your reference or to revert to the default settings, there is a sample file here: /config/themes/default/options.sample.yml

Working with YAML

Option files must be encoded as Unicode (UTF-8) for them to work properly. Option files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Adding your logo

Replace the Subfolio logo URL path with your logo URL path. Use a full path to an external location or a relative path and put your logo here: config/themes/default/images/logos/.

Adding your favicon

Replace the Subfolio favicon URL path with your logo URL path. Use a full path to an external location or a relative path and put your favicon here: config/themes/default/images/logos/.

Remember that your browser will retain the old favicon until you delete it from your browser. See your browser help for instructions on how to delete existing favicons or search Google with "removing favicon for [yourbrowsername]".

Choosing a color palette

You can change or create new color palettes. To learn more, see color palettes documentation

Choosing your default thumbnail size

You can choose the default height and width of your thumbnails. You can also customize thumbnails to a specific size using the custom thumbnail feature.

Choose whether you want locked folders to be hidden or not

If you are using access control, you can opt to hide locked folders from users who don't have access to them.

Choosing your preference for spaces in file names

You can use spaces in filenames, however in the URL, the space will be replaced with %20. We recommend using an underscore _ or dash - instead.

Here, you can choose to automatically substitute underscores or dashes with an actual space within the website interface. It makes the file listings more readable and is especially useful when using Subfolio as a portfolio or public website.

Choosing your preference for how file names are displayed

Do you want to show extensions or hide them? File names under thumbnails or not? Etc. If you are using Subfolio as a client studio, then most likely you want to show all this information, but if you are using it as a portfolio or public website, you may want to keep it simple and hide it all.

Choosing your preference for how files are displayed (list or grid)

Subfolio shows your files by default in a list view. However you can change it to a grid view if you'd like. Grid view uses bigger icons and displays only the comments (if applicable).

Choose your icon set

The default theme comes with three icon sets:

1. list and grid: 8bit icons that work IE6 (default)
   
2. list1 and grid1: 1bit icons that give an old school feel
   
3. list24 and grid24: 24bit alpha icons that display as we intended (preferred)

Choosing your preference for interface elements display

You can turn on/off any of the interface elements and links in the header, footer and file listing, including icons and file names themselves.

Showing your copyright

In /config/settings/settings.yml you can add a copyright. Here you can opt to show it or not.

Introduction

A color palette is a stand-alone yml file that works with a theme. It allow you to change all the colors of the theme without changing the theme itself.

File location (default theme)

The default theme comes with two color palettes (default.yml and dark.yml).

The color palette location is here: /config/themes/default/colors/

Choosing a color palette

1. Go to config/themes/default/options.yml
   
2. Find the color palette option and change (eg. "default" or "dark")
   
3. You don't need to include the extension ".yml"
   
4. Save.

Creating a new color palette

1. duplicate another color palette and rename it (eg. milkywhite.yml)
   
2. Update the main colors (format: '#FF0000')
   
3. Main colors will be used for other secondary colors
   
4. Use the "optional colors" if you'd like to control everything

NOTE: Working with icons

You may need to change your icon set to 1bit or 24bit alpha if using dark background. Or better yet, create your own icon set! You can change icon set in /config/themes/default/options.yml file.

Introduction

A theme is the presentation layer of Subfolio. It is a folder that contains all the interface elements (eg. html, css, images, etc.) so that you can have full control of the look without changing the functionality.

File location (default theme)

Subfolio is prepackaged with the "default" theme however you can install and switch themes as often as you'd like.

The default theme location is here: /config/themes/default/

Switching themes

1. Download additional themes at subfolio.com or support.subfolio.com
   
2. Drop them here: /config/themes/
   
3. Go to: /config/settings/settings.yml and edit theme: default to the new theme name
   
4. Subfolio will now use the new theme, you can change back at anytime

NOTE: Before you switch

A theme is not dependant on the Subfolio engine, which makes it easy to switch themes with ease. However sometimes a specific theme may require changes to settings or the usage of enhancers.

Before you switch themes, it is very important to read the theme release notes, and as always, make backups of your work.

Introduction

You can add your logo, favicon and content copyright in Subfolio.

Working with YAML

Setting files must be encoded as Unicode (UTF-8) for them to work properly. Setting files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Adding your logo

Go to /config/themes/default/options.yml and replace the Subfolio logo path. Can be a full or relative path. Link it from another location or put your logo here: config/themes/default/images/logos/.

Adding your favicon

You can change the favicon by going here: config/themes/default/images/logos/ and replacing the Subfolio favicon named favicon.png with your custom favicon.

Remember that your browser will retain the old favicon until you delete it from your browser. See your browser help for instructions on how to delete existing favicons or search Google with "removing favicon for [yourbrowsername]".

Adding your copyright

1. Go to /config/themes/default/layouts/footer.inc.php,
   
2. Update the copyright line Content ©2009 YourCompanyName — All rights reserved
   
3. Uncomment this line of code (eg. remove the <!-- and the -->) for it to appear

For example:

This:
<!--<span class='copyright'>Content ©2009 YourCompanyName — All rights reserved</span>-->

Should become this:
<span class='copyright'>Content ©2009 AREA 17 — All rights reserved</span>

Introduction

We have gone to great lengths to abstract the presentation layer of Subfolio from the functional layer in order to allow you (and us) to create many different themes for a variety of different purposes.

Default theme: The default theme was built to be simple so that it can act as the base for new themes. Of course the default theme can be used as is or with simple color changes. But you can go nuts and add navigation, graphics, flashy JavaScript, etc.

Customizing your theme

1. Duplicate and rename the default theme
   
2. Change the css, layout and pages as desired
   
3. If you are building a new theme from the ground up, get to know the API's
   
4. When finished, change your theme name here: /config/settings/settings.yml

Theme location

You can find the default theme here: /config/themes/default/

We recommend that you do not modify the default theme, even for small changes. This way you have a clean reference. Always duplicate, rename and change the theme name here: /config/settings/settings.yml.

Structure

• layout/ — global template including the header, footer and previous/next navigation
• pages/ — specific pages, including the listing and file kind modified behaviors
• pages/listing/ — specific pieces of the listing including features, files/folders, thumbnail gallery, inline text/images and related content
• pages/filekinds/ — this is where we modify the default behavior of a specific file kind
• images/ — logos, icons and system graphics. If you other types of graphics, create a new folder
• css/ — the CSS silly
• javascript/ — javascript files, Subfolio uses jquery
• colors/ — location of color palettes
• options.yml — file with all the options for the theme

Options

One of the idea behind Subfolio is that you are not forced into one way of doing things. When working on a new theme, we recommend considering as many of the standard options as possible.

Subfolio API

The Subfolio API is made up of 5 classes:

Subfolio

The Subfolio class can be used to discover information about the Application level settings. It is also used by the other classes, to access global settings.

Functions:

• public static function link_to($text, $url)
• public static function mail_to($text, $email, $subject, $body)
• public static function current_url()
• public static function current_file($data)

SubfolioTheme

The SubfolioTheme class is used to discover information about the current theme.

Functions:

• public static function get_mobile_viewport()
• public static function is_iphone()
• public static function get_page_title()
• public static function get_site_title()
• public static function get_site_name()
• public static function get_view_url()
• public static function get_listing_mode()
• public static function get_notice($name=null)
• public static function get_breadcrumb()
• public static function subfolio_link()
• public static function get_collapse_header_button($wrap="")
• public static function get_tiny_url($name, $wrap="")
• public static function get_option($option_name, $default_value=null)

SubfolioUser

The SubfolioUser class provides information about the user browsing the Subfolio powered website.

Functions:

• public static function is_logged_in()
• public static function current_user_name()

SubfolioLanguage

The SubfolioLanguage class provides acess to the language used by Subfolio, a mechanism for converting Subfolio into the language of your choice.

Functions:

• public function get_text($name, $args = array())

SubfolioFiles

The SubfolioFiles class provides access to the filebrowser component of Subfolio. Find all the files and folders, enhancers and inline elements that make up a Subfolio listing.

Functions:

• public function have_inline_images($type)
• public function inline_images($type)
• public function have_inline_texts($type)
• public function inline_texts($type)
• public function have_features()
• public function features()
• public function have_gallery_images()
• public function gallery_images()
• public function have_files()
• public function files()
• public function have_related()
• public function related()
• public function is_root()
• public function parent_link($name)
• public function previous_link_or_span($name, $directory_name, $link_id, $class)
• public function next_link_or_span($name, $directory_name, $link_id, $class)
• public function updated_since_link_or_span($type)

Engine Customization

If you code PHP and want to change or extend the Subfolio engine, go for it. Just remember that you may no longer be able to take advantage of our updates and upgrades.

Introduction

Subfolio enhancers are simple plaintext files or naming conventions that changes the behavior of files and folders (eg. embedding text or images) or sometimes creates a behavior that normally doesn't exist within a file system (eg. external links, pop-up windows, etc).

How do they work

A file browser is not a website for a reason... its just a list of files. But sometimes you want to do more and that is where enhancers come in.

Their are two types of enhancers:

1. Naming conventions: this is when you append a prefix or suffix to an existing file or folder to change its behavior (eg. add the suffix .site to a folder to turn it into an HTML prototype folder)
   
2. Stand alone plaintext files: this is a snippet of code that does something cool (eg. if you want to feature a folder or put an external link in the file listing)

Where are they stored

Enhancers are stored alongside your content, not in a database or in some global folder. Why? In practice, Subfolio makes it easy to move your files around often and its handy to have them right with the content they belong with. We like to consider enhancers as part of the content. Its like having a link to a website locally on your desktop or organized with some other documents.

Introduction

Here is everything you need to take advantage of enhancers. The package below contains demos of every enhancer file and technique. The easiest way to get started with enhancers is to just copy these files and customize.

Download enhancer demo files

Download: subfolio-enhancers-master.zip

Introduction

Here is a laundry list of all Subfolio enhancers. Keep it handy... or download the enhancer demo files.

Working with YAML

Enhancer files must be encoded as Unicode (UTF-8) for them to work properly. Enhancer files use YAML, a human friendly data serialization standard stored in plaintext files. Indentation, spacing and text case are super important. Learn more at yaml.org.

Embedding images within a folder

Any browser-viewable image can be embedded within a folder (eg. if you'd like to add a logo to the top of the page). There is no limit to how many images you can embed.

• Inline image (top): Top of the page

-t-example.jpg

• Inline image (middle): Immediately before the file listing

-m-example.jpg

• Inline image (bottom): Below the file listing

-b-example.jpg

Embedding text within a folder

Any plain text file can be embedded within a folder (eg. if you'd like to add an introduction to a listing of files). There is no limit to how many text files you can embed.

• Inline text (top): Top of the page

-t-example.txt

• Inline text (middle): Immediately before the file listing

-m-example.txt

• Inline text (bottom): Below the file listing

-b-example.txt

Creating an external link (in the file listing)

• Create a plain text file
• Name it as you'd like
• Add a .link extension

example.link

• Within the file, put the following YAML code:

url: http://www.example.com
target: parent or _blank
comment: an optional comment goes here

• For example:

url: http://www.subfolio.com
target: _blank
comment: This is the Subfolio website

• Put the file where ever you'd like
• External links display in the file listing

Creating a popup (in the file listing)

• Create a plain text file
• Name it as you'd like
• Add a .pop extension

example.pop

• Within the file, put the following YAML code:

url: Destination URL
width: The width of the popup window (default 800)
height: The height of the popup window (default 600)
name: Name to display in the popup window title bar ('My Popup Example')
style: WINDOW or POP or POPSCROLL (default POPSCROLL)

• WINDOW: includes statusbar, menubar, scrollbars and is resizeable.
• POP: no statusbar, menubar nor scrollbars and not resizeable.
• POPSCROLL: no statusbar, menubar not resizeable, scrollbars if content is larger than the pop up width & height For example:
  

url: http://www.example.com
width: 800
height: 600
name: My Popup Example
style: POP

• Put the file where ever you'd like
• Popup links display in the file listing

Creating a website shortcut (in the file listing)

• Create a plain text file
• Name it as you'd like
• Add a .cut extension

example.cut

• Within the file, put the following YAML code:

name: shortcut display name
directory: full location root path

• For example:

name: My explorations
directory: /designs/explorations/

• Put the file where ever you'd like
• Subfolio will add an "also see" header above your shortcut(s).

Featuring a folder

• Create a thumbnail and put it in a folder called -thumbnails-custom
• Create a plain text file
• Give it the same name as the folder (optional)
• Add a .ftr extension

featured_folder.ftr

• Within the file, put the following YAML code:

title: Feature title
folder: Exact folder name
description:>
 Short description you wish to use for the feature.
 You can use textile here.
image: File path and name for feature image
width: 250
height: 230

• For example:

title: My Featured Folder
folder: featured_folder
description:>
 Check out my featured folder, it is so nice. 
image: -thumbnails-custom/folder_thumbnail.png
width: 250
height: 230

• Put the file and thumbnail folder in the same location of the folder
• Subfolio will hide the original folder from the listing
• Features always display at the top of the page

Misc. Hints:

• To hide the title, thumbnail or description, put # in front of that line.
• Default margin is 15px
• Standard size 249x159, however you can do what you'd like

Featuring a file

Follow the same steps as "featuring a folder", except:

• remove the line: folder: Exact folder name
• Add the line: file: Exact file name

Featuring a link (or a specific page)

Follow the same steps as "featuring a folder", except:

• remove the line: folder: Exact folder name
• Add the line: link: http://www.example.com

Creating a slideshow

By default, Subfolio creates thumbnails for all images. But if you'd rather have users skip the thumbnails and go directly to the first image, then you can use a slideshow enhancer.

• Add a .slide extension to any folder
• User will go directly to the first image (or file) in that folder
• User can then use the prev/next navigation to go through your images (or files)

Display an RSS Feed

The RSS enhancer allows you to take any RSS feed from anywhere and display it within Subfolio. It could be used as a stand alone file (eg. example.rss) or as an embedded text file (eg. -t-example.rss).

• Create a plain text file
• Add a -t- or -m- or -b- to the beginning of the filename if you'd like to embed it
• Give it the extension .rss
• Within the file, put the following YAML code:

feedurl: http://feeds.example.com
count: 10
cache: 3600

• Count is the maximum number of items to show
• Cache is number of seconds to cache the feed for
• Note: It may take a minute or so to work for the first time.

Displaying HTML pages or prototypes

• Create a folder
• Name it whatever you'd like
• Add a .site extension

-example_folder.site

• Place your html files within
• The file index.html must exist
• The folder will open in a new window outside of Subfolio

Adding a comment to a folder or file

• Create a plain text file
• Give it the exact same name (including extension) of the folder or file
• Add a .info extension

example.jpg.info

• Within the file, put the following YAML code:

comment: your comment goes here.

• Put the file in the same location of the folder or file

Specifying video properties

Unfortunately, there is no way for Subfolio to detect the properties of a video file. Therefore you need to specify them in the following way. You can also put a standard size for your video files within the file kinds settings file.

• Create a plain text file
• Give it the exact same name (including extension) of the video file
• Add a .info extension

example_video.mov.info

• Within the file, put the following YAML code:

width: width
  height: height
  autoplay: false or true (default false)

• For example:

width: 640
height: 500
autoplay: true

• Put the file in the same location of the video file

Introduction

A markup language is a system for annotating a text in a way which is syntactically distinguishable from that text (eg. HTML, XML). These days we have lightweight markup languages that make it easy to style text without the baggage (eg. Textile, Markdown).

Using markup in enhancers

Markup can be used to style text within enhancers files. Subfolio uses Textile by default, however you can change this to Markdown or HTML in your general settings: _config/settings/settings.yml.

Introduction

Well, you probably have your favorites. But if you don't, here's what we use.

Text Editors (for settings and enhancers)

Mac: The developers are using TextMate and the rest of us are using TextEdit.

PC: The developers are using E-TextEditor and the rest of us are using Notebook.

File encoding note: Make sure your file encoding is set to Unicode (UTF-8).

S/FTP (for uploading content)

Mac: Most of us are using the all-in-one Coda, but some of us use Transmit.

PC: We're using FileZilla ... cause its free and good. Never tried the Mac version.

File encoding note: Make sure your file encoding is set to Unicode (UTF-8).

Web developer tools

We can't live without the Firefox plugin Firebug.

File permissions

Different FTP users may generate different permissions

Make sure your FTP client is set to 777

Allowed memory size exhausted

Problem When your server PHP configuration does not have enough memory to create the thumbnail from the image (based on file size) this will error occur.

Solution You need to see with your system administrator if you can allocate more memory. Otherwise, we have added a setting called thumbnail_max_filesize’ so that Subfolio knows to not try and generate a thumbnail for image files that are larger that your server PHP configuration allows.