List Files

Block Group: Data Services
Block Icon:List Files block icon

The List Files block returns a table that lists the contents of a project directory.

For information on using dataflow blocks, see Dataflow.


Input/Output Properties

The following properties of the List Files block can take input and give output.

  • invoke (trigger)
  • enabled (boolean)
  • interval (number)
  • autoRun (boolean)
  • timeout (number)
  • path (string)
  • filter (string)
  • mode (enum or string)

invoke causes the table to be created. The invoke property works only if enabled is set to TRUE.

enabled specifies whether the List Files block is enabled.

  • TRUE—The table is created as specified by invoke, autoRun, and interval.
  • FALSE—The table is not created.

interval specifies how often the table is automatically generated. A value of 0 means that the table is generated on autoRun or invoke only.

autoRun specifies whether the table is generated automatically.

  • TRUE—The table is generated every time any property is changed. The first time that the path property is populated counts as a change.
  • FALSE—The table is generated when the invoke property is triggered, or at the specified interval.

timeout specifies how long the List Files block will attempt to create the table before the request is canceled.

path specifies the directory for which to create a table. You can populate this field by dragging and dropping. For example, to specify the assets folder, drag the assets folder from the Project panel to this field.

Note

To specify the root project node, click in the path property field and then press Enter or Return.

filter specifies a string that file names must include in order to be listed. For example, this string could be a file extension. Directories are not filtered by this property and are always included in the output if mode is All or Directories.

  • To list only PNG files, enter png.
  • To list all files, leave this field blank.

mode specifies whether the output table lists only files, only directories, or both.

  • All—Files and directories are listed.
  • Files—Only files are listed.
  • Directories—Only directories are listed.

Output Properties

The following properties of the List Files block can give output but cannot take input.

  • loading (boolean)
  • output (table)
  • onComplete (event)
  • error (string)

loading returns whether the list is currently loading.

output returns a table that lists the contents of the specified directory. The table includes the following fields:

  • name: the filename or directory name.
  • path: the path of the item, relative to the root.
  • isDirectory: TRUE if the item is a directory, FALSE if it is a file.
  • created: 0, if the item is a directory. The serial number for the creation date and time, if it is a file.
  • modified: 0, if the item is a directory. The serial number for the last update date and time, if it is a file.

onComplete fires when the table finishes loading.

error returns the error message, if any.


About the Output Table

The output table of the List Files block is only one level deep. Therefore, when one of the table records is a directory, the directory is represented with a name, not a table. You can use multiple List Files blocks to retrieve deeper lists.

For the created and modified columns in the output table, you can parse or format the date time serial numbers using a Parse Date Time or Date Format block.


Example

The following image shows an example of the List Files block. In this example, the block returns a table of files in the “Piping” directory whose names contain the string “valve”.

List Files dataflow model