====== Folders ======

The folder class represents a folder in the various Indigo user interfaces (Mac client, Indigo Touch, web, etc.).

==== Class Properties ====

^Property ^  Type  ^Description ^
|//''id''//|  integer  |the unique id of the folder, assigned on creation by IndigoServer|
|//''name''//|  string  |the name of the folder - no two folders in the same namespace (i.e. //''indigo.devices''//) can have the same name|
|//''remoteDisplay''//|  boolean  |should this folder be displayed in remote clients (IWS, Indigo Touch, etc)|

==== Commands (indigo.*.folder.*) ====


The commands to manipulate folders are within the object lists defined in the IOM Overview page (indigo.devices.folder.*, indigo.variables.folder.*, etc).

=== Create ===

Create a folder. This method returns a **copy** of the newly created folder.

^  Command Syntax Examples  ^
|<code>indigo.variables.folder.create("Folder Name Here")</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|//''name''//|  Yes  |  string  |the name of the folder|

=== Delete ===

Delete the specified folder.

^  Command Syntax Examples  ^
|<code>indigo.devices.folder.delete(123, deleteAllChildren=True)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer  |id or instance of the folder to delete|
|//''deleteAllChildren''//|  No  |  boolean  |a boolean to specify whether all objects contained in the folder should be deleted as well - defaults to //''False''//|

=== Duplicate ===

Duplicate the specified folder. This method returns a copy of the new folder.

^  Command Syntax Examples  ^
|<code>indigo.controlPages.folder.duplicate(123, duplicateName="New Name")</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer  |id or instance of the folder to duplicate|
|//''duplicateName''//|  No  |  string  |name for the newly duplicated folder|

=== Set Remote Display ===

Use this command to set the remote display flag for the folder.

^  Command Syntax Examples  ^
|<code>indigo.devices.folder.displayInRemoteUI(123, value=True)</code>|
|<code>indigo.schedules.folder.displayInRemoteUI(123, value=False)</code>|

^  Parameters  ^^^^
^  Parameter  ^  Required  ^  Type  ^  Description  ^
|direct parameter|  Yes  |  integer  |id or instance of the folder|
|//''value''//|  Yes  |  boolean  |True to display the folder on remote user interfaces or False to hide it|

==== Examples ====

Since folders aren't available in AppleScript, we're only providing Python examples here.

<code># create a new variable folder
newFolder = indigo.variables.folder.create("My New Variable Folder")

# test to see if a folder exists by Name
if ("My New Variable Folder" in indigo.variables.folders):
    # should execute this because we just created it
    indigo.server.log("folder named 'My New Variable Folder' exists")

# test to see if a folder exists by ID
if (newFolder.id in indigo.variables.folders):
    # should execute this because we just created it
    indigo.server.log("folder id " + newFolder.id + " exists")

# set the remote display flag on the folder immediately
indigo.variables.folder.displayInRemoteUI(newFolder, value=False)

# a ValueError exception with the text "NameNotUniqueError" is thrown if you try to 
# create a folder with a name that already exists
try:
    indigo.variables.folder.create("My New Variable Folder")
except ValueError, e:
    if str(e) == "NameNotUniqueError":
        # should execute this because it's a dup name
        indigo.server.log("folder named 'My New Variable Folder' already exists")
    else:
        indigo.server.log("Some other error")

# NOTE - at this point, newFolder.remoteDisplay is still true (default for new folders)
# because we're still working with a copy. Refresh it to get it updated:
newFolder.refreshFromServer()

# change the name of a folder
newFolder.name="My Variable Folder"
newFolder.replaceOnServer()

# duplicate the folder
indigo.variables.folder.duplicate(newFolder, duplicateName="My Duplicate Folder")

# delete a folder
indigo.variables.folder.delete(newFolder)

#test to see if a folder doesn't exist using name
if ("My New Variable Folder" not in indigo.variables.folders):
    # should execute this because we just deleted it
    indigo.server.log("folder named 'My New Variable Folder' does not exist on the server")

# test to see if a folder doesn't exist using ID (was deleted perhaps)
if (newFolder.id not in indigo.variables.folders):
    # should execute this because we just deleted it
    indigo.server.log("folder id " + newFolder.id + " does not exist on the server")
</code>