App customization

Customizing a ManiVault-based Application

A ManiVault “application” (or viewer) consists of:

• the ManiVault core, plus
• one or more additional plugins.

Additionally, the application designer can customize specific aspects of the app to better suit their use case or organization.

Customization can be done in two ways:

1. From within the UI (recommended for most users), or
2. By editing JSON files in the customization directory.

This section focuses on customizing the application from the UI. The JSON files written by the UI are described along the way and can also be edited manually.

---

Customization directory

All app-specific customization lives in the customization directory. By default, this is:

<app_dir>/Customization

From C++ code, you can query this location via mv::util::StandardPaths.

The directory layout is:

• app.json
  Stores the customization settings generated from the UI (branding, start page, etc.).

• projects.json (optional)
  Lists Project Data Source Names (DSNs) that should be exposed in the app. If present, these projects will be available on the start page and in the projects main menu.

• assets/
  Holds app-specific assets, for example:

  • SplashScreen.html to override the default splash screen.
  • (Future) additional images or HTML fragments for branding.

You can safely commit this directory into your app repo, or ship it alongside the application as part of your distribution.

---

Opening the customization UI

To customize the app from within the running application:

1. Start your ManiVault-based application.
2. Press Ctrl + F8 to open the Customization panel.

The customization UI is divided into three categories:

1. Branding
2. Start page
3. Projects

All changes made here are written to app.json (and projects.json when you edit DSNs).

---

Branding

The Branding category controls where settings are stored and how the application presents itself visually.

Identity and settings storage

These three fields are mandatory and together determine where application settings are stored:

• Organization name
  The human-readable name of your organization (qApp->setOrganizationName(<organization_name>)).

• Organization domain
  Typically a DNS-style domain (e.g. example.org).
  Used (together with the organization name) to build a stable settings path (qApp->setOrganizationDomain(<organization_domain>)).

• Full name
  The full application name that is used for the application identity.
  Internally, this is used as the application name when storing settings (for example via qApp->setApplicationName(<full_name>)).

Note
These three properties are crucial. Changes here will affect the location where ManiVault stores user and application settings. You generally want to set them once when designing the app and not change them afterwards.

Display name and version

• Base name
  A short internal name of the application (e.g. MyViewer).
  This can be used as a concise identifier and is also used as the basis for auto-generating the full name.

• Full name
  By default, the full name is automatically generated from the base name and the app version, e.g. MyViewer 1.2.0.
  This value is mandatory (see above) and can either follow the automatic scheme or be overridden manually.

• Override full name (toggle)
  When enabled, you can manually edit the full name field.
  This is useful if you want a more descriptive marketing name, or if you don’t want the version in the window title.

Visual branding

• Logo
  Lets you select an image used as the app logo.
  Currently, the logo is used on the start page, but this may be extended in future versions.

• App icon editor
  Lets you load a PNG image that is converted into an application icon.

  • You can preview the icon live in different sizes.
  • This does not change the executable’s icon on disk; it affects the icon used within the ManiVault UI (e.g. start page tiles, windows, etc.).

• Convert logo to icon (button)
  Convenience button to convert the current logo directly into an icon, so you don’t have to provide the same asset twice.

Splash screen

• Enable custom splash screen (toggle)
  When enabled, the app uses a custom splash screen from the customization directory.

• Preview splash screen
  Allows you to preview the current splash screen directly from the UI.

The splash screen is typically defined by assets/SplashScreen.html in the customization directory. A splash screen customization tutorial will follow soon.

About dialog text

• Custom “About” text
  Lets you override the default text shown when users go to Help → About.

You can use this to:

• Describe the purpose of your application,
• Add licensing or attribution information,
• Provide links to documentation or support.

The text is stored in app.json and can be plain text or (depending on implementation) a subset of rich text/HTML.

---

Start page

The Start page category gives app designers control over which sections appear on the start page and how dense it looks.

Layout

• Compact (toggle)
  Switches between:
  • A high-density layout (compact) with tighter spacing, and
  • A low-density layout with more whitespace and larger items.

Use this to match the style of your app: compact for expert tools, more spacious for visually guided workflows.

Sections

Each toggle shows or hides a section on the start page:

• Open & Create
  Controls the visibility of actions related to opening existing projects and creating new ones.

• Project databases
  Enables or disables the section that lists projects from configured project DSNs.
  (See the Projects category below for DSN configuration.)

• Recent projects
  Shows or hides the list of previously opened projects, making it quick to resume recent work.

• Project from data
  Toggles the section that allows users to create a new project and load data of a selected type.

• Project from workspace
  Toggles the section for creating a new project from a workspace template
  (Note: not operational at the moment; the UI is present, but functionality may be incomplete).

• Tutorials
  Controls the section listing available tutorials (and optionally related projects).
  This is useful for onboarding new users or guiding them through typical workflows.

All these settings are stored in app.json. Toggling them in the UI is the recommended way to configure the start page, but you can also edit them directly in JSON if you need to automate or script app setups.

---

Projects

The Projects category is where app designers configure Project Data Source Names (DSNs).

When DSNs are configured correctly:

• Projects from those DSNs become available on the start page, and
• They also appear in the Projects main menu inside the application.

The DSN configuration is stored in projects.json in the customization directory. Each DSN describes how to reach a projects repository (local or remote). For full details on remote projects and DSN formats, see:

ManiVault Developer Wiki – Adding remote projects

In short:

• Use the Projects UI category to add/edit DSNs.
• Verify that the DSN settings are valid (URL, authentication, etc.).
• Once saved, the configured project databases become available on the start page when the Project databases toggle (in the Start page category) is enabled.

---

Summary

• The customization directory (<app_dir>/Customization) holds all app-specific settings and assets (app.json, projects.json, assets/…).
• Press Ctrl + F8 in the running application to open the Customization UI.
• Use:
  • Branding to define identity, settings storage, logo/icon, splash screen, and About text.
  • Start page to control which sections the user sees and how dense the layout is.
  • Projects to configure project DSNs that feed into the start page and project menus.

You can either:

• Use this UI to configure your app and commit the resulting customization files, or
• Treat app.json / projects.json as configuration files that you manage alongside your app builds (e.g., for different branded distributions).