Documentation

Persistent Objects

Persistent Objects in Vidyano are utilized to represent various data structures, including:

• Tables: Directly mapping to database tables.

• Collections: Representing groups of related items.

• Entities: Defining individual records or objects.

• Virtual Forms: Describing forms with a set of fields without a direct database mapping.

Key Features

• Flexibility: Capable of representing both physical and virtual data structures.

• Customization: Allows for the definition of fields, relationships, and behaviors tailored to specific needs.

Use Cases

• Data Representation: Managing complex data structures within the application.

• Form Design: Creating virtual forms to capture and process user input efficiently.

Persistent Objects are a fundamental component of Vidyano, providing a versatile mechanism for data management and interaction.

---

Queries

Queries in Vidyano are used to retrieve and display data in various ways. There are three primary types of queries:

Context Property Queries

These queries map directly to a property on the context, typically representing entire database tables. They are straightforward and provide a direct view of the underlying data.

Detail Queries

Detail queries are used to fetch data related to a specific entity. They display records based on their parent entity, allowing for a focused view of related data.

Custom Queries

Custom queries offer the most flexibility, allowing developers to implement complex business logic in code. These queries can filter data, retrieve information from external services, or provide customized views tailored to specific needs.

Each type of query serves distinct purposes and provides a powerful mechanism for data retrieval in Vidyano.

Examples

public partial class ProductActions
{
    public IQueryable<Product> ActiveProducts(CustomQueryArgs args)
    {
        return Context.Products.Where(p => p.IsActive);
    }
}

---

Persistent Object Attributes

Attributes in Vidyano represent individual fields within a Persistent Object. They can be:

• Linked Attributes: Directly connected to a class property.

• Virtual Attributes: Used in code but not mapped to a database field, ideal for scenarios like contact forms or additional processing options.

Attributes contain detailed metadata such as:

• Name: The identifier for the attribute.

• Data Type: Specifies the type of data (refer to the Data Types section for more details).

• Position: Determines its placement in the interface.

• Group/Tab: Indicates which group or tab the attribute belongs to.

• Label: A translatable label for user-friendly display.

• Business Rules: Associated validation rules.

Attributes also have customizable hints, such as displaying a dropdown as a select box or radio buttons. This flexibility allows developers to create intuitive and user-friendly interfaces.

---

Data Types

Vidyano supports a range of built-in data types to represent different kinds of information:

• Primitive Types: Includes basic types like string, integer, datetime, and datetimeoffset.

• Multiline String: Provides a text area for users to input large amounts of text.

• Multivalue String: Allows users to enter multiple lines of text that can be reordered.

• Combobox and Dropdowns: Enables selection from a predefined list, with options to add new values.

Developers can also create custom data types to represent specific business needs:

• Custom Data Types: For example, an IBAN bank account number or a phone number. These can be reused across the application and have specific logic for display and input.

Data types dictate how information is presented, whether in a persistent object or within a query. For instance, an Image Data Type might display the image directly in a query, while in edit mode, it allows users to upload or paste a new image.

This flexibility enables developers to tailor the application to specific requirements.

---

Business Rules

Business Rules in Vidyano allow you to enforce predefined validation rules across your application. Some of the built-in rules include:

• NotEmpty: Ensures that a field is not left empty.

• Required: Mandates that a field must be filled.

• Min/MaxValue: Sets minimum and maximum values for numeric fields.

• IsEmail: Validates if the input is a properly formatted email address.

In addition to these, developers can write custom business rules in C# to handle more complex validation logic. This involves:

• Custom Validation: Writing code to evaluate the data input by the user and determine if it meets the required criteria.

• Error Messaging: Displaying validation error messages when the input does not comply with the rules.

Business Rules provide a robust mechanism for maintaining data integrity and ensuring consistent validation throughout the application.

