Examples for SettingsService

[sytone]

Do you have a simple example of how this looks with a Settings Tab class?

Sing the tab will already extend PluginSettingTab it cannot be a service, how will it get context to pull the SettingsService out from the container?

[pjeby]

The idea is that different services have their own settings which together form the overall plugin settings, and the same for the tabs. Each service performs its own useSettings() call and gets the same SettingsService, but the defaults and types from each are combined.

For the settings UI, each service does useSettingsTab() and adds a showSettings() method to actually create the settings UI via the builder.

So there is no PluginSettingTab - that's handled by the builder service (SettingsTabBuilder). An example from some work in progress for one of my plugins:

class GlobalHotkeys extends Service {
    settingsTab   = useSettingsTab(this);
    settings      = useSettings(
        this,
        {globalHotkeys: [] as CmdCfg[]},
        ({globalHotkeys: g}) => this.updateHotkeys(g)
    );
    showSettings() {
        const tab = this.settingsTab, {settings} = this;
        tab.field().setName("Global Hotkeys").setHeading();
        const addNew = tab.field()
            .setName("Add new Command").addButton(b => b
                .setButtonText("Add command").setCta().onClick(async () => {
                    // ...
                    await settings.update(({globalHotkeys: g}) => {
                        g.push(cmd);
                    })
                    new CommandField(this, cmd, addNew.settingEl);
                })
            );
        this.globalHotkeys.forEach(c => new CommandField(this, c, addNew.settingEl));
        tab.field();
    }
}

Basically, there is no one place where you define all your plugins or settings tab UI - it's distributed among the services. The order in which the services are initialized determines the order of the settings in the plugin's (auto-generated) settings tab.

This allows you to concentrate everything for a given feature in one place.

Since the plugin itself is also effectively a service, you can also have it define defaults and UI via the same method; the placement in the list will be determined by where useSettingsTab occurs in the setup, e.g.:

export default class MyPlugin extends Plugin {
    use = use.plugin(this);
    someService = this.use(SomeService);
    settingsTab = useSettingsTab(this, ...);
    otherService = this.use(OtherService);
}

In this example, any settings defined by SomeService will appear first in the plugin's settings, followed by those defined by the plugin class' showSettings() method, followed by any defined by OtherService. So you can organize the settings groups any way you like, and in effect the PluginSettingTab gets generated for you.

[pjeby]

By the way, in case it's not clear from the above, there is a single namespace for the plugin settings, but it's the intersection of all the individual types defined by the services. So service A might use {serviceASetting1, serviceASetting2}, and service B might have {globalHotKeys}. As long as the names don't overlap (or if they do, are a shared setting), it's fine - all the settings are still saved in the normal way, as a combined {serviceASetting1, serviceASetting2, globalHotkeys} type (with combined defaults, too).

But this way, each service only needs to know about its own types and defaults, without needing to manually combine them into a single set of types and defaults for the plugin as a whole.

[pjeby]

Oh, also... to answer your original question, a class does not have to extend Service (or use use.service) in order to be able to look things up. It just needs a use context, which you can pass into its constructor. Or, it can capture use.this if it has a zero-argument constructor, e.g.:

class MyPlugin extends Plugin {
    use = use.plugin(this);
    onload() {
        this.addSettingTab(this.use(MyPluginSettings));
    }
}

class MyPluginSettings extends PluginSettingTab {
    settings = use(SomeService)
    constructor() {
        super(use(App), use(MyPlugin));
    }         
}

Basically, any object that is created via a use() call can call use() to get other services. If that object needs to call it after the constructor is finished, it needs to save it via this.use = use.this (or use = use.this in the class body).

The only reason that Plugin and Services are different on this point is that 1) Plugin is constructed by Obsidian, so there isn't a use() call active (and there is special setup to be done as well), and 2) Services are Components that get registered to load() and unload() with the plugin.

