Survey files

IntelliSurvey includes a web-based file management app that supports basic file management operations, as well as the uploading and downloading of customized files (images, proprietary stylesheets, etc.) that are utilized in the online survey. Survey Programmers (SPs) can use the File Manager applet as a general purpose file management tool for maintaining web surveys, as well as a text editor for performing basic file editing tasks of survey files.

For information specifically on using and adding image files with surveys, see Adding images to a survey.

To open the File Manager applet, expand the Structure button group and click Files.

Directories and files associated with surveys

By default, when a survey is created, the following directories/folders are available in the File Manager.

Using the File Manager

The File Manager applet is composed of a two column user interface. The left column shows a list of all files and directories/folders associated with the survey, and the right column is a simple text editor that will display the contents of the file selected in the left column of the page.

The survey's name (survey ID) will be the name of the first folder in the file tree. In the example below, 'images' is the survey name and can be seen as the first folder at the top. The subfolders _s and theme are created automatically, and as of r8.3, the new subfolder images will be created automatically and placed within the _s folder. Once the survey is published, the pub subfolder will be auto-created as well.

Toolbar buttons

The toolbar buttons located in the File Manager applet perform basic actions. 

The following functions can be performed from this screen. Note that some of the buttons/icons located here will change based on whether a file or folder has been clicked upon first.

Creating a new directory or file

To create a new directory/folder, click on an existing directory and then click the Add new directory button . A modal will appear with a text field to enter the name of the new folder. Choose a name with no spaces; underscores are acceptable. After entering the name, click the OK button. The new folder will be created as a subfolder of the existing/selected directory.

To create a new file, click on an existing directory/folder, and click the Add new file button . A modal similar to the Add new directory modal will appear with a text field to enter the name of the file. The name of the file should include both the file name and file extension. After entering the new file name, click the OK button to create the file in the selected folder. 

Renaming a file

To rename a file, click on an existing file and click the Rename file button . A modal will appear with a text field that contains the name of the selected file. Edit the existing file name provided or create a completely new name for the file. After entering the new file name, click the OK button to rename the file. Note, system directories cannot currently be renamed.

Cutting, copying, and pasting files

To move or copy files from one directory/folder or another, you would use the cut, copy, and paste features. For information on how to copy and paste an image directly into survey source code, see Adding an image to a survey.

To move a file, click on a file within the file tree and click on the Cut file button . This will add the file to the system clipboard for moving.

To copy a file, click on a file within the file tree and click on the Copy file button . This will add the file to the system clipboard for copying.

Next, click on a destination directory and then click the Paste file button  to paste the file into that directory.

To make a local copy of a theme file, click on that file within the file tree and click on the Make Local Copy button . This differs from the regular Copy file function in that it automatically moves it from the theme folder into the root theme folder, and also copies any necessary folders/files along with it so that the file copy in the theme directory has the same directory structure as the original file did to the parent directory. Once copied, a notification message will appear to confirm it was pasted successfully.

Editing a file

To edit an existing file, click on the name in the file tree, and the file contents will open in the text editor in the right column. Once the file is opened in the text editor, the file's text contents will be displayed. To revert to the saved version of the file, click the Refresh button  in the text editor's toolbar. The system will prompt to confirm. Clicking the Yes button will refresh the file's contents to the original saved version. Clicking the No button will close the dialog box and return the file to its original state.

When all edits are complete, click the Save button  in the text editor's toolbar. A dialog box will appear asking to confirm. Clicking the Yes button will save the file; clicking the No button will close the dialog box and return the file to its original state.

Deleting a directory or file

To delete a directory/folder, select the directory from the file tree and click the Delete directory button . A dialog box will appear asking to confirm the deletion of the directory. Clicking the Yes button will delete the directory. Clicking the No button will close the dialog and leave the directory in its current location.

Directory and file permissions

Permissions control who is able to access the file within the file system or when users access them via their browsers. Typically, these should be kept as default. Users should keep in mind that altering these permission settings may impact the file's accessibility to survey respondents.

IntelliSurvey is run on Linux (Unix-like) servers and uses the file permissions schemes present in those systems. File or directory permissions on IntelliSurvey systems are managed in three distinct "scopes" or classes. These scopes are known as User, Group, and Others.

• Files and directories are owned by a User. The owner determines the file's Owner class. Distinct permissions apply to the owner.
• Files and directories are assigned a Group, which define the file's Group Class. Distinct permissions apply to members of the file's group. The owner may also be a member of the file's group.
• Users who are not the owner, nor a member of the group, comprise a file's Others Class. Distinct permissions apply to others.
• The effective permissions are determined based on the user's class. For example, the user who is the owner of the file will have the permissions given to the owner class regardless of the permissions assigned to the group class or others class.

Unix-like systems implement three specific permissions that apply to each class:

• The Read permission grants the ability to read a file. When set for a directory, this permission grants the ability to read the names of files in the directory, but not to find out any further information about them such as contents, file type, size, ownership, or permissions.
• The Write permission grants the ability to modify a file. When set for a directory, this permission grants the ability to modify entries in the directory. This includes creating, deleting, and renaming files.
• The Execute permission grants the ability to execute a file. This permission must be set for executable programs, including shell scripts, in order to allow the operating system to run them. When set for a directory, this permission grants the ability to access file contents and meta-information if its name is known, but not list files inside the directory, unless Read is set also.

When a permission is not set, the corresponding rights are denied. Permissions on Unix-like systems are not inherited. Files created within a directory do not necessarily have the same permissions as that directory.

The image below is an example of the permissions that may appear for a file or directory/folder. You may refer to this example for the following description of how permissions are coded.

To check which permissions are already set on a file or directory:

1. Refer to the symbolic notation in the file tree beneath the Permissions column. In the above example, the permissions listed are: rwxrwxr-x.
   

   1. The nine characters are in three sets, each representing a class of permissions as three characters. 

      • The first set represents the User class. In the above example, the users' permissions are rwx.
      • The second set represents the Group class. In the above example, the group's permissions are rwx.
      • The third set represents the Others class. In the above example, the others' permissions are r-x.

   2. Each of the three characters represent the read, write, and execute permissions.

      • r if reading is permitted, - if it is not.
      • w if writing is permitted, - if it is not.
      • x if execution is permitted, - if it is not.
      • Based on the above example, the following permissions exist for this directory. 
        • Users: rwx = reading, writing, and execution permitted
        • Group: rwx = reading, writing, and execution permitted
        • Others: r-x = reading and execution only permitted
2.  Select the directory or file in the file tree and click the Change directory permissions button  or the Change file permissions button . Clicking either of these buttons brings up a permissions dialog corresponding to the selected file. The checkboxes will show the permissions for the directory or file. If the checkbox is checked for a particular class or right, the permission has been set; if it's unchecked, the permission has not been set.

To set or change the permissions for a folder or file, select the item from the file tree and click the Change directory permissions button or the Change file permissions button. Clicking the button brings up a permissions modal corresponding to the selected file.

Check or uncheck the checkboxes for the permissions you would like to apply or change. Once complete, click the OK button to save the permissions. Clicking the Cancel button will close the permissions dialog box and leave the permissions unaltered.

Zip and unzip files

Zipping and unzipping files can help users save time by not needing to upload or download individual files using the  File Manager applet. To zip a file or collection of files or folders, select each from the file tree. To select more than one file, hold the Ctrl key (PC) or ⌘ key (Mac) while clicking on the file or folder.

Once all required files are selected, click the Zip files button to create a compressed zip file containing each selected file. A modal will appear so that the user can add a name for the zip file. Enter the name, then click the OK button to save the new zip file. It is not necessary to add the ".zip" file extension as the system will do so automatically. Clicking the Cancel button will close the modal, and the zip file will not be created.

To unzip an uploaded zip file, select it from the file tree and click the Unzip files button . The system will unzip the zip file's contents into the same directory where the zip file resides.

Uploading a file

The File Manager applet can be used to upload images and other files to the survey file structure. To upload a file, first select the subfolder where the file should live. For images, the recommended folder in r8.3+ is the images subfolder, though users with surveys on earlier releases can still use the _s folder. For all other survey file types, the _s folder is still recommended. When the folder is selected, click the Upload files button from the toolbar.

Note, as of r8.3+, the images subfolder found within the _s folder is created automatically.

After clicking the Upload files button, a modal will appear, prompting the user to add their files.

Users can drag and drop files individually, or as a collection (hold pressing Ctrl (PC) or ⌘ (Mac) if you select multiple, non-adjacent files to drag and drop all at once).

If you decide not to use the drag and drop feature, simply click the Or select files to upload button and navigate to the file(s) you wish to upload. After selecting the file(s), the filename(s) will appear in the modal. Note that the files that you wish to upload are listed in the bottom half of the Upload files modal, meanwhile the initial prompt stays available for additional uploads. Click OK to begin the upload.

When complete, the newly uploaded files will appear in the file tree.

Determining the URL for an uploaded file

Absolute URL for files in the _s folder

To reference files placed in the _s folder, construct a URL following this template:

http://<domain>/s/<survey_id>/<filename>

Note, 's' is not preceded with the underscore in this URL format. Using the above template as a guide, to view the 'my_image.png' file on the hypothetical survey 'my_survey' located on the fictitious server URL 'www.your_research_company.com', you would construct this link like this: ' http://www.your_research_company.com/s/my_survey/my_image.png'.

Absolute URL for files in the images subfolder

Files in the images subfolder will use the following format:

http://<domain>/s/<survey_id>/images/<filename>

Relative file URL

The above example URL uses an absolute file path. An absolute file path describes every step you must take through the file system to end up at the file location, regardless of your starting point. Relative file paths (shorter paths that are relative to your current location in the file system) are allowed as well, and use the following format:

# for files in the _s folder:
/s/<survey_id>/<filename>

# for files in the images subfolder:
/s/<survey_id>/images/<filename>

Again, the difference between the main folder and the subfolder URL is the additional images folder name between '/<survey_id>/' and '/filename/'.

# for files in the _s folder:
<img src="/s/[* appid() *]/image_name.png" />

# for files in the images subfolder:
<img src="/s/[* appid() *]/images/image_name.png" />

Copying a file path to clipboard

This section focuses on adding non-image file links to a survey. For information on copying and pasting file image links into survey source code with the HTML wrappers, see Adding Images to a Survey.

If a survey file or image needs to be referenced in the source code, the Copy Path button can be used to copy the file link, which can then be pasted into the code via the survey editor. Simply click on the file to which you want to provide a link, then click the Copy Path button. The button will temporarily read "Copied!" once clicked upon. The link may then be pasted into the source code by pressing Ctrl + V (PC) or ⌘ + V (Mac).

File paths copied from the _s folder will generally follow this format:

# via Copy Path button
/survey/<survey_id>/_s/<filename>

Using the above template as a guide, to view the 'web-accessibility-checklist.pdf' file on the hypothetical survey 'my_survey', you would obtain a link like this: '/survey/my_survey/_s/web-accessibility-checklist.pdf'.

Downloading files

To download files, select them in the file tree. To select more than one file, press the Ctrl (PC) or ⌘ (Mac). Once all files have been selected, click the Download files button . The system presents a modal to save the files to your computer. The browser will show a separate modal for each file selected, and they will automatically be downloaded to your computer.