1. Overview of the Directory Element

The Directory element is a UI element used to present the folder and document structure within an application in a hierarchical tree view. Especially in Document Management System (DMS) scenarios, it allows users to navigate comfortably between folders and documents using a VS Code-like explorer structure.

Thanks to this element, even if folder and document records from the backend are in a flat data structure, they can be displayed on the screen as a tree structure. Users can open folders, navigate through subfolders, select documents, and track their current location via the breadcrumb trail. This makes multi-layered content structures more organized, readable, and manageable.

The Directory element is supported only in web applications.

1.1. Common Use Cases

The Directory element is commonly used in the following scenarios:

• It can be used to display folders and documents in a hierarchical structure. For example, project folders, department-based documents, or user-specific document archives can be presented using this structure.
• In document management systems, it is preferred to display the folder-document relationship to the user through a file explorer-like experience.
• It is suitable for displaying content that progresses through a category and subcategory logic in structures such as help centers, documentation libraries, or content archives.
• It can be used in scenarios where the user needs to perform an action by selecting a specific folder or document. For example, opening a document’s details, displaying a preview, or listing the contents of the selected folder can be supported by this element.
• In structures requiring breadcrumb-based navigation, it can be used to allow users to see the path of the folder they are in and navigate using the back/forward/up logic.
• In content structures where searches are performed, it provides a more intuitive navigation experience by displaying matching records along with their relevant parent folders.

2. Key Features

The Directory element offers the following key features for managing folder and document structures:

• Provides hierarchical display support. Folders, subfolders, and documents can be displayed in a tree structure.
• A flat node list received from the backend can be converted into a tree structure within the element for use.
• It supports the distinction between folders and documents. This allows the user to easily distinguish which record is a folder and which is a document.
• It offers client-side search support. During search, normalized filtering can be performed while accounting for Turkish character sensitivity.
• In search results, not only the matching nodes themselves but also all parent folders leading to the relevant node can be automatically displayed.
• It works with state management. Open folders (expandedIds) and the selected item (selectedId) are managed in a synchronized manner.
• It provides breadcrumb-based address bar support. This allows the user to see their current hierarchical location and navigate between folders more easily.
• It offers theme support. The element can be used with a light or dark theme.

2.1. Element Settings (Properties)

When you select the Directory element, you can control its data structure and visual appearance via the Properties panel on the right.

The basic properties available for this element are as follows:

‍

Options: This section contains the action and field mapping settings used to retrieve data from the backend. The data source and field definitions required for the Directory element to create the folder/document structure are configured in this section. Subfields:

• Action: Specifies which backend action/service will be used to retrieve the data. This action returns the relevant node list (folders and documents).
• Field to display: Specifies the field to be displayed or used in the node list. It defines which field in the dataset returned by the selected action will be displayed.
• Field to Use as Key: Specifies the field to be used as a unique identifier for each node (e.g., id). This field must be unique for event and binding operations to function correctly.
• Field to Use as Parent: Specifies the field to be used to establish the parent-child relationship between nodes (e.g., parentId). For records at the root level, this field is expected to be empty or null.

Theme: Specifies the visual theme of the Directory element. Supported values: light, dark. The theme selection is important for readability and visual harmony, especially on screens containing large amounts of data.

DataNodeTypeField: Defines the field that specifies the node’s type. By default, `nodeType` is used. This field allows for the differentiation of various node types, such as folder, document, or virtual folder, if applicable.

SelectedNodeType: This field holds the type of the node currently selected by the user (folder, document, virtualFolder, etc.). As the selection within the Directory element changes, this value is automatically updated, and elements bound to this field from the outside can change their behavior based on the type of the selected item (for example, enabling an action button only when “document” is selected).

SelectedVirtualFolder: This field holds the virtual folder the user is currently in or has selected. In virtual folder structures created independently of the physical folder hierarchy, this field is used to track which virtual folder is active or selected.

SelectedLanguage: This field holds the language information of the selected node (specifically, a document). In multilingual document management scenarios, it is used to indicate which language version of the selected document is being viewed or selected.

SelectedIsDraft: A boolean field indicating whether the selected node is in draft status. In document management systems, it is used to distinguish whether the record selected by the user has been published or is still in draft form.

SelectedMimeType: A field that stores the MIME type (file type) information of the selected node. For example, it can take values such as “application/pdf” or “image/png.” It is used to determine preview, download, or action options based on the type of the selected document.

HoverBgColor: Specifies the background color applied to a row when the user hovers the mouse cursor over it. This allows the user to visually distinguish which row they are currently on.

SelectedBgColor: Specifies the background color applied to the selected node row. It is used to visually distinguish the selected item from other items in the list.

