Wedge

Public area => The Pub => Plugins => Topic started by: Arantor on February 25th, 2012, 12:40 AM

Title: Settings page integration
Post by: Arantor on February 25th, 2012, 12:40 AM
Had a random idea about this today. The plugin info file already lists all the $settings variables that a plugin uses (so that it can set defaults and clean up properly later) but I've been thinking about the interface side of things.

Right now, if a plugin wants to add a settings page, even a simple one, it's going to have to create a file, use at least two hooks[1] and create a stub file that is almost entirely identical from plugin to plugin. Heck, when I start a plugin now that uses a simple settings page, I just copy everything from an earlier one.

So, here's what I'm thinking. Everything that you would normally have to set up for a settings page ($config_vars etc.) can be streamlined. Of course, more complex plugins (of the likes of WedgeDesk) would still do their own thing, but the smaller stuff could be simplified.

For example, I have a stub plugin that will grow into a big scary share-topics-with-services monster, dubbed Flitter because it was originally just Facebook + Twitter. Right now, it's very straightforward however, with its settings page being:

Code: [Select]
$config_vars = array(
array('desc', 'flitter_desc'),
array('select', 'flitter_position', array('topic' => $txt['flitter_position_topic'], 'sidebar' => $txt['flitter_position_sidebar'])),
array('title', 'flitter_fb'),
array('check', 'flitter_showfb'),

array('title', 'flitter_twitter'),
array('check', 'flitter_showtwitter'),
$txt['flitter_twitter_via_desc'],
array('text', 'flitter_twitter_via'),
array('text', 'flitter_twitter_related'),
array('text', 'flitter_twitter_related_desc'),

array('title', 'flitter_google'),
array('check', 'flitter_showgoogle'),
);

Then you have a function which binds to the admin menu, and the rest of the boilerplate in this function that's used for saving and calling the relevant templates and stuff. It gets set up as action=admin;area=flitter and uses 'Flitter' as the title (which is the plugin's title anyway)

I'm thinking we could handle this in the plugin-info.xml file directly instead.

Code: [Select]
<settings-page area="flitter" icon="mgallery.png" bigicon="$plugindir/flitter.png">
<load-language file="Flitter-Admin" />
<desc name="flitter_desc" />
<select name="flitter_position">
<opt value="topic" name="flitter_position_topic" />
<opt value="sidebar" name="flitter_position_sidebar" />
</select>
<title name="flitter_fb" />
<check name="flitter_showfb" />
<title name="flitter_twitter" />
<check name="flitter_showtwitter" />
<literal name="flitter_twitter_via_desc" />
<text name="flitter_twitter_via" />
<text name="flitter_twitter_related" />
<text name="flitter_twitter_related_desc" />
<title name="flitter_google" />
<check name="flitter_showgoogle" />
</settings-page>

Assuming the plugin author uses this, it should be able to handle the menu item, the settings themselves, making them searchable and auto-linking it in the plugins area (minimising the need for using the <acp-url> element though not obsoleting it)

The area= part specifies what admin area it should be, the icon is the icon for the dropdown menu, the bigicon is the big icon to use, <load-language> identifies what language file(s) should be loaded when running the page, so that the relevant strings can be loaded. Everything else just correlates to the above.

Personally, I think it's less effort for the plugin developer generally, it's less they have to deal with - you don't expressly have to deal with hooks when doing this and you're still doing less work than you would doing it manually.

Thoughts?
 1. Three if you want to make it searchable as well, yup, even that isn't automated.
Title: Re: Settings page integration
Post by: Arantor on February 25th, 2012, 01:01 AM
While there is an implied performance aspect (since the admin menu has to be evaluated every page of the admin area) it's not a great stretch to actually cache all the active plugins' details and evaluate them in a single hit.
Title: Re: Settings page integration
Post by: live627 on February 25th, 2012, 02:01 AM
We used this concept for external modules in Dream Portal. The module uploader grabbed the parameters and copied them to the database.

Title: Re: Settings page integration
Post by: Arantor on February 25th, 2012, 02:05 AM
How well did it work out for you?

I never did find out how well Dream Portal's plugins stuff did, I was vaguely aware of what one had to do to create such a thing but I never made any, and I remember being something related to amazement at seeing raw PHP embedded into XML,[1] but anything other than that, I don't remember, and I might even be remembering that incorrectly.