// No arguments, rule can be used as "NotEmpty"
public static string? NotEmpty(BusinessRulesArgs args, string value)
{
    if (string.IsNullOrWhiteSpace(value))
        return "{0} cannot be empty.";

    return null;
}

// With arguments, rule can be used as "Between(0, 100)"
public static string? Between(BusinessRulesArgs args, decimal value, decimal min, decimal max)
{
    if (value < min || value > max)
        return "{0} must be between {1} and {2}.";
    return null;
}

---

PersistentObjectActions

The Actions class in Vidyano is linked to specific Persistent Objects and is crucial for implementing custom logic, named following the [PersistentObject]Actions convention. Key functionalities include:

• Custom Logic: Execute code when an entity is loaded, created, saved, or deleted.

• Query Execution: Add logic when executing queries, enhancing data processing.

• Versatile Methods: Provides various methods to handle different stages of an entity's lifecycle.

This class is widely used for customizing application behavior, providing developers with powerful tools to manage

The Legacy v5.x also contains relevant information about Actions classes.

---

Custom Actions

Custom Actions in Vidyano are user-defined actions, typically represented as buttons, that can be placed on Persistent Objects or Queries. They provide a flexible way to extend functionality.

Key Features

• Role-Based Visibility: Custom Actions can be controlled via user roles, allowing developers to specify when and where these actions are visible.

• Contextual Behavior: On a Query, actions can be configured to require conditions, such as

Examples of Using Custom Actions

Custom Actions can be used for a variety of tasks within Vidyano. Here are a few practical examples:

• Send Email Action: This action can be used to send an email to a selected customer. When triggered, it opens a predefined email template and sends it to the customer's email address.

• Import Data Action: This action can be placed on a customer query, allowing users to import data from a file. When the import button is clicked, a dialog appears for selecting a file, and the data is imported accordingly.

  public partial class Import : CustomAction<ProjectTargetContextType>
  {
      public override PersistentObject Execute(CustomActionArgs e)
      {
          return Manager.Current.RegisterImport(e.Query?.PersistentObject ?? e.Parent!, accept: ".xlsx");
      }
  }
  
  public partial class EmployeeActions
  {
      public override void OnImport(ImportArgs e)
      {
          var sheet = e.ReadAsExcelSheet();
      }
  }

• Download Action: This action allows users to export download data for a specific Employee. When the user clicks the Download button, the data is fetched and will show a download dialog in the browser to save the result.

  [Description("""
             Allows to download a file from the server.
             """)]
  public partial class Download : CustomAction<ProjectTargetContextType>
  {
      /// <inheritdoc />
      public override PersistentObject Execute(CustomActionArgs e)
      {
          e.EnsureParent(Types.Employee);
  
          // This will inform Vidyano to call the OnGetStream method on EmployeeActions.
          return Manager.Current.RegisterStream(e.Parent);
      }
  }
  
  public partial class EmployeeActions
  {
      public override Stream OnGetStream(GetStreamArgs e)
      {
          return e.GetText(e.Key, "Employee.txt");
      }
  }

These examples illustrate the versatility of Custom Actions, enabling developers to extend Vidyano's capabilities to meet specific business needs.

---

Menu

The menu in Vidyano provides a structured way for end users to navigate through the application. It consists of:

• Program Units: Higher-level items in the menu that can be easily shown or hidden based on user rights. Each application can have multiple program units.

• Program Unit Items: These are links within a program unit and can point to a query, a persistent object (e.g., an account page), or even an external URL.

The entire menu system is driven by user rights, ensuring users only see the options they have access to. Additionally, developers can implement hooks to further control the visibility of program units or dynamically add new values.

This system offers a flexible way to organize and manage the application's navigation, enhancing user experience.

---

Web API Hooks

Vidyano allows you to extend your application by adding custom API methods. Each application comes with a predefined web file, named using a specific naming convention ([schema]Web), which acts as a built-in API controller.

Key Features

