### onload() Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Example demonstrating how to get an instance of the PrettyPropertiesPlugin after it has loaded and is ready for use.
```typescript
const plugin = app.plugins.getPluginById('pretty-properties') as PrettyPropertiesPlugin;
// Plugin is fully initialized and ready to use
```
--------------------------------
### loadSettings() Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Example showing how to load settings and then access a specific setting like 'enableBanner'.
```typescript
await plugin.loadSettings();
console.log(plugin.settings.enableBanner); // true
```
--------------------------------
### saveSettings() Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Example demonstrating how to modify a setting and then save the changes.
```typescript
plugin.settings.enableBanner = false;
await plugin.saveSettings();
```
--------------------------------
### Install Dependencies
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Installs project dependencies using npm.
```bash
# Install dependencies
npm install
```
--------------------------------
### Development Build
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Starts the development server for live reloading and debugging.
```bash
# Development build
npm run dev
```
--------------------------------
### migrateSettings() Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Example illustrating the use of migrateSettings to handle the conversion from an old single cover property format to the new array format.
```typescript
// Migrates from old single coverProperty to new coverProperties array
await plugin.migrateSettings(loadedSettings);
```
--------------------------------
### Dynamic Feature Application Example
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Example of applying dynamic features after patches are registered, typically called in the plugin's onload() function.
```typescript
// In onload(), after patches registered:
updateRelativeDateColors(this)
updateBannerStyles(this)
updateIconStyles(this)
updateCoverStyles(this)
// ... etc
```
--------------------------------
### Settings Migration Example
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/configuration.md
Illustrates the conversion from an old settings format to the new format during plugin loading. This ensures backward compatibility.
```typescript
// Old format
{
coverProperty: "cover",
extraCoverProperties: ["banner_image"]
}
// New format
{
coverProperties: [
{ property: "cover", format: "" },
{ property: "banner_image", format: "" }
]
}
```
--------------------------------
### IconSuggestModal Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Demonstrates how to open the IconSuggestModal. After user selection, it may open another modal like SvgSuggestModal.
```typescript
new IconSuggestModal(app, plugin).open();
// User selects "Lucide Icon"
// Opens SvgSuggestModal
```
--------------------------------
### Instantiate PropertyFormatter
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Example of creating a new instance of the PropertyFormatter class.
```typescript
const formatter = new PropertyFormatter();
```
--------------------------------
### HTML Example: Date with Relative Color Data Attribute
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Shows an example of a date property with a data attribute indicating a future relative date, used for styling.
```html
```
--------------------------------
### Command Availability Logic Example
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/commands.md
Demonstrates the conditions that commands typically check before becoming available. This includes verifying an active file, checking if a feature is enabled in settings, and confirming if a specific property is configured or exists.
```typescript
// File requirement
let file = plugin.app.workspace.getActiveFile();
if (!(file instanceof TFile)) return false;
// Feature enabled check
if (!plugin.settings.enableBanner) return false;
// Property configured check
if (!plugin.settings.bannerProperty) return false;
// Property exists check (for remove commands)
let value = getCurrentProperty(propName, plugin);
if (!value) return false;
```
--------------------------------
### Update Function Optimization Example (Good)
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Demonstrates an optimized approach to updating elements by first querying all relevant elements and then iterating over them.
```typescript
// Good - O(n)
const pills = document.querySelectorAll(".pill");
for (const pill of pills) {
updatePill(pill);
}
```
--------------------------------
### HTML Example: List Item with Color Data Attribute
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Example of a list item styled as a pill, with a data attribute specifying its value for conditional styling.
```html
```
--------------------------------
### Create Settings Controls
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-utility-functions.md
Demonstrates how to create settings controls within a container element using the Setting class. Includes examples for text input and color picker controls.
```typescript
// Create settings controls
const textSetting = new Setting(containerEl)
.setName("Banner Height")
.setDesc("Height in pixels")
.addText(text => text.setValue("150"));
// Color picker
const colorSetting = new Setting(containerEl)
.setName("Color")
.addColorPicker(picker => picker.setValue("#ff0000"));
```
--------------------------------
### Global API Access and Usage Example
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Demonstrates how to access the Pretty Properties API globally via `window.PrettyPropertiesApi` and use its functions to retrieve color values and apply styles to elements.
```typescript
// In browser console or custom code
const api = window.PrettyPropertiesApi;
// Get current color setting
const bgColor = api.getPropertyBackgroundColorValue("status", "done");
const textColor = api.getPropertyTextColorValue("status", "done");
// Apply to elements
const element = document.querySelector(".my-property-pill");
api.setPPColorStyles(element, "status", "done");
```
--------------------------------
### HTML Example: Progress Property with Data Attributes
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Illustrates how data attributes are added to HTML elements for styling and behavior, specifically for a progress property.
```html
```
--------------------------------
### Dot Notation Path Examples
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-utils.md
Illustrates how dot notation is used to access nested properties in frontmatter. Paths are split by '.', empty segments are skipped, and paths can be arbitrarily deep.
```text
"title" → fm.title
"author.name" → fm.author.name
"metadata.colors.bg" → fm.metadata.colors.bg
"tags" → fm.tags (array)
```
--------------------------------
### Testing Patches in Console
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Provides examples of how to test if patches have been applied correctly using the browser's developer console.
```typescript
// In console
const widget = document.querySelector(".metadata-property");
const rendered = widget._rendered;
if (rendered) {
console.log("Widget is patched:", rendered);
}
// Check if unpatch function exists
if (plugin.patches.widgets) {
console.log("Patches registered");
}
```
--------------------------------
### Initialize Property Formatter
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Example of calling `registerPropertyFormatter` to initialize the plugin's formatter. After this call, `plugin.formatter` becomes available for use.
```typescript
registerPropertyFormatter(plugin);
// plugin.formatter is now available
```
--------------------------------
### durationFormatted Helper Examples
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Demonstrates the `durationFormatted` Handlebars helper for formatting durations using a specified dayjs format string.
```handlebars
{{durationFormatted 829 "seconds" "HH:mm:ss"}} → "00:13:49"
{{durationFormatted propertyValue "s" "HH[h] mm[m]"}} → "00h 13m"
```
--------------------------------
### Template Compilation and Caching Example
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Demonstrates how the formatter compiles and caches templates. The first call compiles and caches the template, while subsequent calls reuse the cached version for performance.
```typescript
// First call - compiles and caches
formatter.format("prop1", 100, "{{add propertyValue 50}}");
// Second call - uses cached compilation
formatter.format("prop2", 200, "{{add propertyValue 50}}");
```
--------------------------------
### onunload() Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Illustrates that the onunload method is called automatically when the plugin is disabled.
```typescript
// Called automatically when disabling the plugin
```
--------------------------------
### Conditional Formatting Example
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Applies conditional formatting to a property value, displaying a specific emoji based on the value. This example shows how to prepend an emoji to the property value for visual emphasis.
```typescript
// Show status with color based on priority
const result = formatter.format(
"priority",
"high",
"🔴 {{propertyValue}}"
);
// Returns: "🔴 high"
```
--------------------------------
### EmojiSuggestModal Example Usage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Shows how to use the EmojiSuggestModal to insert an emoji directly into the text editor.
```typescript
// Insert emoji in text editor
new EmojiSuggestModal(app, plugin, editor).open();
```
--------------------------------
### Get Plugin Instance from Obsidian Console
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Access the Pretty Properties plugin instance and its API from the Obsidian console.
```typescript
const plugin = app.plugins.getPluginById('pretty-properties');
const api = window.PrettyPropertiesApi;
const formatter = plugin.formatter;
```
--------------------------------
### Use Custom Formatters in Templates
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Illustrates how to use a custom Handlebars helper within property formatting settings. Examples show direct usage and combined with other helpers.
```plaintext
// In property formatting settings:
// {{myHelper propertyValue}}
// {{myHelper propertyValue}} - {{propertyName}}
// {{uppercase (myHelper propertyValue)}}
```
--------------------------------
### HTML Example: Hidden Property with Data Attributes
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Demonstrates how a hidden property is marked with inline styles and a class to control its visibility.
```html
```
--------------------------------
### Default Settings Object
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/types.md
The complete default configuration object for new installations of the Pretty Properties plugin. It includes settings for hidden properties, colors, and display options.
```typescript
const DEFAULT_SETTINGS: PPPluginSettings = {
hiddenProperties: [],
propertyPillColors: {},
propertyLongtextColors: {},
tagColors: {},
enableBanner: true,
enableIcon: true,
enableCover: true,
bannerProperty: "banner",
iconProperty: "icon",
coverProperties: [{ property: "cover", format: "" }],
coverShapeProperty: "cover_shape",
coverPositionProperty: "cover_position",
bannerHeight: 150,
bannerHeightMobile: 100,
bannerHeightPopover: 100,
bannerMargin: -20,
bannerMarginMobile: 0,
bannerFading: true,
// ... (see settings.ts for complete list)
}
```
--------------------------------
### Localization Structure
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Directory structure for localization files in the Pretty Properties Obsidian plugin, including the main localization system and example locale files.
```typescript
src/localization/
├─ localization.ts - i18n system
└─ locales/
├─ en.ts - English strings
└─ ru.ts - Russian strings (example)
```
--------------------------------
### Process Multiple Files for Front Matter
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Iterates through all markdown files in the vault and processes their front matter. This example demonstrates marking files as 'archived' based on a 'status' property.
```typescript
const files = app.vault.getMarkdownFiles();
for (const file of files) {
plugin.app.fileManager.processFrontMatter(file, (fm) => {
// Process each file
const status = getNestedProperty(fm, 'status');
if (status === 'archived') {
// Mark as hidden
addToHiddenList(file.name, plugin);
}
});
}
```
--------------------------------
### Get Property Type Information
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Fetches detailed information about a specific property, including its widget type and available options. Returns null if the property is not found.
```typescript
const typeInfo = plugin.app.metadataTypeManager.getPropertyInfo('status');
if (typeInfo) {
console.log('Type:', typeInfo.widget || typeInfo.type);
console.log('Options:', typeInfo.options);
}
```
--------------------------------
### Get Property Background Color Setting
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Retrieves the raw color setting (theme name, HSL, 'default', or 'none') for a property value before CSS conversion. Handles different property types like text, multitext, and tags.
```typescript
getPropertyBackgroundColorSetting(propName: string, propValue: string): string | HSL | "default" | "none"
```
```typescript
const setting = api.getPropertyBackgroundColorSetting("status", "done");
// Returns: "green", HSL object, "default", or "none"
```
--------------------------------
### Production Build
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Compiles the plugin for production deployment.
```bash
# Production build
npm run build
```
--------------------------------
### Get Current File Property
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-utils.md
Reads a property value from the currently active file. It gets the active file, its metadata cache, extracts frontmatter, and uses getNestedProperty() to retrieve the value.
```typescript
export const getCurrentProperty = (
propName: string,
plugin: PrettyPropertiesPlugin
): string | string[] | number | boolean | null | undefined
```
```typescript
const banner = getCurrentProperty("banner", plugin);
if (banner) {
console.log("Banner set to:", banner);
}
const depth = getCurrentProperty("metadata.depth", plugin);
```
--------------------------------
### Create Pretty Properties API Instance
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
This function creates and initializes the API instance. It assigns the API to `plugin.api` and also exposes it globally as `window.PrettyPropertiesApi`.
```typescript
export const createApi = (plugin: PrettyPropertiesPlugin): void
```
```typescript
createApi(plugin);
// Now available as: plugin.api, window.PrettyPropertiesApi
```
--------------------------------
### Programmatic Command Execution and Checking
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/commands.md
Shows how to execute a command by its ID using `app.commands.executeCommandById`. It also demonstrates how to retrieve a command object and check its current availability.
```typescript
// Execute a command programmatically
app.commands.executeCommandById('pretty-properties:select-banner-image');
// Get command object
const command = app.commands.commands['pretty-properties:select-banner-image'];
// Check if command is currently available
const isAvailable = app.commands.executeCommandById('pretty-properties:select-banner-image');
```
--------------------------------
### durationHumanized Helper Examples
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Illustrates the usage of the custom Handlebars helper `durationHumanized` for converting durations into natural language strings.
```handlebars
{{durationHumanized 829 "s"}} → "14 minutes"
{{durationHumanized 829 "s" true}} → "in 14 minutes"
{{durationHumanized propertyValue "s"}} → "14 minutes"
```
--------------------------------
### Standard Command Registration Pattern
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/commands.md
Illustrates the common pattern for registering commands in an Obsidian plugin using `plugin.addCommand`. It shows how to define command IDs, names (with localization), and implement availability checks using `checkCallback` or execution logic using `editorCallback`.
```typescript
plugin.addCommand({
id: "command-id",
name: i18n.t("TRANSLATION_KEY"),
checkCallback: (checking: boolean) => {
// Check if requirements are met
if (!meetsRequirements()) return false;
if (!checking) {
// Execute command
doSomething();
}
return true;
}
// or editorCallback for editor commands:
editorCallback: (editor, view) => {
// Execute with editor context
}
});
```
--------------------------------
### Common Usage Patterns
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-utils.md
Demonstrates common patterns for interacting with Obsidian properties using utility functions like setNestedProperty, deleteNestedProperty, and getNestedProperty within the file manager.
```APIDOC
## Common Usage Patterns
### Update a Single Property
```typescript
plugin.app.fileManager.processFrontMatter(file, (fm) => {
setNestedProperty(fm, "status", "completed");
});
```
### Update Multiple Properties
```typescript
plugin.app.fileManager.processFrontMatter(file, (fm) => {
setNestedProperty(fm, "cover", "![[cover.jpg]]");
setNestedProperty(fm, "cover_position", "left");
setNestedProperty(fm, "cover_shape", "square");
});
```
### Check and Conditionally Update
```typescript
plugin.app.fileManager.processFrontMatter(file, (fm) => {
if (!getNestedProperty(fm, "status")) {
setNestedProperty(fm, "status", "todo");
}
});
```
### Remove Multiple Related Properties
```typescript
const propsToRemove = ["cover", "cover_position", "cover_shape"];
plugin.app.fileManager.processFrontMatter(file, (fm) => {
for (const prop of propsToRemove) {
deleteNestedProperty(fm, prop);
}
});
```
### Handle Property That Might Not Exist
```typescript
const status = getCurrentProperty("status", plugin);
if (status !== undefined && status !== null) {
// Property exists with a value
console.log(status);
}
```
```
--------------------------------
### ImageSuggestModal Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Initializes the ImageSuggestModal for selecting banner, cover, or icon images. It requires the Obsidian app instance, plugin instance, property name, target folder, and image type.
```typescript
new ImageSuggestModal(
app: App,
plugin: PrettyPropertiesPlugin,
propName: string,
folder: string,
type: string
)
```
--------------------------------
### Handle Icon Menu
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Provides context menu options for icons, including changing the icon or its visibility.
```typescript
handleIconMenu(menu, icon, plugin)
```
--------------------------------
### Get Plugin Instance from Another Plugin
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Access the Pretty Properties plugin instance and its API from within another Obsidian plugin.
```typescript
const ppPlugin = this.app.plugins.getPluginById('pretty-properties');
if (!ppPlugin) {
console.log('Pretty Properties not installed');
return;
}
const api = ppPlugin.api;
const formatter = ppPlugin.formatter;
```
--------------------------------
### LocalImageSuggestModal Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Initializes the LocalImageSuggestModal for selecting local image files. It takes the Obsidian app, plugin instance, property name, shape, image paths, image names, and an optional editor instance.
```typescript
new LocalImageSuggestModal(
app: App,
plugin: PrettyPropertiesPlugin,
propName: string,
shape: string,
imagePaths: string[],
imageNames: string[],
editor?: Editor
)
```
--------------------------------
### Get Property Text Color Setting
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Retrieves the raw text color setting for a property value. Returns the same types as getPropertyBackgroundColorSetting.
```typescript
getPropertyTextColorSetting(propName: string, propValue: string): string | HSL | "default"
```
```typescript
const textColor = api.getPropertyTextColorSetting("status", "done");
```
--------------------------------
### Determine Property Types
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Get the type of a property and check if it's a list, date, or number. This helps in handling property values correctly.
```typescript
const type = getPropertyType('myProp', plugin);
const isListProperty = type === 'multitext' || type === 'aliases';
const isDateProperty = type === 'date' || type === 'datetime';
const isNumberProperty = type === 'number';
// Handle accordingly
if (isListProperty) {
// Value is string[]
const items = value as string[];
} else if (isDateProperty) {
// Value is string (YYYY-MM-DD format)
const date = moment(value as string);
}
```
--------------------------------
### API Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Initializes a new instance of the API class. Requires a reference to the plugin instance.
```typescript
constructor(plugin: PrettyPropertiesPlugin)
```
```typescript
const api = new API(plugin);
```
--------------------------------
### Settings Tab Options
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/configuration.md
Lists the available options for the `settingsTab` configuration. This determines which settings tab is initially displayed.
```plaintext
"BANNERS", "ICONS", "COVERS", "COLORED_PROPERTIES",
"HIDDEN_PROPERTIES", "PROPERTY_FORMATTINGS", "OTHER"
```
--------------------------------
### PPPluginSettings Interface
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/types.md
Defines the main settings interface for the Pretty Properties plugin, encompassing all user-configurable options for properties, colors, banners, icons, covers, and more.
```typescript
interface PPPluginSettings {
// Hidden properties
hiddenProperties: string[]
hiddenWhenEmptyProperties: string[]
// Color settings
propertyPillColors: Record
propertyLongtextColors: Record
tagColors: Record
dateColors: {
past: PillColorSettings
present: PillColorSettings
future: PillColorSettings
}
// Banner settings
enableBanner: boolean
bannerProperty: string
bannerHeight: number
bannerHeightMobile: number
bannerHeightPopover: number
bannerMargin: number
bannerMarginMobile: number
bannerFading: boolean
bannerPositionProperty: string
bannerIconGap: number
bannerIconGapMobile: number
enableBannersInPopover: boolean
// Icon settings
enableIcon: boolean
iconProperty: string
iconSize: number
iconTopMargin: number
iconTopMarginMobile: number
iconTopMarginWithoutBanner: number
iconLeftMargin: number
iconGap: number
iconColor: string
iconColorDark: string
iconBackground: boolean
iconSizeMobile: number
iconSizePopover: number
iconInTitle: boolean
titleIconSize: number
titleTextIconMatchTitleSize: boolean
enableIconsInPopover: boolean
// Cover settings
enableCover: boolean
coverProperties: Array<{ property: string; format: string }>
coverShapeProperty: string
coverPositionProperty: string
coverPosition: string
coverDefaultWidth1: number
coverDefaultWidth2: number
coverDefaultWidth3: number
coverMaxHeight: number
coverMaxHeightTopBottom: number
coverVerticalWidth: number
coverHorizontalWidth: number
coverSquareWidth: number
coverCircleWidth: number
coverMaxWidthPopover: number
coverMaxWidthCanvas: number
enableCoversInPopover: boolean
hideCoverCollapsed: boolean
// Progress bar settings
progressProperties: Record
// Folder settings
bannersFolder: string
coversFolder: string
iconsFolder: string
// Property formatting
propertyFormats: Record
enableColoredProperties: boolean
enableColoredInlineTags: boolean
enableColorButton: boolean
showTextColorSettings: boolean
// Date settings
customDateFormat: string
customDateTimeFormat: string
enableCustomDateFormat: boolean
enableCustomDateFormatInBases: boolean
enableRelativeDateColors: boolean
// Tag settings
enableColoredTagsInTagPane: boolean
nonLatinTagsSupport: boolean
showTagColorSettings: boolean
addBaseTagColor: boolean
// Hidden/empty property settings
hidePropertiesInPropTab: boolean
showColorSettings: boolean
showHiddenSettings: boolean
showHiddenEmptySettings: boolean
hideAllEmptyProperties: boolean
hideMetadataContainerIfAllPropertiesHiddenEditing: boolean
hideMetadataContainerIfAllPropertiesHiddenReading: boolean
autoHidePropertiesWithBanner: boolean
hidePropTitle: boolean
hideAddPropertyButton: boolean
// Other settings
showColorSettings: boolean
showExtraFormattings: boolean
showColorSettings: boolean
addPillPadding: string
enableColorButtonInBases: boolean
propertySearchKey: string
settingsTab: string
mathProperties: string[]
enableMath: boolean
imageLinkFormat: string
dataVersion: number
// Deprecated (kept for migration)
coverProperty?: string
extraCoverProperties?: string[]
}
```
--------------------------------
### FileImageSuggestModal Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Initializes the FileImageSuggestModal for quick selection of image types (banner, cover, icon). It requires the Obsidian app and plugin instance.
```typescript
new FileImageSuggestModal(app: App, plugin: PrettyPropertiesPlugin)
```
--------------------------------
### Handlebars Property Formatting
Source: https://github.com/anareaty/pretty-properties/blob/master/README.md
Example of using Handlebars templating to format a number property representing seconds into a human-readable duration. This avoids storing the same value multiple times.
```handlebars
{{durationFormatted propertyValue "seconds" "m \"m\" s\"s\""}}
```
--------------------------------
### Handle Banner Menu
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Provides context menu options for banner images, including changing the image, position, or visibility.
```typescript
handleBannerMenu(menu, banner, plugin)
```
--------------------------------
### Instantiate ColorPickerModal
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Opens a dialog to set colors for properties, tags, or dates. Features a color picker, live preview, and stores HSL values.
```typescript
// Set color for "high" priority tag
new ColorPickerModal(app, plugin, "high", "tagColors", "pillColor").open();
```
--------------------------------
### List All Properties
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Retrieves and logs all available properties managed by the application, along with their types. This is useful for introspection and understanding available metadata.
```typescript
const properties = plugin.app.metadataTypeManager.getAllProperties();
for (const [name, info] of Object.entries(properties)) {
console.log(`${name}: ${info.type}`);
}
```
--------------------------------
### API Class for Color Management
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Provides methods for managing property colors, including getting color values and applying styles to elements. Used for customizing the appearance of properties.
```typescript
class API {
constructor(plugin: PrettyPropertiesPlugin)
getPropertyBackgroundColorValue(propName, propValue): string
getPropertyTextColorValue(propName, propValue): string
getPropertyBackgroundColorSetting(propName, propValue): string | HSL
getPropertyTextColorSetting(propName, propValue): string | HSL
setPPColorStyles(el, propName, propValue): void
setPPTextColor(el, propName, propValue): void
setPPBackgroundColor(el, propName, propValue): void
}
export function createApi(plugin): void
```
--------------------------------
### Get Current Cover Property
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-utility-functions.md
Finds the current cover property that has a value for the current note by checking properties in the `coverProperties` array. Returns the property name or `undefined` if no cover is found.
```typescript
export const getCurrentCoverProperty = (
plugin: PrettyPropertiesPlugin
): string | undefined
```
```typescript
const coverProp = getCurrentCoverProperty(plugin);
if (coverProp) {
console.log("Current cover property:", coverProp);
}
```
--------------------------------
### IconSuggestModal Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Initializes the IconSuggestModal for selecting various icon types including local images, external images, Lucide icons, and emojis. It requires the Obsidian app and plugin instance.
```typescript
new IconSuggestModal(app: App, plugin: PrettyPropertiesPlugin)
```
--------------------------------
### Access Global Pretty Properties API
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Demonstrates how to access the Pretty Properties plugin's API instance and the plugin instance itself globally within an Obsidian environment.
```typescript
window.PrettyPropertiesApi // Color API instance
app.plugins.getPluginById('pretty-properties') // Plugin instance
```
--------------------------------
### Configure Tag Colors
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/configuration.md
Set custom colors for tags. This allows you to visually distinguish tags based on their meaning or importance. For example, 'project' tags could be blue and 'urgent' tags red.
```typescript
{
"project": { pillColor: "blue" },
"urgent": { pillColor: "red" }
}
```
--------------------------------
### Get Property Background Color Value
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Retrieves the CSS-compatible background color string for a given property name and value. Returns theme colors, transparent, HSL, or an empty string for default.
```typescript
getPropertyBackgroundColorValue(propName: string, propValue: string): string
```
```typescript
const color = api.getPropertyBackgroundColorValue("status", "completed");
// Returns: "rgba(var(--color-green-rgb), 0.2)"
```
--------------------------------
### Common Update Pattern: Querying and Updating Elements
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-utility-functions.md
Illustrates a common pattern for updating elements by first selecting them using `document.querySelectorAll` and then iterating to apply updates.
```typescript
// Get all elements of type
const elements = document.querySelectorAll(".metadata-property");
// Update each one
for (const el of elements) {
const propName = el.getAttribute("data-property-key");
updateSomeProperty(el, propName, plugin);
}
```
--------------------------------
### Handle Cover Menu
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Offers context menu options for cover images, such as changing the image, shape, position, or visibility.
```typescript
handleCoverMenu(menu, cover, plugin)
```
--------------------------------
### Get Property Text Color Value
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Retrieves the CSS-compatible text color string for a given property name and value. Falls back to calculating color based on background lightness if not explicitly set.
```typescript
getPropertyTextColorValue(propName: string, propValue: string): string
```
```typescript
const color = api.getPropertyTextColorValue("status", "completed");
```
--------------------------------
### Core API Files Structure
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Overview of the main API files within the Pretty Properties Obsidian plugin, including the plugin's main class, lifecycle, settings management, and API utility classes.
```typescript
src/main.ts
└─ PrettyPropertiesPlugin class
└─ Plugin lifecycle (onload, onunload)
└─ Settings management
src/utils/createApi.ts
└─ API class for color management
└─ window.PrettyPropertiesApi global
src/utils/propertyFormatter.ts
└─ PropertyFormatter class
└─ Handlebars compilation and formatting
src/utils/propertyUtils.ts
└─ getNestedProperty, setNestedProperty
└─ removeProperty, getCurrentProperty
└─ getPropertyType, getPropertyValue
src/utils/registerCommands.ts
└─ All slash commands registration
└─ 10 commands for images and properties
src/utils/imageUtils.ts
└─ selectCoverImage, selectCoverShape
└─ renderImageFromValue
└─ getCurrentCoverProperty
```
--------------------------------
### Store and Apply Patch Reference
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Demonstrates how to store a reference to a patch for later removal. Patches are applied using the 'around' function.
```typescript
plugin.patches.widgets = around(
PropertyWidgetComponent.prototype,
"render",
// ... patch function
);
if (plugin.patches.widgets) {
delete plugin.patches.widgets; // Unpatch
}
```
--------------------------------
### Get Obsidian Property Type
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-utils.md
Retrieves the Obsidian property type for a given property name. Uses Obsidian's metadataTypeManager and handles both new and old property formats. Returns undefined for unknown properties.
```typescript
export const getPropertyType = (
propName: string,
plugin: PrettyPropertiesPlugin
): string | undefined
```
```typescript
const type = getPropertyType("status", plugin);
if (type === "multitext") {
// Property is a list/multiselect
}
const dateType = getPropertyType("published", plugin);
if (dateType === "date") {
// Property is a date
}
```
--------------------------------
### Remove File Property
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-utils.md
Removes a property from the currently active file's frontmatter. It gets the active file and uses Obsidian's file manager to safely modify frontmatter, deleting the property using deleteNestedProperty().
```typescript
export const removeProperty = (
propName: string,
plugin: PrettyPropertiesPlugin
): void
```
```typescript
// Remove banner image
removeProperty("banner", plugin);
// Remove nested property
removeProperty("metadata.color", plugin);
```
--------------------------------
### Get Nested Property
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-utils.md
Retrieves a property value from a frontmatter object using dot notation. Returns undefined if the path leads to a non-primitive value or is not found. Supports multi-level nesting and handles missing intermediate objects.
```typescript
export const getNestedProperty = (
obj: FrontMatterCache,
path: string
): string | string[] | number | boolean | null | undefined
```
```typescript
const cache = plugin.app.metadataCache.getFileCache(file);
const title = getNestedProperty(cache.frontmatter, "title");
const author = getNestedProperty(cache.frontmatter, "author.name");
const tags = getNestedProperty(cache.frontmatter, "tags");
```
--------------------------------
### SvgSuggestModal Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Initializes the SvgSuggestModal for searching and selecting Lucide SVG icons. It requires the Obsidian app and plugin instance.
```typescript
new SvgSuggestModal(app: App, plugin: PrettyPropertiesPlugin)
```
--------------------------------
### Open ImageLinkPrompt
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Opens a dialog to enter an external image URL. Validates the URL format and sets the specified property. Supports HTTP/HTTPS.
```typescript
new ImageLinkPrompt(app, "banner").open();
// User enters: https://example.com/banner.jpg
// Sets banner property
```
--------------------------------
### Command Name Localization
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/commands.md
Illustrates how command names are localized using the `i18n` system, referencing translation keys for different languages. Translations are typically stored in locale files.
```typescript
name: i18n.t("SELECT_BANNER_IMAGE")
```
--------------------------------
### Configure Multiple Cover Properties
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/configuration.md
Allows for multiple frontmatter properties to be designated as cover image sources. The plugin will use the first one that contains a value.
```json
[
{ "property": "cover", "format": "" },
{ "property": "banner_image", "format": "" },
{ "property": "hero", "format": "" }
]
```
--------------------------------
### UI Components Structure
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
File organization for UI components within the Pretty Properties Obsidian plugin, covering various modals for image selection, icon picking, color selection, and more.
```typescript
src/modals/
├─ imageSuggestModal.ts - Image selection
├─ localImageSuggestModal.ts - Local image picker
├─ fileImageSuggestModal.ts - Quick image menu
├─ iconSuggestModal.ts - Icon type selector
├─ svgSuggestModal.ts - Lucide icon picker
├─ emojiSuggestModal.ts - Emoji picker
├─ bannerPositionModal.ts - Banner position selector
├─ coverShapeSuggestModal.ts - Cover shape selector
├─ coverPositionSuggestModal.ts - Cover position selector
├─ imageLinkPrompt.ts - URL input dialog
└─ colorPickerModal.ts - Color picker dialog
src/menus/
├─ propertyMenu.ts - Property context menu
├─ bannerMenu.ts - Banner context menu
├─ coverMenu.ts - Cover context menu
├─ iconMenu.ts - Icon context menu
└─ selectColorMenus.ts - Color selection menus
```
--------------------------------
### Listen for Settings Changes
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Provides methods to respond to external settings changes, as settings are not automatically saved or updated in the UI. Includes polling and manual reload patterns.
```typescript
// Poll for changes
setInterval(() => {
const currentSettings = plugin.settings;
// Check for changes
}, 1000);
// Or reload manually
reloadAllTabs(plugin);
```
--------------------------------
### Monkey-Around Patching Pattern
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Demonstrates the standard pattern for applying patches using the 'monkey-around' library, including before and after hooks.
```typescript
import { around, dedupe } from "monkey-around";
export const patchSomething = (plugin: PrettyPropertiesPlugin) => {
plugin.patches.someName = around(
TargetClass.prototype,
"methodName",
(next) => {
return function(...args) {
// Before hook
console.log("Before method call");
// Call original method
const result = next.apply(this, args);
// After hook
console.log("After method call");
return result;
};
}
);
};
```
--------------------------------
### Property Widget Rendering Extension
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Illustrates how the original render method is called first, followed by Pretty Properties' extensions to update widgets with custom features.
```typescript
// Original method called first
const rendered = originalRender.call(this);
// Then extended with Pretty Properties features
updateWidgets(type, rendered, args, plugin);
return rendered;
```
--------------------------------
### Image Utilities for Selection and Rendering
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
Contains functions for selecting local and banner images, managing cover image properties, and rendering images from values.
```typescript
export const selectLocalImage(propName, folder, shape, plugin): void
export const selectBannerPosition(plugin): void
export const selectCoverShape(plugin): void
export const selectCoverPosition(plugin): void
export const getCurrentCoverProperty(plugin): string | undefined
export const selectCoverImage(plugin): void
export const renderImageFromValue(value, type, sourcePath, component, plugin): Promise
```
--------------------------------
### Banners Folder Configuration
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/configuration.md
Specify the vault folder to search for banner images. Leave empty to search the entire vault.
```string
"assets/banners"
```
--------------------------------
### onload() Method Signature
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Signature for the onload method, which is called when the plugin loads. It's responsible for initialization tasks.
```typescript
async onload(): Promise
```
--------------------------------
### PropertyFormatter Constructor
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-property-formatter.md
Initializes the PropertyFormatter, setting up Handlebars, registering built-in and custom helpers, and configuring the dayjs locale.
```typescript
constructor()
```
--------------------------------
### Import Monkey-Around Functions
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Illustrates the necessary import statement for using the 'around' and 'dedupe' functions from the 'monkey-around' library.
```typescript
import { around, dedupe } from "monkey-around";
```
--------------------------------
### Log Plugin State and Property Details
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/extension-guide.md
Use console.log to inspect the plugin's internal state, settings, patches, and formatter cache. Also useful for logging specific property values and their types.
```typescript
// Log plugin state
console.log('Plugin settings:', plugin.settings);
console.log('Plugin patches:', Object.keys(plugin.patches));
console.log('Formatter cache:', plugin.formatter.compiledCache.size);
// Log property resolution
const value = getCurrentProperty('status', plugin);
const type = getPropertyType('status', plugin);
console.log(`status: ${value} (${type})`);
```
--------------------------------
### selectCoverImage
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-utility-functions.md
Opens a modal to select or upload a cover image, determining the current cover property or using the first configured one.
```APIDOC
## selectCoverImage
### Description
Opens a modal to select or upload a cover image. It automatically determines the current cover property to use or defaults to the first configured one. Supports local files, URLs, and external images.
### Method
selectCoverImage
### Parameters
#### Path Parameters
- **plugin** (`PrettyPropertiesPlugin`) - Required - Plugin instance
### Request Example
```typescript
selectCoverImage(plugin);
```
### Response
#### Success Response
This function does not return a value directly but opens a modal for image selection and updates the relevant frontmatter property.
### Error Handling
No explicit error handling is documented for this function.
```
--------------------------------
### Select Cover Position
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-utility-functions.md
Opens a dialog to set the cover position by launching the `CoverPositionSuggestModal`. The selected position is then set to the `cover_position` property.
```typescript
export const selectCoverPosition = (
plugin: PrettyPropertiesPlugin
): void
```
--------------------------------
### API Class Declaration
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-color-management.md
Defines the structure and methods of the Color Management API class. This class is exposed globally as window.PrettyPropertiesApi.
```typescript
export class API {
plugin: PrettyPropertiesPlugin
constructor(plugin: PrettyPropertiesPlugin)
getPropertyBackgroundColorValue(propName: string, propValue: string): string
getPropertyTextColorValue(propName: string, propValue: string): string
getPropertyBackgroundColorSetting(propName: string, propValue: string): string | HSL | "default" | "none"
getPropertyTextColorSetting(propName: string, propValue: string): string | HSL | "default"
setPPColorStyles(el: HTMLElement, propName: string, propValue: string): void
setPPTextColor(el: HTMLElement, propName: string, propValue: string): void
setPPBackgroundColor(el: HTMLElement, propName: string, propValue: string): void
}
```
--------------------------------
### Monkey-Around Library API
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/patching-system.md
Shows the basic API for the 'monkey-around' library, including applying a patch and removing it, as well as deduplicating patches.
```typescript
// Apply patch
const unpatch = around(target, methodName, patchFn);
// Remove patch
unpatch();
// Deduplicate patches
const unpatch = dedupe(key, patchFn);
```
--------------------------------
### Custom Suggestion Modal Implementation
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Extend `SuggestModal` to create custom suggestion interfaces. Implement `getSuggestions`, `renderSuggestion`, and `onChooseSuggestion` to define behavior.
```typescript
export class MyModal extends SuggestModal {
plugin: PrettyPropertiesPlugin;
constructor(app: App, plugin: PrettyPropertiesPlugin) {
super(app);
this.plugin = plugin;
}
getSuggestions(query: string): MyType[] {
// Filter options based on query
return allOptions.filter(opt =>
opt.name.toLowerCase().includes(query.toLowerCase())
);
}
renderSuggestion(item: MyType, el: Element) {
// Display item in list
el.createDiv({ text: item.name });
}
onChooseSuggestion(item: MyType) {
// Handle selection
applySelection(item, this.plugin);
}
}
```
--------------------------------
### Instantiate CoverPositionSuggestModal
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Used to select the position of a cover image relative to metadata.
```typescript
new CoverPositionSuggestModal(
plugin,
file
)
```
--------------------------------
### Select Cover Image
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-utility-functions.md
Opens a modal to select or upload a cover image, supporting local files, URLs, and external images. It determines the current cover property or uses the first configured one before opening the `ImageSuggestModal`.
```typescript
export const selectCoverImage = (
plugin: PrettyPropertiesPlugin
): void
```
```typescript
selectCoverImage(plugin);
```
--------------------------------
### Instantiate CoverShapeSuggestModal
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/modals-menus.md
Used to select the shape of a cover image. Applies CSS for sizing.
```typescript
new CoverShapeSuggestModal(
plugin,
file
)
```
--------------------------------
### loadSettings() Method Signature
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Signature for the loadSettings method, an asynchronous function that loads plugin settings from persistent storage.
```typescript
async loadSettings(): Promise
```
--------------------------------
### Settings Structure
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/INDEX.md
File organization for the settings modules in the Pretty Properties Obsidian plugin, covering main settings and specific UI configurations for banners, icons, covers, colors, dates, and formatting.
```typescript
src/settings/
├─ settings.ts - Main settings interface
├─ bannerSettings.ts - Banner settings UI
├─ iconSettings.ts - Icon settings UI
├─ coversettings.ts - Cover settings UI
├─ colorSettings.ts - Color settings UI
├─ datesSettings.ts - Date format settings UI
├─ formatSettings.ts - Property format settings UI
├─ hiddenSettings.ts - Hidden property settings UI
└─ otherSettings.ts - Misc settings UI
```
--------------------------------
### migrateSettings(data) Method Signature
Source: https://github.com/anareaty/pretty-properties/blob/master/_autodocs/api-plugin-main.md
Signature for the migrateSettings method, which handles backward compatibility for settings that have changed structure between plugin versions.
```typescript
async migrateSettings(data: PPPluginSettings): Promise
```
--------------------------------
### Progress-bar Formula for Bases
Source: https://github.com/anareaty/pretty-properties/blob/master/README.md
A formula to create a progress bar within bases, using 'maxProperty' and 'valueProperty'.
```dataviewjs
if( note["maxProperty"], html("