SelectedFontColor: Specifies the text color of the selected node. When used in conjunction with SelectedBgColor, it ensures that the background-text color contrast of the selected row is sufficient and readable.

2.2. Event Actions That Can Be Added to the Element

The Directory element has a structure capable of executing actions based on user interactions. When the element is selected, the ADD ACTION button appears, and actions can be defined via specific events.

The event actions available in the Directory element are as follows:

OnNodeSelect: Triggered when the user selects any node in the Directory structure.

This event is used to manage more general selection scenarios. For example, it can be used to display detailed information about the selected node, open related content in a different panel, or filter data based on the selection.

OnDocumentSelect: Triggers when the user selects a document. It is typically used for document-focused operations. For example, the selected document’s detail screen can be opened, a preview can be displayed, a download can be initiated, or additional information about the document can be presented to the user.

OnFolderSelect: Triggers when the user selects a folder. The contents of the selected folder can be listed, subfolders can be displayed, or only documents associated with the relevant folder can be displayed on the screen. It is particularly useful in folder-based navigation scenarios.

2.3. Output (Binding) Values

The Directory element generates various output values based on the selected node and user interactions. These values can be read using the value() function and transferred to other elements via SetValueOf.

Available Binding Values

• nodeId: The unique ID of the selected node
• nodeName: The name of the selected node
• isNodeBranch: Indicates whether the selected node is a folder
• selectedDocumentId: The ID of the selected document
• selectedDocumentName: The name of the selected document
• selectedFolderId: The ID of the selected folder
• selectedFolderName: The name of the selected folder
• selectedVersionId: The version ID of the selected document
• selectedNodeType: Node type (folder, document, etc.)
• selectedVirtualFolder: Virtual folder type (e.g., versions, drafts)
• selectedLanguage: Selected language code (e.g., tr, en)
• selectedIsDraft: Indicates whether the node is a draft
• selectedMimeType: The document’s MIME type

2.4 Virtual Folder Smart Mode

Virtual Folders operate in smart mode. This mode automatically generates different views based on the document’s language and version structure.

• Single-language documents: A flat list is displayed. No subfolders or language tags are created.
• Multilingual documents: Language variants are grouped and displayed. A “Current” folder is created for each language.
• Versions folder: Displayed only when there are 2 or more versions.
• Document Nodes: Enriched with the currentVersionId information. This allows direct access to the active version of the selected document.
• nodeType-sensitive icons: Virtual Folders are displayed with different icons based on the node type. For example:
  
  • version folder → blue
  • draft folder → orange

3. Directory Element Use Case

Document Management on the DMS Main Screen

The Directory element can be used to display the folder and document tree in the left panel of the DMS main screen. In this scenario, the user makes a selection from the tree on the left, and operations are performed on the selected content in the right panel.

Page Initialization Flow

• The GetDocumentTree action is called in the page’s onPageLoad event:
  
  • folderId: empty (starts from the root directory)
  • pageSize: 100
  • hideEmptyFolders: true
• The result of the action is assigned to a variable (e.g., dsDocumentTree).
• The Directory element’s options prop is bound to this variable.

User Interaction

When the user clicks a folder in the tree, the onFolderSelect event is triggered.

• selectedFolderId is updated.
• This value is reflected in the DocumentUploader.folderId field.

When the user clicks a document, the onDocumentSelect event is triggered.

• selectedVersionId is updated
• (document nodes have a currentVersionId field)

The Document element automatically uploads the new version.

Example Action Binding

Page Init:

1. GetDocumentTree → dsDocumentTree

2. Directory.options = dsDocumentTree

Directory.onDocumentSelect:

1. SetValueOf(Document.versionId, Directory.selectedVersionId)

Directory.onFolderSelect:

1. SetValueOf(DocumentUploader.folderId, Directory.selectedFolderId)

4. Best Practices

• When the options array changes (for example, when GetDocumentTree is called again), the tree is automatically refreshed. The component is re-rendered even when the platform creates a new array reference.
• Node IDs are normalized to be case-insensitive. Even if GUID values from the backend are in different formats, the correct match is made.
• In Dashboard mode (design time), the Directory element displays a preview with sample data.

5. Limitations

• If an incorrect options data structure is used, the tree structure will not be created correctly. Parent-child relationships must be defined correctly.
• The Id field must be unique. Otherwise, selection and event operations may fail.
• If ParentId is incorrect, nodes may appear in the wrong position or the hierarchy may be broken.
• If the NodeType is defined incorrectly, the folder/document distinction and related events will not function properly.
• When the options data changes, the element is re-rendered, and the selection/expand state may be reset.
• Search operates only on the client-side. Performance may degrade with large datasets.
• The Virtual Folder structure operates automatically, and manual control is limited.