Okey, so, a thread for discussion pertaining directly to the lib and the data specs.
I am, of course, open to all feedback. If there's anything you think I should add to the wiki pages on github, let me know.
Github Page, lots more links here, including API docs and downloads.
Please note that you should release addons with the tagged versions only, never release addons with the version from the master branch, it is considered ALPHA. Also, don't remove the library from "no externals" versions of addons, there is no standalone version and never will be!
Don't split the specification.
the only difference between the two things you noted as seperate specifications is, that the one will have the launcher attribute set and will thus most likely not change text nor expect the display to have it shown. Besides that, they are based on the smae spec so all you get is doublicated specification text making it harder to read the specs.
Don't set attributes as required.
The spec shouldn't mark anything as required. For example, a changing icon could be used by an addon to indicate data so there would be no text. Or a launcher could only provide a label (or even have the display fallback to the DOs name). Sure, a launcher needs an OnClick handler to be functional, but that shouldn't be part of the specs... anyone trying to do one without it is doomed to fail anyways ;)
Better documentation on tooltips.
After reading through the specs and having some hard time I figured out that there are currently three ways tooltips can be handled:
- the display provides and handles a tooltip that is populated via the OnTooltipShow attribute
- the DO provides a (populated) tooltip that is handled by the display
- the DO handles the tooltip in reaction to OnEnter/OnLeave
Currently this is only documented implicitly through the attributes.
Better documentation on function arguments.
Currently, the arguments are only noted inside the documentation text but in order to have the function work properly they should be noted more explicit I think.
Okay, here's the deal, me and Funkeh have been discussing the spec for a while, and Funkeh wants a way to easily change the color of "FPS" or "MiB/s" or "XP".
The way he did it was to put "FPS" or "XP" etc. in .label, then color it and concatenate it with .text. In the .text he only gives the number, like "24".
At the same time I read the docs Tekkub put up, and I started putting stuff like "Framerate" in .label and "24 FPS" in .text. We had a discussion about it and I didn't want to force him to change the way he did things, I had added a temporary key named .unit, which he too started to use as "FPS, "MiB" or "XP"...
.unit is just way too specific, and it is not a good solution. Well, I have a suggestion for keys that might help this problem:
.value - if the display displays a number, set it here (could be "24", when .text would be "24 FPS")
.suffix, - text to append behind .value or text (could be "FPS", when .text would be "24 FPS")
All should be optional of course, and text should always provide something for displays that don't support this optional stuff. The goal here is keeping stuff simple, but this is needed if the displays should be able to set the color/hide the suffix, and Funkeh and I wouldn't mind being able to. I don't think optionally providing .value and .suffix would be too specific. Anyone having some ideas on how to solve this the best without making Funkeh cry? :) He wants his colors!
setup a standard pattern and just format it and set the .txt each time? is it that wasteful for the plug in to do? or is this a case of offloading burden to the display?
I want to hear more about the .unit label. So far we've used it correctly for units like MB or FPS etc, that's fine by me, but in my opinion we need a rule. Either add "FPS" etc to .text OR .unit NOT both. Some Broker plugins do this and completely render it useless.
I want
.text = 100 .unit = FPS
OR
.text = 100FPS
(dependent on the author)
NOT
.text = 100FPS .unit = FPS
Inconsistency like these will only end up on people replicating existing plugins for minor changes, rendering the route of LDB pointless because of incompatibilities with viewers.
.unit was something I added to some of the broker plugins, but someone (Nev, JoshBorke can't remember) said it is too specific to be supported, and yeah, they're right. So currently I follow the LDB-1.1 spec from the readme and use nothing else. This means including the unit/suffix in .text (.text = "24 fps", for example), as that is how I was told it should be by multiple people, for maximum compatibility with displays.
This leaves the problem that it would be nice to have a way to set the color of the unit/suffix in the display, and I think this is why Funkeh doesn't put "fps" for example in his .text. Funkeh and I haven't really been able figure out the best way to do things.
So bottom of line is: The spec needs to be stricter and Funkeh would like a way to color his unit/suffix. Hopefully some of the guys who started the spec can help clear this up.
maybe instead of text and unit you could simply have multiple texts text = {24,"FPS"} simplest case the table would simply be concat but if the display addon wants to it could enable coloring of each table entry though this might create confusion of how to describe each key of the text table so maybe if you have a text table you should also provide with a textinfo table textinfo = {"FPS number", "FPS tag"}
Hopefully some of the guys who started the spec can help clear this up.
You mean me?
I originally started .label as an optional method for plugins to use so display addons could customize it the way *they* wanted and still not have it look like rubbish if they didn't support it since you just had the raw value in text. Now what's happened is you've changed the way label is used because of, imo, a bad description by Tekkub. I'm not willing to argue this to the end of time so I dumped label for .unit since you were using that in some sane way to find out you're double using unit. No information should ever be doubled in my opinion, choose to show it in one method or another.
As to a name, that really doesn't bother me as long as we can have a global standard.
I'm willing to merge the specs, anyone have a good argument against it? It would actually make things simpler in the end, and might encourage more people to flag their DO's as launchers when they really are, and let the display addons chose to just not implement all the fancy bits and only handle icon and OnClick. Also this has the added bonus of pulling the tocname field into the data source spec, in case a display wants to show TOC metadata in their config or something.
I will expand the tooltip docs a bit to explain all three methods and why they're needed.
How can I provide better docs on the functions? They're dawn simple as is, I don't know what more is needed.
value and suffix in addition to text seems the best route to me. Using the FPS example:
text = "75.0 FPS"
value = "75.0"
suffix = "FPS"
The display would choose to use value and suffix over text if it wanted to. It would implied that if you provide value you must provide suffix as well. Of course, text must also be provided, for those displays that don't want to muck about with all this suffix crap and just want to display the text.
Yssaril, a table like that wouldn't fire off callbacks, and it's encouraging overuse of tables... we shouldn't do that.
hehe agreed and i like your solution better :) LDB should probably check that if you have a value that you also have text and a suffix otherwise error out :)
LDB will not validate values or perform actions on values. That's entirely up to the addon providing or using the data to do. LDB is just a thin layer between the two addons that fires callbacks when data is changed.
As soon as LDB cares about the data that's being passed around, it stops being a generic, simple library.
The addon providing the data could simply register a callback on itself and update the text whenever suffix or value is changed. But it's probably only ever writing the value out in one place, so it'd be faster and simpler to just write text and value at the same time.
well, let's take my FactionsFu as an example, although there isn't use for the suffix but in theory it could set values. But the display has the form: "<faction>: <rank> - <current reputation>/<max reputation for rank> (<percentage>)"
imho it wouldn't make sense to split that into multiple DOs. And I think this also holds for other addons where the data shown is closely related.
On the other hand, you're trying to get launchers out to reduce the number of DOs shown in config but say that in such cases one should split into multiple DOs which could largely increase the number of DOs.
If it wouldn't use the suffix, then how is it related to the topic? :P
I don't want launchers to be flagged as such to reduce the number of options in the config, I want launchers flagged as such because they serve a completely different purpose and I, like many other users, don't want the things breeding like rabbits all over my bar mod or my minimap. When an addon is provided that handles them in a much cleaner way, I think more people will be interested in that instead of the current lazy approach of "just throw it on the minimap/bar addon.
well, let's take my FactionsFu as an example, although there isn't use for the suffix but in theory it could set values. But the display has the form: "<faction>: <rank> - <current reputation>/<max reputation for rank> (<percentage>)"
imho it wouldn't make sense to split that into multiple DOs. And I think this also holds for other addons where the data shown is closely related.
On the other hand, you're trying to get launchers out to reduce the number of DOs shown in config but say that in such cases one should split into multiple DOs which could largely increase the number of DOs.
The solution might be .value = {"value1","value"} .suffix = {"suffix1","suffix2"}
Displays that doesn't care about value and suffix always use .text anyway. Addons that don't want to handle tables but only strings can just use .text instead too, if type(.value) == "table". It is true that there might be situations where it won't make sense to split it up into multiple DOs.
Rollback Post to RevisionRollBack
To post a comment, please login or register a new account.
I am, of course, open to all feedback. If there's anything you think I should add to the wiki pages on github, let me know.
Github Page, lots more links here, including API docs and downloads.
Please note that you should release addons with the tagged versions only, never release addons with the version from the master branch, it is considered ALPHA. Also, don't remove the library from "no externals" versions of addons, there is no standalone version and never will be!
-
View User Profile
-
View Posts
-
Send Message
Forum ModeratorDon't split the specification.
the only difference between the two things you noted as seperate specifications is, that the one will have the launcher attribute set and will thus most likely not change text nor expect the display to have it shown. Besides that, they are based on the smae spec so all you get is doublicated specification text making it harder to read the specs.
Don't set attributes as required.
The spec shouldn't mark anything as required. For example, a changing icon could be used by an addon to indicate data so there would be no text. Or a launcher could only provide a label (or even have the display fallback to the DOs name). Sure, a launcher needs an OnClick handler to be functional, but that shouldn't be part of the specs... anyone trying to do one without it is doomed to fail anyways ;)
Better documentation on tooltips.
After reading through the specs and having some hard time I figured out that there are currently three ways tooltips can be handled:
- the display provides and handles a tooltip that is populated via the OnTooltipShow attribute
- the DO provides a (populated) tooltip that is handled by the display
- the DO handles the tooltip in reaction to OnEnter/OnLeave
Currently this is only documented implicitly through the attributes.
Better documentation on function arguments.
Currently, the arguments are only noted inside the documentation text but in order to have the function work properly they should be noted more explicit I think.
The way he did it was to put "FPS" or "XP" etc. in .label, then color it and concatenate it with .text. In the .text he only gives the number, like "24".
At the same time I read the docs Tekkub put up, and I started putting stuff like "Framerate" in .label and "24 FPS" in .text. We had a discussion about it and I didn't want to force him to change the way he did things, I had added a temporary key named .unit, which he too started to use as "FPS, "MiB" or "XP"...
.unit is just way too specific, and it is not a good solution. Well, I have a suggestion for keys that might help this problem:
.value - if the display displays a number, set it here (could be "24", when .text would be "24 FPS")
.suffix, - text to append behind .value or text (could be "FPS", when .text would be "24 FPS")
All should be optional of course, and text should always provide something for displays that don't support this optional stuff. The goal here is keeping stuff simple, but this is needed if the displays should be able to set the color/hide the suffix, and Funkeh and I wouldn't mind being able to. I don't think optionally providing .value and .suffix would be too specific. Anyone having some ideas on how to solve this the best without making Funkeh cry? :) He wants his colors!
-
View User Profile
-
View Posts
-
Send Message
Curse Premiumalso about this tooltip stuff, which is the most advised method of showing it (personally I don't understand why .OnEnter and .OnLeave isn't enough).
-
View User Profile
-
View Posts
-
Send Message
Forum ModeratorI want
.text = 100 .unit = FPS
OR
.text = 100FPS
(dependent on the author)
NOT
.text = 100FPS .unit = FPS
Inconsistency like these will only end up on people replicating existing plugins for minor changes, rendering the route of LDB pointless because of incompatibilities with viewers.
This leaves the problem that it would be nice to have a way to set the color of the unit/suffix in the display, and I think this is why Funkeh doesn't put "fps" for example in his .text. Funkeh and I haven't really been able figure out the best way to do things.
So bottom of line is: The spec needs to be stricter and Funkeh would like a way to color his unit/suffix. Hopefully some of the guys who started the spec can help clear this up.
-
View User Profile
-
View Posts
-
Send Message
Forum ModeratorYou mean me?
I originally started .label as an optional method for plugins to use so display addons could customize it the way *they* wanted and still not have it look like rubbish if they didn't support it since you just had the raw value in text. Now what's happened is you've changed the way label is used because of, imo, a bad description by Tekkub. I'm not willing to argue this to the end of time so I dumped label for .unit since you were using that in some sane way to find out you're double using unit. No information should ever be doubled in my opinion, choose to show it in one method or another.
As to a name, that really doesn't bother me as long as we can have a global standard.
I'm willing to merge the specs, anyone have a good argument against it? It would actually make things simpler in the end, and might encourage more people to flag their DO's as launchers when they really are, and let the display addons chose to just not implement all the fancy bits and only handle icon and OnClick. Also this has the added bonus of pulling the tocname field into the data source spec, in case a display wants to show TOC metadata in their config or something.
I will expand the tooltip docs a bit to explain all three methods and why they're needed.
How can I provide better docs on the functions? They're dawn simple as is, I don't know what more is needed.
value and suffix in addition to text seems the best route to me. Using the FPS example:
text = "75.0 FPS"
value = "75.0"
suffix = "FPS"
The display would choose to use value and suffix over text if it wanted to. It would implied that if you provide value you must provide suffix as well. Of course, text must also be provided, for those displays that don't want to muck about with all this suffix crap and just want to display the text.
Yssaril, a table like that wouldn't fire off callbacks, and it's encouraging overuse of tables... we shouldn't do that.
-
View User Profile
-
View Posts
-
Send Message
Forum ModeratorAs soon as LDB cares about the data that's being passed around, it stops being a generic, simple library.
The addon providing the data could simply register a callback on itself and update the text whenever suffix or value is changed. But it's probably only ever writing the value out in one place, so it'd be faster and simpler to just write text and value at the same time.
http://github.com/tekkub/libdatabroker-1-1/wikis/data-specifications
-
View User Profile
-
View Posts
-
Send Message
Forum Moderator-
View User Profile
-
View Posts
-
Send Message
Forum Moderatorimho it wouldn't make sense to split that into multiple DOs. And I think this also holds for other addons where the data shown is closely related.
On the other hand, you're trying to get launchers out to reduce the number of DOs shown in config but say that in such cases one should split into multiple DOs which could largely increase the number of DOs.
I don't want launchers to be flagged as such to reduce the number of options in the config, I want launchers flagged as such because they serve a completely different purpose and I, like many other users, don't want the things breeding like rabbits all over my bar mod or my minimap. When an addon is provided that handles them in a much cleaner way, I think more people will be interested in that instead of the current lazy approach of "just throw it on the minimap/bar addon.
The solution might be .value = {"value1","value"} .suffix = {"suffix1","suffix2"}
Displays that doesn't care about value and suffix always use .text anyway. Addons that don't want to handle tables but only strings can just use .text instead too, if type(.value) == "table". It is true that there might be situations where it won't make sense to split it up into multiple DOs.