(Note that I'm not looking to remove the existing <settings> block which is used for settings defaults and housekeeping, because plugins that don't use this setup because it's too limiting, e.g. WedgeDesk, will still use <settings> to clean up after removal)
 1. Since unless I'm much mistaken, that's eval() right there...
Title: Re: Settings page integration
Post by: live627 on February 25th, 2012, 02:27 AM
Quote
How well did it work out for you?
I did not notice any problems. My original draft did not modify any files, but, in the end, language entries got injected into a master file, if you remember.

Raw PHP code within XML? II have no idea on what's in the current development, but the first public debuts did not. Heck, the only eval call was for the custom code module.
Title: Re: Settings page integration
Post by: Arantor on February 25th, 2012, 02:33 AM
I thought the module's code was generally specified in the XML file and there was no extraneous files added (except for complete language files or sub files, but that the main block code was actually directly in the XML) - but that was a long time ago. Glancing through the current ones it doesn't seem like that now - though I think the format of embedding options into the XML sort of defeats the point of using XML a bit...
Quote
but, in the end, language entries got injected into a master file, if you remember.
I didn't remember but it seems to be that way based on the XML files.

So, all in all, it seems like it hasn't confused anyone?
Title: Re: Settings page integration
Post by: live627 on February 25th, 2012, 02:46 AM
Quote
though I think the format of embedding options into the XML sort of defeats the point of using XML a bit...
I don't know about the other developer, but I didn't know much about XML best practices back then.
Quote
So, all in all, it seems like it hasn't confused anyone?
Very hard to tell, since almost no one has used that. To this day, I see modules only be the project members. And they haven't complained about that syntax that I could see.
Title: Re: Settings page integration
Post by: Arantor on February 25th, 2012, 02:48 AM
Somehow that doesn't surprise me one bit.

OK, so more relevantly, do you like the syntax proposed? Would you use it for the intended case?
Title: Re: Settings page integration
Post by: live627 on February 25th, 2012, 03:32 AM
Yep! But why use the tag opt - seems too close to optgroup. Could you expand tit to the full word ''option'?
Title: Re: Settings page integration
Post by: Arantor on February 25th, 2012, 03:34 AM
Because I was lazy :P I have no problem with using option instead of opt, just laziness on my part.
Title: Re: Settings page integration
Post by: live627 on February 25th, 2012, 03:42 AM
We all have our lazy times :P
Title: Re: Settings page integration
Post by: Arantor on February 27th, 2012, 03:58 AM
Bump in case anyone else has any opinions they want to voice before I go implement this.
Title: Re: Settings page integration
Post by: Nao on February 27th, 2012, 11:54 AM
You're the boss, boss!
Title: Re: Settings page integration
Post by: Arantor on February 27th, 2012, 01:33 PM
OK, I'll work on this in a bit :)
Title: Re: Settings page integration
Post by: Arantor on February 27th, 2012, 06:36 PM
This is now in r1397.
Posted: February 27th, 2012, 06:33 PM

And I've updated the contact page plugin in my repo to cover it too.
Title: Re: Settings page integration
Post by: live627 on March 12th, 2012, 07:45 AM
Can you add support for subtexts?
Title: Re: Settings page integration
Post by: Arantor on March 12th, 2012, 09:17 AM
Strikes me that there's two ways to do it, either by checking for $txt[$current_setting . '_subtext'] and just setting subtext to that if found, or manually specifying it as a parameter. The former would be quicker and likely easier to use but the latter would be clearer how the answer is derived.

Which would you prefer to use? (Remember that you can have help text if you so desire, though it's not immediately obvious how... if you declare $helptxt[$current_setting] and then have it so your language file is also loaded by the lang_help hook, it should work (though I haven't tested to be sure)
Title: Re: Settings page integration
Post by: Nao on March 12th, 2012, 01:50 PM
Reminds me of a recent conversation, eh... ;)
Title: Re: Settings page integration
Post by: Arantor on March 12th, 2012, 01:51 PM
Haha, indeed it does. But therein is the reason why $helptxt is a separate variable, it's to keep it structurally simple :)
Title: Re: Settings page integration
Post by: Dragooon on March 12th, 2012, 01:52 PM
Quote from Arantor on March 12th, 2012, 09:17 AM
Strikes me that there's two ways to do it, either by checking for $txt[$current_setting . '_subtext'] and just setting subtext to that if found, or manually specifying it as a parameter. The former would be quicker and likely easier to use but the latter would be clearer how the answer is derived.