So anything that isn't a component that loads/unloads with the plugin does not have to be a Service. You can also use() anything that has a zero-argument constructor, and it can call use() in the constructor (and any initializers), and it can save use.this (via constructor or initializer) to keep a reference to the context.

[sytone]

Thanks for the detailed response! I will re-read it again later today and look at how I have my plugin structured. Currently my settings are generated by a json configuration file that is processed to generate the UI dynamically. I will look to see how to break it up as the UI creation has a lot of repedative code that I was trying to avoid.

I should be able to make the generation seperate and then have a json file per service to keep it cleaner.

If you want I will make a PR in the next week or so to make this part of the documentation for this library.

I had tried to implement a DI in the past to break up my app but I just do not have enough working experience with typescript to be effective so this project is great as it gets me moving faster. Just have to refactor my code to the service model a bit. I'm sure there would be better ways but I have the rendering working locally now using your framework. Took a bit to sort out how to get the context though for the post code block rendering.

I'll make a PR for my plugin so you can see and comment on my mistakes if you are interested. Thank you for putting all this together.

[pjeby]

Don't worry about the doc PR - the settings API (both the storage and UI parts) are too unstable at the moment, as I have not actually published any plugin updates using them. I'm still exploring the use of them to see if the APIs are actually good. At this point they are functional but there are little bits I don't like, like relying on events for settings updates. The final API probably won't change a ton, but... I don't feel it's stable enough to document at the moment.

You can ping me on your plugin PR, though, and I'll have a look.

I'm going to leave this issue open though as a reminder for me to write some documentation from this eventually. 😉

[pjeby]

Oh, now I remembered one of the specific things that's most likely to change when useSettings/SettingsService finalizes API is that I may want to require settings to be immutable. The current implementation is based on JSON comparison of the overall settings object rather than equality checking, which is super convenient in some ways but bad for others (e.g. if I rip out Events as the basis of distribution). This is relevant to the API in that I would like to be able to convert the settings "data source" to be something you can functionally derive parts of it as properties, as in FRP systems.

What I mean is, it should be possible to take a settings object, give it two functions (an accessor and mutator for some aspect of settings) and then get a new "subsetting" with the same ability to observe changes and the like. This would make complex settings UI easier if you have settings that need sub-dialogs to pop up with more settings.

