SpecialFolders | revUp 94

This article shows how to create/update a Rev application that uses the SpecialFolderPath function. In this article I'll show how the Win SpecialFolders Utility file, by Andy Piddock, was updated to support this function on Mac as well as why Rev developers should love SpecialFolders.

SpecialFolders are unique to Revolution. Why? Well, because the "SpecialFolders" name refers to all the known locations of programmatic storage on a computer/server and web. Consider FileMaker (I'm new to Rev, with FileMaker (FMP) experience), where the semi-equivalent Get(TemporaryPath) obtains only the path to temporary storage on Mac and Win, during a given session. During a FMP session, the temporary storage folder location is identified as S(n) where n is the folder number. After considering the breadth of functionality that the Rev SpecialFolders function offers "All the Nooks and Crannies"seemed a good phrase to describe this article. A special thanks to Mark Weider for showing this Rev newbie that a stack on open, will go to the first card.

During my pursuit of learning Rev, I encountered a stack by Andy Piddock which locates and displays all the Win SpecialFolderPaths on one's system. So, part of learning Rev was to convert Andy's stack to also work on the Mac, while becoming familiar with SpecialFolders "Nooks and Crannies".

In pursuing this task, immense help was afforded by Ken Ray's Win and Mac table listings of the associated SpecialFolderPaths, located here.

In Rev, loading or saving of all information via the computer/server/web storage is performed using the

Function SpecialFolderPath nomenclature:

specialFolderPath("Preferences")
set the defaultFolder to specialFolderPath("desktop")
put specialFolderPath("asup") into appSupportFolder

Use the SpecialFolderPath function to place preferences in the Preferences folder, save files to a Temporary folder, etc. .

In Mac OS and OS X systems, a four-character special folder constant is the folderIdentifier .

Originally, this was one stack and one card. Several minor modifications were made to objects on the Win card as well as to some of the stack and card scripts, which are discussed later.

The Mac has 93 SpecialFolderPaths. Numbers 1-93 in the example stack, are only displayed as path identifiers to the user. Four character codes are used in the call: specialFolderPath(aaaa) to identify to the system which SpecialFolder is requested.

The paths shown in the SpecialFolders Utility Mac card are processed as shown by the following browsers:

Firefox puts "http://www.apple" as a prefix to the path to display the path folder contents.

Safari replaces "/Users/{user id}/Desktop/" with "http://www.apple.com/startpage/ in the address field, to display the Desktop folder contents.

Another card was added with most of the same buttons as on the Win card. Since obtaining the SpecialFolderPaths takes longer on the Mac, a Load Progress bar was added for visual feedback to the user. The Mac SpecialFolder paths table has 3 items for each entry: The first item is a number used only for visual feedback to the user, the second item is the Mac 4 character path folder identifier and the third item is the SpecialFolderPath. The "Select SpecialFolders 4 Character Code" button and script was modified to present a list of the codes for user selection. Then, the Mac SpecialFolderPath returned, is automatically entered into the Mac SpecialFolderPath field. Then this path is used by the second part of this card (Get Files List).

The SpecialFolders Utility consists of a stack with two cards, Mac and Win. When the file is opened the message path is to the first card named "Mac". If the platform is "Mac", then the GUI shown in Figure 1 is displayed and the stack awaits user input.

/--
-- Author: Andy Piddock
-- Creation Date:mm/dd/2007
-- Modifier Name:
-- Modification Date: 06/01/2010 
-- About These Scripts:
--   Close Stack
--   Cleanup Fields
--   Get Folder Content
--   Quit Routines
-- History
-- Modifier: William Roger Moseid
-- Date: 06/01/2010
--  Added Script Header
--  Added Andy’s Quit Routines
--/
on closeStack
   //Uncomment if exe made
   //clear_fields
   quitMyProject
   pass closeStack
end closeStack
--
-- Get Folder Contents
function folder_content tFolder, olddir, tFiles
   local olddir
   local tFiles
   
   put the directory into olddir
   set the directory to tFolder
   put the files into tFiles
   set the directory to olddir
   return tFiles
end folder_content

-- Cleanup Fields
function clear_fields
   put empty into fld "FldSFNumber"
   put empty into fld "FldSFPath"
   put empty into fld "fldfileslist"
   put empty into btn "Pulldown Menu"
end clear_fields

--Quit routines
on quitMyProject
   lock messages
   -- Stop using stacks
   put the stacksInUse into myStacks
   repeat for each line myStack in myStacks
      stop using stack myStack
   end repeat
   -- Stacks
   put the openStacks into myStacks
   put "message box,home,tool,Message Box,revTools,revMenubar" \
          & comma & the short name of me into myDontClose
   repeat for each line myStack in myStacks
      if myStack is not among the items of myDontClose then \
             close stack myStack
   end repeat
   -- Messages
   put the pendingmessages into myMsgs
   repeat for each line myMsg in myMsgs
      cancel item 1 of myMsg
   end repeat
   set the backdrop to none
   close me
   if the environment is not "development" then quit
end if
end quitMyProject

The Mac card scripts and GUI are functionally the same as the Win card and have been modified as required in order to function in the Mac environment. The Mac Card scripts follow.

-- Author: Andy Piddock
-- Creation Date: nn/dd/2007
-- About This Script:
--  Populates The Mac SpecialFolderPaths Table
-- History
-- Modifier: William Roger Moseid
-- Date: 04/25/2010
-- Added Script Header & Comments
-- Added Explicit Content Variables (olddir, tFiles) To The
-- function folder_content call
-- Added Platform Check: If Not “Mac” Go To Win Card
--/

-- Get Folder Contents 
function folder_content tFolder 
   put the directory into olddir 
   set the directory to tFolder
   put the files into tFiles 
   set the directory to olddir 
   return tFiles 
end folder_content 
-- Clear Fields
function clear_fields
   put empty into fld "FldSFNumber"
   put empty into fld "FldSFPath"
   put empty into fld "fldfileslist"
   put empty into btn "Pulldown Menu"
end clear_fields

on preOpenStack
   --Uncomment if exe made
   -- Clear_fields
   -- Check Platform
   -- Navigate To Applicable Card
   if "Mac" is not in the platform then
      go card "Win"
   end if
end preOpenStack

// -- Author: Andy Piddock
-- Creation Date: 04/25/2010
-- About This Script:
-- Populates The Mac SpecialFolderPaths Table
-- History
-- Modifier: William Roger Moseid
-- Date: 05/31/2010
-- Added:
--   Script Header & Comments
--   Setup TblSP With Three Items In Each SpecialFolders Row
--  The tSFList Field Is Set To A Menu List of 93 Mac (1-93)
--  Four Character SpecialFolder Codes (Folder Identifier)
--  Changed Comment Of Menu List Number Quantity to 93 
--/

-- Declare Local Variables
local tVarNum

-- Populate Mac SpecialFolderPaths Table
on mouseUp
   put empty into Field "TblSP"
   set the highlight of btn "BtnGetAll" to False
   -- Wait So User Can See Table Clearance
   wait for 1 second
   -- Setup To Obtain Special Folder Path Data
   set the itemDelimiter to tab
   -- Set Loop Value Range For 93 SpecialFolder Paths
   repeat with tVarNum =1 to 93
      --Set SpecialFolderPath Number As First Table Item
      put tVarNum into item 1 of line tVarNum of Field "TblSP"
      -- Set SpecialFolders, 4 Character Code As Second Table Item
      -- The tSFList Field Has The Mac Four Character
      -- SpecialFolders Code List
      -- (Folder Identifier) As Menu Items
      put item 1 of line tVarNum of Btn "tSFList" into item 2 \
             of line tVarNum of Field "TblSP"
      -- Get & Set SpecialFolderPath As Third Table Item
      --  The tSFList Field Is Set To A Menu List of 93 Mac 
      --  Four Character SpecialFolder Codes (FolderIdentifier)
      put specialFolderPath(item 1 of line tVarNum of Btn \
             "tSFList") into item 3 of line tVarNum of Field "TblSP"
      -- Show Load Progress
      set the thumbPosition of scrollbar "Progress Scrollbar" \
             to (tVarNum)
   end repeat
   -- Tell User SpecialFolders Request Completed
   set the highlight of btn "BtnGetAll" to true    
end mouseUp

/-- Author: Andy Piddock
-- Creation Date: mm/dd/2007
-- About This Script:
-- Clears Any Special Folder Path File Names In Field
-- fldfileslist & My Menu (Pulldown)
--  If The Special Folder Path Is Not Empty
--    Filters these variables in tmyfiles (Omit ".DS_Store",
-- ".localized"
--    Puts The Special Folder Path File Names Into Fld
-- "Fldfileslist" & Btn "Pulldown Menu"
-- History
--  Modifier: William Roger Moseid
--  Date: 04/22/2010
--  Added Script Header and Comments
--  Added PickList Approach For Mac 4 Character Codes
-- (SpecialFolderPath Selection)
-- On the Mac Where the Last Character of The Four Character
-- Code Is The ƒ symbol,
-- Is Typed On The Mac Using Option-F
--/

on menuPick theChosenItem
   -- Clear File Names
   put empty into Fld "fldfileslist" 
   put empty into Btn "Pulldown Menu"
   -- Set Special Folder Path, If Any
   put specialFolderPath(theChosenItem) into Fld "FldSFPath"
end menuPick

/-- Author: Andy Piddock
-- Creation Date: mm/dd/2007
-- About This Script:
-- Clears Any Special Folder Path File Names In Field
-- fldfileslist & My Menu (Pulldown)
--  If The Special Folder Path Is Not Empty
--    Filters these variables in tmyfiles (Omit ".DS_Store",
-- ".localized"
--    Puts The Special Folder Path File Names Into Fld
-- "Fldfileslist" & Btn "Pulldown Menu"
-- History
--  Modifier: William Roger Moseid
--  Date: 04/22/2010
--  Added Script Header and Comments
--  Added PickList Approach For Mac 4 Character Codes
-- (SpecialFolderPath Selection)
--/

local tmyfiles
local tmypath


on mouseUp
   -- Clear File Names
   put empty into fld "fldfileslist"
   put empty into btn "Pulldown Menu"
   -- Allow The User To See FileName Clearance
   wait for .5 seconds
   -- Setup Special Folder Path
   set the itemDelimiter to "/"
   -- fldSFPath Has The 4 Character Mac SF List In The
   -- fldSFpath Button Under “Menu List”
   put fld "fldSFPath" into tmypath
   put folder_content(tmypath) into tmyfiles 
   -- Check If Folder Path
   if fld "FldSFPath" is empty then
   else
      -- Clear System Names
      filter tmyfiles without "DS_Store"
      filter tmyfiles without ".localized"
      -- Get Special Folder Path File Names
      put tmyfiles into fld "fldfileslist"
      put tmyfiles into btn "Pulldown Menu"
   end if
   -- Tell User, Request Is Finished
   set the highlight of btn "BtnGetFilesList" to true
end mouseUp

"HomeDrive" is an environment variable that returns the name of your home drive on your hard disk.

The paths shown in the SpecialFolders Utility Win card are processed as shown by the following browsers:

Internet Explorer, Firefox and Safari all require the prefix: "file://" to be added to the path when being used to display the contents of the specified path folder, by the user.

/--
-- Author: Andy Piddock
-- Creation Date: dd/mm/2007
-- Modifier Name: William Roger Moseid
-- Modification Date: 04/27/2010
-- About This Card Scripts
--   Added Script Header, Comments & Function parameters
--   Empties The SpecialFolderPaths Table
--   Clears Applicable Fields
--/

// Get Folder Contents
function folder_content tFolder, olddir, tFiles
   put the directory into olddir
   set the directory to tFolder
   put the files into tFiles
   set the directory to olddir
   return tFiles
end folder_content

-- Clear Applicable Fields
function clear_fields
   put empty into fld "FldSFNumber"
   put empty into fld "FldSFPath"
   put empty into fld "fldfileslist"
   put empty into btn "Pulldown Menu"
end clear_fields

/-- Author: Andy Piddock
-- Creation Date: mm/dd/2007
-- About This Script:
--   Empties The Special Folder Path Table
--   Clears The Filename Lists
--   Puts The Folder Path Code, If Any, In The Special Folder
-- Path Field
-- History
-- Modifier: William Roger Moseid
-- Date: 05/31/2010
-- Added Script Header & Comments
-- Changed Script To A Loop Count of 60 Folder Identifiers
-- (0-59)

--/

-- Declare Local Variables
local tVarNum

on mouseUp
   put empty into Fld "TblSP"
   -- Wait So User Can See Table Clearance
   wait for 1 second
   -- Setup To Obtain Special Folder Path Data
   set the itemDelimiter to tab
   -- Set SpecialFolderPath Number As First Table Item
   put 0 into item 1 of line 1 of Fld "TblSP"
   -- Set SpecialFolderPath As Second Table Item
   put specialFolderPath(0)into item 2 of line 1 of Fld "TblSP"
   -- Set Loop Value Range For 59 Remaining SpecialFolder paths
   repeat with tVarNum =1 to 60
      -- Set Next SpecialFolderPath Number As First Table Item
      put tVarNum-1 into item 1 of line tVarNum of Fld "TblSP"
      -- Set Next SpecialFolderPath As Second Table Item
      put specialFolderPath(tVarNum-1)into item 2 of line \
             tVarNum of Fld "TblSP"
   end repeat
end mouseUp

--  Author: Andy Piddock
-- Creation Date: mm/dd/yyyy
-- About This Script:
--   Uses An Option Button
--    User Selects The Desired Special Folder Path Code From
--    The Button Menu List
--  Clears The Filename Lists
--  Puts The Folder Path Code, If Any, In The Special Folder
-- Path Field
-- History
-- Modifier: William Roger Moseid
-- Date: 05/31/2010
-- Added Script Header & Comments
--  Modified Btn fldSFNumber To Use The Menu List With SF
-- Numbers (0-64)
--//

on menuPick theChosenItem
   -- Clear File Names Lists
   put empty into Fld "fldFilesList" 
   put empty into Btn "Pulldown Menu"
   -- Set Special Folder Path, If Any
   put specialFolderPath(theChosenItem) into Fld "fldSFPath"
end menuPick

/-- Author: Andy Piddock
-- Creation Date: mm/dd/2007
-- About This Script:
--  Clears Any Special Folder Path File Names In Field
-- fldfileslist & My Menu (Pulldown)
--  If The Win Special Folder Path Is Not Empty
--    Puts The Win Special Folder Path File Names Into fld
-- "fldfileslist" & btn "Pulldown Menu"
-- History
--   Modifier Name: William Roger Moseid
--   Date: 05/20/2010
--   Modifications
--   Added Script Header & Comments
--/

local tmyPath
local tmyFiles

on mouseUp
   put empty into fld "fldFilesList"
   put empty into btn "Pulldown Menu"
   set the itemDelimiter to "/"
   put fld "fldSFPath" into tmyPath
   put folder_content(tmypath) into tmyFiles
   put tmyfiles into fld "fldFilesList"
   put tmyfiles into btn "Pulldown Menu"
end mouseUp

The SpecialFolders feature built into Rev, enables Rev developers to quickly and easily modify their stack files in order to take advantage of this functionality. The SpecialFolders Utility.rev (Mac/Win) that was shown in this article can be downloaded here.

In the next article, I'll explore the usage of Custom Functions in conjunction with SpecialFolders to import and export files. Meaning, CustomProperties are used as a container for files. Said files are imported via SpecialFolders into CustomProperties and exported via SpecialFolders to Temporary Storage. The ImportExport Files.rev used for this article will be available for download.

Why? Well, in a following article, I'll show you how to import swf, css, js and html files via these SpecialFolders on Win/Mac into CustomProperties. Then exporting these files to Temporary Storage, use files to render charts in Rev using a revBrowser. The FusionCharts Temporary Path Demo.rev used for this article will be available for download.

This will lead to another article where you, using only your Rev skills, will be able to "bolt on" charting capability for your Rev solutions.