• Custom Methods: You can add methods that are accessible via the /api/[methodName] endpoint.

• Flexible Authentication: API methods can be configured to require authentication, support anonymous access, or use custom authentication mechanisms.

• ApiArgs: Each method receives an ApiArgs argument, providing various request details.

• Standard ASP.NET Core: Use the standard IResult interface for returning results, compatible with ASP.NET Core helper methods.

public IResult Ping(ApiArgs args)
{
    return Results.NoContent();
}

This system offers a flexible way to extend your application's functionality, allowing you to handle various scenarios and integrate external services seamlessly.

---

Settings

Vidyano provides a variety of settings that can be configured to tailor the application to specific needs. These include:

• Built-in Settings: Accessible from the management interface, these settings cover a range of configurations, such as:

  • SMTP Configuration: For managing feedback or email sending settings.

  • Default Language and Culture: Setting the application's default language or cultural preferences.

• View Preferences: Configuring how persistent objects are displayed, such as master-detail or full-page views.

• Custom Settings: Developers can create and manage custom settings, which can be fetched and set via code. These settings are environment-specific, allowing different configurations for production, staging, and development environments.

These settings provide a flexible mechanism to customize the application behavior, from basic configurations to more complex feature toggles and external service settings.

// Get a setting
var enabled = Manager.Current.GetSetting("FlagEnabled", false);
var retries = Manager.Current.GetSetting("NumberOfRetries", 5);
var url = Manager.Current.GetSetting("ExternalUrl", "https://service/api/");

// Set a setting
Manager.Current.SetSetting("LastSync", Manager.Current.NowOffset);

The Legacy v5.x documentation also contains relevant information about Overriding Vidyano Settings.

---

Logging

Vidyano includes a built-in logging system that records events and errors, storing them in the database (SQL or RavenDB). Key features include:

• Automatic Logging: The application logs important events automatically, such as metadata synchronization, incorrect sign in attempts or faults.

• Error Logging: Records exceptions and faults, providing developers with detailed information during development and troubleshooting.

• Custom Logging: Developers can add custom logs via code, useful for tracking specific events or processes.

• Updateable Logs: Supports appending to logs during long-running processes, allowing continuous tracking and insight into process execution.

This robust system ensures that developers have comprehensive insights into application behavior and can quickly identify and resolve issues.

// Log an exception with detail information
ServiceLocator.GetService<IExceptionService>().Log(ex);

// Or as a warning
ServiceLocator.GetService<IExceptionService>().LogWarning(ex);

// Logged exceptions will contain:
// - Message/Type/Source
// - Data
// - All inner exceptions recursively

// Log
Manager.Current.Log("Message", LogType.Information);
// Will also log the User that was currently logged in
// For background jobs we can pass any user
Manager.Current.Log("Job failed", LogType.Error, adminUser);

// Updateable log
using var log = Manager.Current.UpdateableLog("Message", LogType.Custom);
// do some processing
log.AppendLine("Extra information");
log.ChangeType(LogType.Warning);
log.Prepend("Finished at ..."); // Makes it easy in the Logs view to see this part
log.Delete(); // if the log isn't relevant you could clean it up

/// <summary>Describes the type of logging.</summary>
public enum LogType : byte
{
  /// <summary>An error has occurred.</summary>
  Error,
  /// <summary>The synchronization process has logged something.</summary>
  Synchronization,
  /// <summary>A security related entry has been logged.</summary>
  Security,
  /// <summary>A custom entry has been logged.</summary>
  Custom,
  /// <summary>A warning entry has been logged.</summary>
  Warning,
  /// <summary>An information entry has been logged.</summary>
  Information,
  /// <summary>A licensing entry has been logged (Legacy).</summary>
  Licensing,
}

Verbose Logging

Vidyano also supports a verbose logging concept, where all requests are logged automatically with detailed information. This feature is invaluable for advanced troubleshooting and collecting metrics, allowing developers to gain deeper insights into application performance and user interactions.