Which would you prefer to use? (Remember that you can have help text if you so desire, though it's not immediately obvious how... if you declare $helptxt[$current_setting] and then have it so your language file is also loaded by the lang_help hook, it should work (though I haven't tested to be sure)
I'd do it the geek way and define an entire hook as <current_setting>_helptxt.
Title: Re: Settings page integration
Post by: Arantor on March 12th, 2012, 02:03 PM
That seems a big drastic seeing how there's absolutely no need to do anything extra in core for help popup strings.
Title: Re: Settings page integration
Post by: Dragooon on March 12th, 2012, 02:12 PM
Quote from Arantor on March 12th, 2012, 02:03 PM
That seems a big drastic seeing how there's absolutely no need to do anything extra in core for help popup strings.
It was a joke, I'd just do it similarly to title. If title is passed, then pass the helptxt as well otherwise just take it if defined in txt entries.
Title: Re: Settings page integration
Post by: Arantor on March 12th, 2012, 02:20 PM
That's all well and good (and the use of help items was more a footnote that they work already without any extra core effort), but that doesn't solve subtext items, which are normally defined in $txt and have no direct correlation to the primary entry. I personally tend to try and be consistent and for $txt[$key], define $txt[$key . '_subtext'] but $txt[$key . '_note'] is also used.

So, should we auto-use $txt[$key . '_subtext'] or have something in the XML to specify the subtext? Note that it might also be good to allow for having post-values as well like in some of the numeric fields where after it, the word 'days' is used to indicate that it's a set number of days.
Title: Re: Settings page integration
Post by: Dragooon on March 12th, 2012, 02:25 PM
I'd simply define it as $txt[$key . '_subtxt'] mostly because then it goes with other langaage strings and can be translated at one place.
Title: Re: Settings page integration
Post by: Arantor on March 12th, 2012, 02:36 PM
OK, cool. I'll implement that later on then as it's a pretty quick thing to add.
Title: Re: Settings page integration
Post by: live627 on March 13th, 2012, 01:31 AM
Quote from Arantor on March 12th, 2012, 09:17 AM
Strikes me that there's two ways to do it, either by checking for $txt[$current_setting . '_subtext'] and just setting subtext to that if found, or manually specifying it as a parameter. The former would be quicker and likely easier to use but the latter would be clearer how the answer is derived.

Which would you prefer to use? (Remember that you can have help text if you so desire, though it's not immediately obvious how... if you declare $helptxt[$current_setting] and then have it so your language file is also loaded by the lang_help hook, it should work (though I haven't tested to be sure)
I prefer the former, like Dragooon
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 01:35 AM
OK, so I need to define an extra thing in the XML just for subtext as opposed to having something automatically check a preset $txt.

/megoes to fire up the heavyweight XML editor to manage the schema.
Posted: March 13th, 2012, 01:33 AM

To be absolutely clear, we're talking about the difference between:

Code: [Select]
<settings>
<setting name="contact_verification" default="guests" />
</settings>

and
Code: [Select]
<settings>
<setting name="contact_verification" default="guests" subtext="contact_verification_somestring" />
</settings>

And then just defining $txt['contact_verification_subtext'] in the first case vs $txt['contact_verification_somestring'] in the second. The former is a 'just works' case.

The latter sounds like an awful lot of work for something most plugin writers won't even use...
Title: Re: Settings page integration
Post by: live627 on March 13th, 2012, 01:53 AM
Why would a plugin want to define its own subtext other than using its own format, like using _desc instead of _subtext?
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 01:57 AM
That's what I thought you were saying?
Title: Re: Settings page integration
Post by: live627 on March 13th, 2012, 02:01 AM
Yes, iit was. I was just exploring why someone would want to do otherwise, when this way seems better and simpler and less error-prone.
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 02:06 AM
Eh, it's quickly added to r1456, have at it!
Title: Re: Settings page integration
Post by: live627 on March 13th, 2012, 02:21 AM
Cool, thanks :)

Should the div-in-label-to-subtext hack go now?
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 02:22 AM
Which one? The one in the admin search?
Title: Re: Settings page integration
Post by: live627 on March 13th, 2012, 02:26 AM
No, same file as in the revision, there's a small regex hack that allegedly converts the div in the label to  the subtext.
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 02:37 AM
Not in ManageSettings.php there isn't.

