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.
Configuring a custom logo
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'
Show advanced search
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",
},
],
},
];