---

Advanced Topics

Authenticator Service

The Authenticator Service in Vidyano is based on a naming convention ([schema]AuthenticatorService) and extends the base Authenticator Service class. This class is crucial for mapping users and verifying credentials. Key functionalities include:

• Default Authentication: Uses BCrypt-encrypted passwords stored in the database.

• External Providers: Supports integration with external authentication providers like Azure AD, Google, and Microsoft.

• Custom Authentication: Allows implementation of custom password logic.

• Group Membership: Determines user group memberships and supports various authentication customizations, including header-based authentication.

The Authenticator Service provides extensive flexibility, enabling developers to tailor authentication processes to specific requirements.

Check the legacy v5.x documentation about configuring Azure AD SAML based authentication.

Advanced Base Class

Vidyano includes an advanced class, named using a specific naming convention ([schema]Advanced), that provides numerous hooks to extend or modify built-in features. While these hooks are less frequently used, they are invaluable for specific scenarios.

The Advanced class is ideal for developers needing fine-grained control over the application's behavior.

Courier Messaging

See related document Courier Feature, can be used in RavenDB for message based communication.

---

Context

The Context class in Vidyano is a core component used for database interactions. Named following the [schema]Context convention, each application has at least one Context class. Key features include:

• Database Interaction: For SQL Server, it's based on Entity Framework's DbContext. For RavenDB, it wraps the IDocumentSession.

• Scoped Service: A single instance per request, used across the application.

• Data Management: Provides properties for tables or collections and includes helper methods to add, remove, and save changes.

• Custom Contexts: Developers can implement their own Context classes if needed.

The Context class is essential for managing data access and interactions, providing a flexible and powerful way to handle database communication.

---

Custom UI

Vidyano offers a default user interface out-of-the-box, allowing you to run applications without writing HTML or JavaScript. However, you can create custom components for specific needs, such as new data types or unique UI elements.

Custom UI is particularly useful for:

• New Data Types: When adding new data types, you can design custom UI components.

• Unique Requirements: For cases where the built-in UI doesn't meet your needs, custom components allow full control over the interface.

This flexibility ensures you can tailor the user experience to your application's unique needs.

Source code is available on https://github.com/Vidyano/vidyano together with a sample Vidyano application to showcase the different data types.

---

Samples

This section provides a collection of sample projects and code snippets to help you understand various use cases. These samples are designed to be downloaded and run, offering practical examples of how to implement different features in Vidyano.

While the full details are found in the code, the documentation highlights:

• Common Use Cases: Real-world scenarios demonstrating key Vidyano features.

• Code Examples: Sample code illustrating how to achieve specific tasks.

• Downloadable Projects: Ready-to-run projects you can explore and adapt.

These samples serve as a practical reference, helping you to quickly grasp how to leverage Vidyano's capabilities in your own projects.

Sample Projects

1. Web3: https://github.com/Vidyano/vidyano Web3 is a sample Vidyano application that showcases various data types and custom UI components. It provides a comprehensive overview of Vidyano's capabilities and how to implement them in your projects.
2. VidyanoRavenSample: https://github.com/2sky/VidyanoRavenSample A sample project demonstrating how to use RavenDB with Vidyano. It includes a basic setup and configuration to get you started with RavenDB in Vidyano.

---

Tips and Tricks

Vidyano offers several developer-centric features to enhance productivity:

• Profiler: Open the profiler while the application runs in the browser to view details of requests, including methods called, parameters, database calls, and performance metrics.

• Control + Right-Click: Use this shortcut to open a pop-up menu for quick navigation within the management interface.

• Impersonation: Test various user roles by impersonating users without needing to log in separately.

These features streamline development and testing, making it easier to manage and optimize your Vidyano applications.

---

This document provides a structured guide to working with Vidyano. For further details, explore each section and refer to the provided code snippets.