There is however in ManageServer.php:
Code: [Select]
// !!! Temporary. Preventing divs inside label tags.
$divPos = strpos($context['config_vars'][$config_var[1]]['label'], '<div');
if ($divPos !== false)
{
$context['config_vars'][$config_var[1]]['subtext'] = preg_replace('~</?div[^>]*>~', '', substr($context['config_vars'][$config_var[1]]['label'], $divPos));
$context['config_vars'][$config_var[1]]['label'] = substr($context['config_vars'][$config_var[1]]['label'], 0, $divPos);
}

Until everything that should be a subtext is a subtext, it needs to stay (though I think it's broken anyway... since I think everything's dfn tags now)
Title: Re: Settings page integration
Post by: live627 on March 13th, 2012, 07:03 AM
Can you add  support for the callback type? Just need  to add a case for it in the top group.
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 09:12 AM
No, I won't.

In order to make it work, it would require not only having support for the type directly (which is an easy matter, though also requires updating the plugin-info.rng file), but the ability to load a source file and a template file, and call functions to load and save the data.

If it's that complex, do it the older way and create your own settings page through the normal hook channels.
Title: Re: Settings page integration
Post by: Arantor on March 13th, 2012, 11:32 AM
Quote from live627 on March 13th, 2012, 02:26 AM
No, same file as in the revision, there's a small regex hack that allegedly converts the div in the label to  the subtext.
Fixed in r1457.
Title: Re: Settings page integration
Post by: Dragooon on March 20th, 2012, 02:38 PM
Hey, this actually works! :D. Great!
Title: Re: Settings page integration
Post by: Arantor on March 20th, 2012, 02:43 PM
Quote from Dragooon on March 20th, 2012, 02:38 PM
Hey, this actually works! :D. Great!
What do you mean 'this actually works'? :lol: Cheeky. Of course it works! :P (Never mind that as soon as I implemented it, I migrated all my simple plugins to use it, to prove it worked :P)
Title: Re: Settings page integration
Post by: Dragooon on March 20th, 2012, 03:01 PM
You know.....I didn't expect this to be implemented, let alone working just fine...I just realised that you actually went ahead with it and dropped the admin area hooks :P
Title: Re: Settings page integration
Post by: Arantor on March 20th, 2012, 03:08 PM
No, I didn't drop any hooks at all, this is in addition to it. (And I did mention in reply #30 that I'd added it :P)

The idea is that simple stuff can use the quick integration and have it basically done for them, but complex stuff (calendar, WedgeDesk) will still continue to do its own thing anyway. That's really what stuff like this is for: simple cases now don't have to create a new file just to store a function just to add to a variable, nor do they have to attach that function to hooks (especially re admin search).

There are also usability matters at hand: the more that Wedge can do automatically, the better everyone is. If plugin authors don't have to contend with plugins being integrated into search, because Wedge can do it for them, great - both the plugin author and the general users benefit. Also having a semi-consistent interface will help with that, instead of having to mess around adding new pages to the admin, they get added automatically so admins are going to be able to find them more easily :)
Title: Re: Settings page integration
Post by: Dragooon on March 20th, 2012, 03:12 PM
I don't happen to be a good reader :P. I bumped into this while trying to figure out where to add the settings. Regardless, it's a pretty handy feature for quickly adding in a neat settings page. Thanks :).
Title: Re: Settings page integration
Post by: Arantor on March 20th, 2012, 03:14 PM
Anytime :)

You probably figured by now, though, a lot of the way the plugin system is developing is actually because I've been using it. The <actions> hook for example is because I was actively adding actions and figuring out how awkward it was. This is another example. I did also suggest something similar for adding menu items actually... haven't got round to that yet.
Title: Re: Settings page integration
Post by: live627 on March 20th, 2012, 08:46 PM
Quote from Arantor on March 20th, 2012, 03:08 PM
No, I didn't drop any hooks at all
Yes you did: remember modify_modifications?
Title: Re: Settings page integration
Post by: Arantor on March 20th, 2012, 08:53 PM
Oh, yes, that one. What I meant was I didn't prevent addons doing their own thing, I just removed that particular method of doing it... In my mind it didn't really qualify as a hook :P