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: Options refers to the flat node list coming from the Backend. The Directory element uses this dataset to create the folder and document structure. Therefore, the data structure provided in the Options field must correctly include parent-child relationships.

For each node used in this field, the following fields are typically present:

• id
• name
• parentId
• nodeType

DataTextField: Determines the text field to be displayed on the screen for each Node. By default, the name field is used. If the text to be displayed is stored in a different field in the data source, the relevant field name can be defined via this property.

DataValueField: Defines the field representing each node’s unique identifier. By default, id is used. This field must be unique for selection, event, and binding operations to function correctly.

DataParentField: Defines the field that determines the parent-child relationship between nodes. By default, parentId is used. For records at the root level, this field must be empty or null.

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

Supported example values:

• folder
• document
• virtualFolder
• version
• draft
• temp

Theme: Theme determines the visual theme of the Directory element. Supported values:

• light
• dark

Theme selection is particularly important for readability and visual harmony on screens with dense data.

ShowSearch: When this feature is enabled, a search field is displayed at the top of the Directory element. The search operates on the client side and provides normalization support compatible with Turkish characters.

With this feature, users can:

• folder name
• document name
• matching content path

to perform faster searches.

ShowAddressBar: When this feature is enabled, a breadcrumb structure and navigation controls are displayed at the top of the element. Users can track their current folder path and navigate using the back/forward/up logic.

This feature particularly simplifies navigation in multi-level folder structures.

ClientPageSize: Enables client-side pagination. It can be used to improve performance and readability, especially in folder structures with a large number of nodes.

For example, if the value 50 is set here, a maximum of 50 records are displayed in a folder at any given time. Users can navigate to the next page for additional records.

Style: Used to define style settings to be applied to the Directory element’s container. It can be used for sizing, spacing, alignment, or custom appearance needs.

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.