External Configuration

Introduction

This document will describe how to deploy TagSpaces Pro and Enterprise with predefined configuration such as custom logo and color, tag library or locations.

For exchanging the application logo the ExtLogoURL parameter should be used. A valid values can be an URL:

window.ExtLogoURL = 'https://www.tagspaces.org/content/text-logo.svg';

or a relative path the file containing the logo:

window.ExtLogoURL = 'custom-logo.png';

Valid file formats are JPG, GIF, PNG and SVG. The maximum height of the logo should 50px.

Disabling the onboarding dialog and the license confirmation

The property ExtIsFirstRun can be used for disabling the initial onboarding dialog and license confirmation.

window.ExtIsFirstRun = true;

Switching desktop and mobile mode of the app

The property ExtDisplayMode can be used for switching between the desktop and mobile mode of the app.

window.ExtDisplayMode = 'mobile';

Possible values are 'mobile' and 'desktop'.

Configuring custom locations

With this feature TagSpaces can be deployed with a set of predefined location, which could point to local folder or object store buckets hosted for example on AWS S3. The configuration property responsible for this feature is called ExtLocations.

This an example for connecting an AWS S3 bucket as location:

window.ExtLocations = [
  // an array containing one or many locations
  {
    uuid: "10565f09-c7fd-2333-fc67-a75db27rt5ba", // an inique id of the location
    type: "1", // 1 defines the locations a cloud based
    name: "The name of the cloud location", // the name of the location
    paths: ["demo"], // the path to sub folder in the location
    accessKeyId: "your_access_key", // the access key of the user
    secretAccessKey: "your_secret_key", // the secret case of the user
    bucketName: "demo-bucket", // the name of the S3 bucket
    region: "eu-central-1", // the AWS region
    isDefault: true, // if true this location will be loaded by the application start
    isReadOnly: true, // if true the user interface of the application turns to read-only mode
    persistIndex: false, // if true the search index will be persisted and loaded by default on location opening
    fullTextIndex: false, // activated the full-text search for TXT, MD and HTML files
    watchForChanges: false, // activates the watching for changed files in the current location
  },
];

The following snipped is an example for connecting a local folder as location:

window.ExtLocations = [
  // an array containing one or many locations
  {
    uuid: "53453458-c7fd-2333-fc67-a75db27rt5ba", // an unique id of the location
    type: "0", // 0 defines the location as local
    name: "The name of the local location", // the name of the location
    paths: ["/var/mnt/data/"], // the path pointing to the local folder
    isDefault: true, // if true this location will be loaded by the application start
    isReadOnly: true, // if true the user interface of the application turns to read-only mode
    persistIndex: false, // if true the search index will be persisted and loaded by default on location opening
    fullTextIndex: false, // activated the full-text search for TXT, MD and HTML files
    watchForChanges: false, // activates the watching for changed files in the current location
  },
];

Disable the editing of the locations

The editing of the locations can be disabled with the following property: ExtLocationsReadOnly

Note: This switch is not supported anymore. Now as soon as you have externally configured locations they are automatically read-only.

Configuring custom tag library

With this feature TagSpaces can be deployed with a set of predefined tags distributed in tag groups. The configuration property responsible for this feature is called ExtTagLibrary.

The following code snipped shows how to define one tag group containing one tag as a predefined tag library

window.ExtTagLibrary = [
  // an array containing one or many tag groups
  {
    uuid: "17882854-44a7-4b2d-a2b1-b022846ac41d", // an unique id of the tag group
    title: "Common Tags", // the name of the tag group
    color: "#008000", // the default background color of the tags in this group
    textcolor: "#ffffff", // the default text color of the tags in this group
    children: [
      // an array containing one or many tags
      {
        id: "ff47282f-a7cc-474c-951f-4636d60c0529", // an unique id of the tag
        type: "plain", // the type of tag, just leave it plain
        title: "book", // the name of the tag
        description: "", // a optional description for a tag
        color: "#008000", // the background color of the tag
        textcolor: "#ffffff", // the text color of the tag
      },
    ],
    expanded: true, // should be true in order this tag group to be visible in the application
  },
];

Including the tag library in the config

  • Start the export process from the three dot menu of the tag library
  • From the export dialog choose which tag groups you want to export
  • Click the Export button and choose where the exported json file should be saved
  • Open the exported json file in text or json editor. TagSpaces has an integrated JSON editor, which can be used too.
  • Edit the json files if needed
  • Copy the part shown in the next snipped, to the window.ExtTagLibrary array in the extconfig.js
  • Save the changes in extconfig.js

