Pluggable XML Info
Owen Winkler
We need to move the Info method of Plugin and Theme up to Pluggable so
that they use the same stuff. As a result, we need to form the XML used
to define plugin/theme info a little better. As a result of changing
the format, all existing themes will explode.
This has to be done, because the areas that are published for a theme
need to go in that XML, and the XML needs to be stable.
I want to do this this week. I can publish a schema for the XML on the
wiki (Relax?), and others can look it over.
The schema should allow for themes and plugins to use the same format of
xml data, since they're both Pluggable. Soon after the info method of
plugins would go away to be replaced by the Pluggable info method,
meaning plugins wouldn't need to execute any more to get their infos.
It would just use the xml file instead (although the plugin should still
be sandboxed so it's known to work).
Your consideration is appreciated.
Owen
Arthus Erea
Sounds fine, but please document the schema thoroughly.
Also, please be sure that some elements are allowed only for plugins/
themes. Ex. I still need to be able to include themeconfig in the xml.
~Arthus
rick c
correct in concluding this means that Plugin can go away completely?
Which would also mean that all plugins should derive from Pluggable,
and also need rewritten?
Rick
Ali B.
Owen Winkler
> I think we'd need to hold on to Plugin for a little Longer. We may get
> to a point were we need something implemented in plugins only. If we
> switch now and need that in the future, we'd need to break plugins
> again. This sure is a possibility.
>
> On Tue, Jun 2, 2009 at 2:23 PM, rick c <rickc...@gmail.com
> <mailto:rickc...@gmail.com>> wrote:
>
>
> Since info() is the only thing left in Plugin at the moment, am I
> correct in concluding this means that Plugin can go away completely?
> Which would also mean that all plugins should derive from Pluggable,
> and also need rewritten?
The Plugin class is used for more than just a container for its methods.
Being derived from the Plugin class denotes a certain status that is
used by the rest of the code.
Owen
rick c
On Jun 2, 8:15 am, Owen Winkler <epit...@gmail.com> wrote:
> Ali B. wrote:
> > I think we'd need to hold on to Plugin for a little Longer. We may get
> > to a point were we need something implemented in plugins only. If we
> > switch now and need that in the future, we'd need to break plugins
> > again. This sure is a possibility.
>
> > <mailto:rickcock...@gmail.com>> wrote:
>
> > Since info() is the only thing left in Plugin at the moment, am I
> > correct in concluding this means that Plugin can go away completely?
> > Which would also mean that all plugins should derive from Pluggable,
> > and also need rewritten?
>
> The Plugin class is used for more than just a container for its methods.
> Being derived from the Plugin class denotes a certain status that is
> used by the rest of the code.
>
> Owen
a while.
Rick
Chris J. Davis
to review.
drzax
S.
Owen Winkler
http://schemas.habariproject.org/Pluggable-1.0.xsd
Validated XSD:
http://pastoid.com/azc+/
Sample XML:
http://pastoid.com/aya+0/
I can't find an online tool to validate the XML using the XSD, but the
XML should validate if you have a desktop tool that supports XSDs.
Owen
Arthus Erea
Owen Winkler
>
> 1) Should "type" be required for <container> or can we default to fieldset?
> 2) Can we make the "attribute" sections optional for controls, allowing
> them to be attached to the main item as well? The attribute sections are
> only needed for translation.
We have a responsibility to make good, sensible formats where we can,
and I think that takes priority over letting theme developers take
shortcuts. Assume that every themer would love to have their theme's
strings translated - there's no reason to avoid starting out with the
data in the right place for that to happen.
I see the choices as two: 1) make the files shorter by omitting values
and using obscured, if documented, defaults or 2) make the files longer
but necessarily obvious. I like choice 2 for the little suffered
discomfort of clarity.
> 3) You are aware that there /will/ be many different, optional controls
> which different formcontrols require. Does the accommodate that? Does it
> matter?
If by "optional controls" you mean "optional attributes", then yes, I am
aware, and it should accommodate that as-is. Nonetheless, I am human
and fallible, so I posted it rather than keeping it to myself that
others could verify my work and provide potential corrections.
I suggest that if you have a particular concern that you think this
format will not address, then you bring it to light, like in point #4 below.
> 4) I don't see anything in there for <option> children. Should those be
> included?
Yes. I'll add that in a new iteration.
> 5) Can we make storage optional? The whole point is to make it easier
> for themers to create configuration, and forcing them to think about
> storage makes that harder. If not supplied, we'd provide
> an intelligent default based upon the form location.
If storage is optional, then the default should be "null:null", since
specifying no storage should indicate that no storage is required, and
the developer will handle it with code.
Remember that this is not the Theme XML spec, it is the Pluggable XML
spec. As such, it makes no sense to default storage to one place when
the bulk of configuration options may be stored elsewhere by the other
pluggable type.
Owen
Arthus Erea
However, I feel like you are making it unnecessarily complicated for
themers. The whole idea of allowing this XML is to make it simpler,
not more complicated.
I understand this is the Pluggable XML, which is fine. Some of my
points only apply to themes: they would only work as such in themes. I
don't think you are being pragmatic in your demands that plugins and
themes behave in exactly the same way. Where possible, we should make
it easier for themers or there is no point to any of this work. 0.7
should make it EASIER to do a theme, not HARDER.
If, where you disagree with me, you can provide a good reason for it,
I am wiling to accept that. Otherwise, I don't consider unnecessary
complication just for the sake of "standardization" unacceptable.
On Jun 3, 11:35 am, Owen Winkler <epit...@gmail.com> wrote:
> Arthus Erea wrote:
>
> > 1) Should "type" be required for <container> or can we default to fieldset?
> > 2) Can we make the "attribute" sections optional for controls, allowing
> > them to be attached to the main item as well? The attribute sections are
> > only needed for translation.
>
> We have a responsibility to make good, sensible formats where we can,
> and I think that takes priority over letting theme developers take
> shortcuts. Assume that every themer would love to have their theme's
> strings translated - there's no reason to avoid starting out with the
> data in the right place for that to happen.
so translation must be encouraged.
However, it is not mutually exclusive. I don't like your idea that we
should do NO sensible defaults. What is wrong with defaulting type to
fieldset on <containers>?
> I see the choices as two: 1) make the files shorter by omitting values
> and using obscured, if documented, defaults or 2) make the files longer
> but necessarily obvious. I like choice 2 for the little suffered
> discomfort of clarity.
about making them clearer. I'm not sure where you suddenly got the
idea that sensible defaults are a bad thing.
Please, try for once to not think like a developer. As a themer, there
is pretty much no reason I would have <containers> that aren't
fieldsets. You should not make my job more complicated for no good
reason.
> > 3) You are aware that there /will/ be many different, optional controls
> > which different formcontrols require. Does the accommodate that? Does it
> > matter?
>
> If by "optional controls" you mean "optional attributes", then yes, I am
> aware, and it should accommodate that as-is. Nonetheless, I am human
> and fallible, so I posted it rather than keeping it to myself that
> others could verify my work and provide potential corrections.
necessarily be. The spec should support this.
> I suggest that if you have a particular concern that you think this
> format will not address, then you bring it to light, like in point #4 below.
they will be ahead of time. I do not know what every possible
formcontrol will require, so we should make sure the format is
extensible.
> > 4) I don't see anything in there for <option> children. Should those be
> > included?
>
> Yes. I'll add that in a new iteration.
> > 5) Can we make storage optional? The whole point is to make it easier
> > for themers to create configuration, and forcing them to think about
> > storage makes that harder. If not supplied, we'd provide
> > an intelligent default based upon the form location.
>
> If storage is optional, then the default should be "null:null", since
> specifying no storage should indicate that no storage is required, and
> the developer will handle it with code.
is not written for you, it is written for themers with relatively
little programming experience.
I do not expect the majority of themers to be able to write a storage
handler. I expect them to be able to hook into the system which
intelligent developers provide. For most themers, I do not think
null:null: makes sense as a sensible default. If I add a text control
with a name, I don't expect that it won't be saved, I expect I'll be
able to access it as a theme option.
> Remember that this is not the Theme XML spec, it is the Pluggable XML
> spec. As such, it makes no sense to default storage to one place when
> the bulk of configuration options may be stored elsewhere by the other
> pluggable type.
Of course this is the Pluggable XML spec. The default for PLUGINS can
be null:null. For themes it should be theme:name. To demand that there
are absolutely no differences between what themes and plugins leverage
is shortsighted and impossible.
Please, I urge you to work from the presumption that the person who
will be writing this XML does *not* know as much programming as you.
Their PHP and XML experience is most likely limited. At present, your
proposal, and your insistence to not provide any sensible defaults,
does not accommodate that person.
Owen Winkler
> Owen, I understand that you want to make a clear format.
>
> However, I feel like you are making it unnecessarily complicated for
> themers. The whole idea of allowing this XML is to make it simpler,
> not more complicated.
Yes, producing one static, documented format that doesn't change is more
clear, more simple, than having the file behave in completely different
ways based on the value assigned to a type attribute of the XML's first
node. That's the basis of my entire thesis -- there's no reason to even
debate your additional points.
The alternative to a generic format produces at least two documents,
each including its own differences in how things work. This also
produces much more conditional code, which needs to be maintained. None
of this maintenance and complication of documentation is of benefit to
anyone.
Moreover, this is a first draft, which will also have a first
implementation. I think it will be better to refine from something
generic to something specific than vice-versa.
If it turns out that themers are befuddled by what you perceive as
complication, then we can make adjustments before release or for the
next release. It would be wise to have actual experimental data to
review before making those kinds of assumptions.
Owen
Arthus Erea
Please respond to criticism and admit you're not infallible.
Owen Winkler
> Please write some documentation.
>
> Please respond to criticism and admit you're not infallible.
The Pluggable XML format does need some more written-language
documentation, even though the XSD is mostly complete. (Some guidance
from those who know on how to correct the XSD to work with non-local
validators would be helpful.)
Until that documentation is written (which you are welcome to begin,
instead of waiting for someone else), you can find these resources here:
Pluggable XSD: http://schemas.habariproject.org/Pluggable-1.2.xsd
Sample XML: http://schemas.habariproject.org/pluggable-sample.xml
If while writing the documentation, you have specific questions, posting
them here should yield specific direct answers and input from others.
Regarding another query posed about tying plugins explicitly to Habari
versions --
I'm unsure that this is the best approach, in the same way that I know
that a theme's requiring a specific plugin by name is the wrong
approach. Primarily my opinion on this is based on the concept that
it's not a version of Habari that a plugin targets, but a feature that
Habari provides.
So the question is, should Habari itself provide "features", as included
in the pluggable xml, that plugins can then require or recommend as
needed?
Bear in mind that major version releases of Habari should be API-stable.
So it would be useful to include a single feature of "Habari 1.0" when
that time comes. But for the 0.x branch, features change so often,
especially in the trunk, that simply indicating "0.7" as a requirement
may not be enough. Especially for the useful features that we continue
to modify and add in 0.7, an 0.7 Habari checked out at the beginning of
the branch's life would not have any of the features implied by the
requisite of "0.7".
Owen
Arthus Erea
schema, and apologize for the resultant rudeness.
I would be willing to write some documentation, though keep in mind it
will be my interpretation of a somewhat vague XSD.
For compatibility, I do think it is worthwhile to do both. Habari core
should provide specific features which plugins can test against (ex.
blocks).
However, I do think there is additional value in a <compatible> field.
The <compatible> field simply means "this plugin has been tested to
work with this version." When constructing the extras repository,
that'll be a useful field to leverage.
I imagine that users don't want to have to hunt through Habari
versions and find whether a feature is provided. I think it's useful
for them to be able to see "will this plugin work with my version?"
Regarding trunk development, I actually think <compatible> should only
name released versions. Remember, <compatible> is not strictly
enforced: it'll just say "this plugin might not work with your version
if Habari." For bleeding edge development, I don't think we need to
provide the same seal of testing. Plugins would simply rely upon
features to determine compatibility with HEAD.
~arthus
Ryan Mullins
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd"/>to <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/>
This will make validators look in the right place for xml.xsd instead of looking to http://schemas.habariproject.org/xml.xsd which doesn't exist.
The w3 validator works because it does have a local copy of xml.xsd.Owen Winkler
>
> This will make validators look in the right place for xml.xsd instead of
> looking to http://schemas.habariproject.org/xml.xsd which doesn't exist.
Indeed. Thanks for that.
I've added a little validator script to schemas.hp.o so that you can
test your own XML:
http://schemas.habariproject.org/pluggable_validator.php
If you try to validate this plugin, you'll get an error:
http://svn.habariproject.org/habari-extras/plugins/twitter/branches/0.7-1.x/twitter.plugin.xml
This is because there is no <authrourl> element. If you change that in
the textbox, and move the url as a property of the author element, like
this:
<author url="http://habariproject.org/">Habari Community</author>
Then validate the Text (click that radio button), you'll see it validate.
Hopefully, that'll be a useful tool.
Also note that I've updated the xsd file to 1.3, since limiting required
elements to a specific order was making most plugin XML fail. The side
effect is that there's really no way to say that the XML requires a
<name> element. There are some technical reasons why this is so --
changing them would make other things in the format less desirable.
Owen
Arthus Erea
I have begun work on some written language documentation: http://wiki.habariproject.org/en/pluggable
If anyone else would like to help, I'd greatly appreciate it.