Anyway, all of that is hard to do in the current setup - each subsetting would need its own Events instance at present. I'm thinking about using @preact/signals-core instead, but it has the problem that signals always have an initial value, and Obsidian plugin settings don't have a value until they're loaded from disk... which can't happen till plugin load, which screws up the necessary initialization order of services. (I really wish Obsidian would just load the plugin data automatically before instantiating the plugin instance... it'd save so many headaches.)

So, yeah, the biggest holdup to finalizing the settings API is having a clean way of creating monitorable value streams without needing to write my own rxjs replacement, too... though my local copy of ophidian/core has a draft or two of such. 😉 The new html module I'm working on in core right now is a redom-inspired Obsidian-specific HTML framework for use w/JSX, and I want to support binding it to some kind of value streams as well.

Unfortunately most tiny FRP libs seem to lack critical features somewhere:

• Preact Signals lack the ability to have a signal with a delayed initial value (also doesn't have on-demand upstream pull but I can extend it to add that)
• Callbags would be fantastic if they weren't all CommonJS modules using a calling convention that's essentially impossible to write code in Typescript for without constantly casting things.
• Flyd doesn't do lazy upstreams and I can't hack it in without using proxies, getting a PR accepted (seems unlikely in this stage of its development), or just forking it. (Also its extensions are mostly CommonJS and lacking in typings.) Oh, and though you can technically have a stream without an initial value, you can still read the nonexistent initial value, which is the thing I want to avoid for settings.

And the big ones are, well, big. As in bigger than many Obsidian plugins' entire built main.js files. most.js's minified code is larger than the source of my drafts for a tiny FRP, including lots of doc comments. 😁 (And rxjs is an order of magnitude larger, bigger than most Obsidian plugins.)

So if you happen to know of a good tiny FRP lib with decent performance and typings, that can do lazy, on-demand subscriptions and value streams with no initial value, packaged as ES modules and implemented as operator functions so it can be tree-shaken down to what a given plugin needs... please do share. As much fun as I have writing draft FRP libs, getting them production-ready with docs and tests and such is more of a chore. 😉

If I don't find one, my likely next approach is to just bail on delayed-start as part of the FRP framework itself, and use Promise<Signal<T>> as SettingService's main event source, and augmenting Preact signals with the other bits Ophidian needs for general-purpose FRP and HTML rendering. This won't likely change useSettings(), though, except that setting mutators will have to return new objects instead of mutating in place. But some direct access stuff for SettingsService might change, and I might need to make it so that the PluginSettingTab doesn't get registered with Obsidian until after the SettingService finishes the data load.

[sytone]

I have not worked with a FRP library so cannot help there. Was looking at the event library to handle notifications through the systems for call backs at one point.

[sytone]

This is where I know I am going the wrong way. I wanted to move the rendering logic to a separate service and then have the QueryRenderChild added as child of the MarkdownPostProcessorContext. That class needs to extend MarkdownRenderChild.

I tried to get the use functions to load the object in QueryRenderChild nd not pass them through but kept on getting no context errors. Assing it directly works but looks like it is not cleaning it self up when pages load so need to look at how all the unloads work.

MarkdownRenderChild

[pjeby]

Yeah, one thing there is that you don't want Service for things that aren't singletons you want to have hang around for the life of the plugin being loaded. That's what inheriting from Service or using use.service() does -- make it load() and unload() with the Bootloader, which in turn is tied to the Plugin.

Second, you don't have to fork context to create things if you just want them to have a context. You can just pass the context as a constructor argument, or send in a Useful thing. That is, like this:

class AThing {
    use: Context
    constructor(ctx: Useful = use.this) {
        this.use = ctx.use;
    }
}

Now AThing will discover its own context when created by use(), but you can also create it manually by passing it any other object with a use property. (e.g. new AThing(this) if this is a service or plugin or another Useful thing - i.e. a thing with a use: Context property.

You should use this approach for your render child stuff: just keep your existing Component subclasses but add a constructor argument you can pass the context into. No need to fork or use services for components like this -- the examples in to-use of forking for requests are intended for a web server architecture where lots of different components might need to be request-specific and live and die by that request. Per-request singletons, as it were.

But Obsidian doesn't have anything like that, just stuff like renderChild where it's not really a new context - just a thing that lives in the existing context and doesn't have any new, context-specific singletons that need to be shared among a bunch of things.

Another tip -- if you want to simplify stuff like access to Workspace, you can just do stuff like this in your main.ts:

use.def(Workspace, () =>use(Plugin).app.workspace);

And then you can just this.use(Workspace).on(...) and the like. Or set ws = this.use(Workspace) as an instance property or whatever.

[pjeby]

Come to think of it you can use use.def(Workspace, () =>use(App).workspace); too, since Ophidian now supplies a use.def for App as well. (Honestly I'm thinking of adding an app export to Ophidian so that you can just import app anywhere you need it.)

[sytone]

ok, I just played around with something similar where I passed the service into the render child that extends MarkdownRenderChild. From that I called use off that service and got the instances of the classes I needed.

I tried to just use 'use' off the class via the base functionality of to-use but it kept complaining there was no context, which I know there was as the parent class definitely had it and was able to find the services.

At that point I could have just passed the objects over be at least this way the parent does not keep on having to add more object to be sent. It just sends itself and the child render class pulls what it needs out. Updated the PR with the newer approach. This also fixed the unload issue where the rendering was not being destroyed causing a continual increase in executions when a page was modified.

[pjeby]

Yeah, I thought I was clear on the distinction in the to-use docs, but maybe I wasn't:

• Singletons created by to-use get the context automatically
• Non-singletons need to be given a context so they can look up the singletons with it

That's what the Useful interface is for: the idea is that you can make a generic class or function that accepts any Useful object to get context from, without needing to know anything else about that object.

There's really no such thing as a "parent" class in to-use: just a context you can get configuration and singletons from. If you have more than one of a thing and they're not scoped to some sort of execution context (like a web request), it's not something you'd look up via use().

Take for example PerWindowComponent in Ophidian. PerWindowComponent is not a singleton or a service - it takes a context object as its first constructor parameter, and is created by a WindowManager service. Code that needs to get a per window component ask the WindowManager, which then makes one or returns an existing one. This is a handy approach when you have more than one of a thing, but they are still well-known in some way (i.e. as the instance of a thing "for" a particular window or whatever).

I wouldn't take that approach with a renderChild, though, because they're disposable one-offs, not well-known instances. I jsut bring it up to show you there are many ways to manage things between "one-off with a context" and "total singleton".

If you have any suggestions on how to clear this up in the to-use docs, I would appreciate it. I recall briefly referencing some of this stuff in it, but I was mostly focused on singletons providing services rather than classes that consume services but don't provide them.

[sytone]

ok, so one the plugin is set in the global container via use = use.plugin(this); calls to this.use will be using the global context/plugin context and all services are singletons in this container, correct?

As an example at this point I want to setup a LoggingService to return a logger customized for the class/module via a name. So in the plugin or any other class that inherits from Service I can call logger = this.use(LoggingService).getLogger('modulename');. This will return a logger class pre configured by the LoggingService, the LoggingService itself is a singleton in the context for the Plugin. The returned Logger class will be independent in this case and it does not need any context as the parent class (LoggingService) which is the singleton handles it all.

For the rendering approach, in plugin I set a private property to the QueryRendererV2Service by using this.queryRendererService = this.use(QueryRendererV2Service); This would mean it is now in the context for the plugin and avaliable for services. In this case it is not really used by other classes but is a component that sets itself up in the onload function which is called via Bootstrapper looking at the library code.

During the load it is registering a Markdown Code Block Processor which should be called when Obsidian hits a codeblock when rendering preview/read mode. When it is called via Obsidian it parses the codeblock to get the config out and then adds a child (QueryRenderChildV2) to the MarkdownPostProcessorContext provided by Obsidian, which is a Component. This child is new every time as the configuration and rendering is seperate per code block.

The object I have added takes the HTML element to update, configuration, MarkdownPostProcessorContext and then this, which is the QueryRendererV2Service which is in the Plugin's context. In the QueryRenderChildV2 class I am using the passed in service and calling use of it as it has the global context still, it allows it to grab things like the plugin, logger, as well as the render and query adapters from the global context.

So reading through what you have said instead of the service being passed, I can pass the context that QueryRendererV2Service has to the child objects? So instead of passing the service over via this I should pass this.use which should be the Context object and from that I can get the singletons already registered in the plugins context.

Sorry for the ramble trying to get it out of my head to make more sense.

[pjeby]

ok, so one the plugin is set in the global container via use = use.plugin(this); calls to this.use will be using the global context/plugin context and all services are singletons in this container, correct?

Yep. In to-use terms, it's just the plugin context, as the global context can't be used except to define defaults. But from the point of view of everything in the plugin, it's definitely "global" in that sense. In services.ts, it's also captured as rootCtx, and you can get access to it by calling getContext() with an object that might have a .use property. If the passed in object doesn't have a use property and the plugin has been initialized, it returns the root (plugin) context.

Sorry this stuff isn't documented, but it's very much in motion -- I think I only added getContext() a month ago.

The returned Logger class will be independent in this case and it does not need any context as the parent class (LoggingService) which is the singleton handles it all.

Yeah, if an object doesn't use any other singletons it doesn't need a context.

For the rendering approach, in plugin I set a private property to the QueryRendererV2Service by using this.queryRendererService = this.use(QueryRendererV2Service); This would mean it is now in the context for the plugin and avaliable for services. In this case it is not really used by other classes

Yep. You can also just call this.use(Whatever) in the plugin onload() without keeping a reference to it, if the service just does its own thing and you don't need to talk to it from the plugin.

And you may not even need to do that much, see below...

So reading through what you have said instead of the service being passed, I can pass the context that QueryRendererV2Service has to the child objects? So instead of passing the service over via this I should pass this.use which should be the Context object and from that I can get the singletons already registered in the plugins context.

Yes. Exactly. This lets you make things more loosely-coupled, as the parent doesn't have to "spoon feed" the child everything it needs. In fact, you can write things the other way around, by making the child depend on the renderer service, instead of needing the service to create the child.

That is, you could just register a postprocessor that creates an instance of QueryRenderChildV2 and gives it a context, and then lets it look up the render service from there. At which point the plugin would not need to create the rendering service at all!

That's the true freedom of dependency injection - it lets you work "bottom up" instead of "top down". By default Obsidian architecture is sort of paternalistic, you have parents needing to know all their children's business and manage their lives. In the Ophidian model, you just let the kids do their own thing, and they have a context they can call on for whatever shared resources they need -- without the parents needing to know or care about the details.

In the limit case, an Ophidian based plugin need not do anything except kickstart any services that represent user-visible features, and the services shouldn't need to reference the plugin except to access Obsidian plugin-level APIs (like view, postprocessor and command registration), and thus only use the raw Plugin interface without needing to import the plugin class from main.

The ideal really is that the plugin can import services or utility classes and depend on what features they have, but the services and utility classes should never need to depend on the plugin except as an access point for those plugin APIs (or as a place to getContext() from, I suppose).

[pjeby]

This commit actually showcases a bit how some of the above is supposed to work, actually:

03dd418#diff-5536dabb3779843c6bc44bccbbbf02dc58b5c7fb4071b74f933a52119f52ce3eR46

If you look at how useSettings is implemented, it takes an owner argument, but doesn't do anything with it except use it to register an event and get the context (and it falls back to the root context if the owner doesn't have one). It then does stuff with the SettingsManager behind the scenes. This is an example of how you can create nice APIs that don't require explicit service management. If you useSettings() the settings service comes along for the ride, but you don't have to create it, put it in a property, remember what property you put it on, etc. etc. All you care about is that the return value of useSettings() has onChange() and update() methods.

In the same way, you could define a function like, "createQueryRenderChild()" or something, that takes an owner plus any needed parameters, and do the same thing without needing the consuming component to know anything about the underlying details. Or you can just include an owner as a class constructor argument. Or heck, you can just call getContext(null) and get the plugin context as long as the plugin constructor has already run.

When I was first writing Ophidian I thought it might be useful to have child use() contexts for some things... but the more experience I get the more I see those are extreme specialty cases. Like for example, I have considered doing some note indexing stuff where a note would get a context to look up computed field data. For any version of a note, there is always one answer to a question like, "what tags does this have" or "does this link to note X". So a context where you're looking up functions for computing those things makes sense and is a valid reason to fork contexts.

But that's an extreme special case compared to normal plugin development.

Another possibility is that if you have something like a remote login connection to a database or something, and you don't want to cache things across connections, you want clean setup each time, so you want to have "per-connection" singletons, then that's another place where forking makes sense - any components that use() the connection would then be scoped there. The tricky bit is that they couldn't be Services unless the connection had its own Bootloader so as to shut down when the connection unloaded. But you could do something like that, certainly.

Anyway, these two examples are far less common than I thought forking would be when I did the initial design and wrote to-use. That's why I've recently loosened up and added getContext(), as it makes life a lot easier in the extremely common case where there will only ever be one context.