Explanation which part of the code should be copied.

    {
        "appName": "TagSpaces",
        "appVersion": "3.1.5",
        "settingsVersion": 3,
        "tagGroups": [
            // Copy everything from here to window.ExtTagLibrary = [ here ]
        ]
    }

User interface tweaks

Open app with predefined perspective

window.ExtDefaultPerspective = 'gallery';

Possible values as of version 3.3.x are 'default', 'gallery', 'mapique'

Show vertical panel on startup

window.ExtDefaultVerticalPanel = 'none';

Possible values: 'none', 'taglibrary', 'search', 'locations'

window.ExtShowAdvancedSearch = true

Possible values: true, false Default value: true

Show welcome panel

window.ExtShowWelcomePanel = true

Possible values: true, false Default value: true

Show smart tags

window.ExtShowSmartTags = true

Possible values: true, false Default value: true

Choose startup theme

window.ExtTheme = 'dark';

Possible values: 'dark', 'light'

Custom color for the default themes

Set custom sidebar color

window.ExtSidebarColor = '#2C001E'

Possible value: any css color

Default value: '#2C001E'

Set custom sidebar selection color

window.ExtSidebarSelectionColor = '#880E4F'

Possible value: any css color

Default value: '#880E4F'

Set custom light color for the light theme

window.ExtLightThemeLightColor = '#dcf3ec'

Possible value: any css color

Default value: '#dcf3ec'

Set custom main color for the light theme

window.ExtLightThemeLightColor = '#1dd19f'

Possible value: any css color

Default value: '#1dd19f'

Set custom light color for the dark theme

window.ExtDarkThemeLightColor = '#56454e'

Possible value: any css color

Default value: '#56454e'

Set custom main color for the dark theme

window.ExtDarkThemeMainColor = '#ff9abe'

Possible value: any css color

Default value: '#ff9abe'

Modifying packages

  • Unzip the packaged
  • Copy in resources/app folder the the file extconfig.js
  • Copy in resources/app folder the custom logo of the app. This is an optional step, for the case where you have specified the logo as a relative path.
  • Zip the unzipped folder containing the tagspaces program files
  • Distribute and/or deploy it

Example configuration file

Here you will find the whole configuration file, so it can be easily copied and reused for your custom needs.

window.ExtLogoURL = "https://www.tagspaces.org/content/text-logo.svg";

window.ExtIsFirstRun = false;

window.ExtDefaultPerspective = "gallery";

window.ExtTheme = "dark";

window.ExtLocations = [
  {
    uuid: "10565f09-c7fd-2333-fc67-a75db27rt5ba",
    type: "1",
    name: "The name of the cloud location",
    paths: ["demo"],
    accessKeyId: "your_access_key",
    secretAccessKey: "your_secret_key",
    bucketName: "demo-bucket",
    region: "eu-central-1",
    isDefault: false,
    isReadOnly: true,
    persistIndex: false,
    fullTextIndex: false,
    watchForChanges: false,
  },
  {
    uuid: "53453458-c7fd-2333-fc67-a75db27rt5ba",
    type: "0",
    name: "The name of the local location",
    paths: ["/var/mnt/data/"],
    isDefault: true,
    isReadOnly: true,
    persistIndex: false,
    fullTextIndex: false,
    watchForChanges: false,
  },
];

window.ExtTagLibrary = [
  {
    uuid: "17882854-44a7-4b2d-a2b1-b022846ac41d",
    title: "Common Tags",
    color: "#008000",
    textcolor: "#ffffff",
    children: [
      {
        id: "ff47282f-a7cc-474c-951f-4636d60c0529",
        type: "plain",
        title: "book",
        description: "",
        color: "#008000",
        textcolor: "#ffffff",
      },
      {
        id: "c3fa72f5-afde-4d2e-af14-bdebb6782a71",
        type: "plain",
        title: "article",
        description: "",
        color: "#008000",
        textcolor: "#ffffff",
      },
    ],
  },
  {
    uuid: "e21711da-ee78-4c83-bae3-e0007fe426a3",
    title: "Priorities",
    color: "#008000",
    textcolor: "#ffffff",
    children: [
      {
        id: "dca64cf4-79e2-4450-a57b-b53d9d6b8ad3",
        type: "plain",
        title: "high",
        description: "",
        color: "#ff7537",
        textcolor: "#ffffff",
      },
      {
        id: "41dbf6ab-cf8f-4d88-bad1-f9baec83d48b",
        type: "plain",
        title: "medium",
        description: "",
        color: "#ffad46",
        textcolor: "#ffffff",
      },
      {
        id: "78fb6569-9970-4fdf-b6df-ec0daa6ea9b9",
        type: "plain",
        title: "low",
        description: "",
        color: "#7bd148",
        textcolor: "#ffffff",
      },
    ],
  },
];
Edit this page