forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thorsten Scherler <thors...@apache.org>
Subject Re: RT: Storage of Properties
Date Sun, 24 Feb 2008 12:17:05 GMT
On Sat, 2008-02-23 at 05:43 +0100, Ferdinand Soethe wrote:
> Thorsten Scherler wrote:
> 
> > Actually what you describe already exists and we are using it. The core
> > is:
> > https://svn.apache.org/repos/asf/forrest/trunk/main/java/org/apache/forrest/conf/ForrestConfModule.java
> 
> OK, can I learn how it works other than looking at the 
> source code?

Our mailing list archive. AFAIR there is no documentation in ours docs
but with the amount of threads around this topic it should be.

Here are two out of many:
http://marc.info/?l=forrest-dev&m=115516934127695&w=2
http://marc.info/?t=115493806000005&r=1&w=2

> 
> >>       copyright, logos etc
> > 
> > The last one is for me presentation.
> 
> I disagree. To display a logo or the size and placement of 
> it is presentation. The logo itself, like a publishers name 
> is project metadata.

Hmm, since a logo is only visible in presentation its for me
presentational. Since it can be used from different output plugins I
agree it should go into project properties. 
...
> 
> > The dispatcher does not need any input to work, nor does it use "one big
> > stylesheet document-to-html.xsl". The structurer (based on jx) is used
> > to define which functionality should be used and passes extra
> > configuration parameter to the contracts.
> 
> Yes, makes a lot of sense.
> But where would the properties for a certain set of 
> contracts (used in one dispatcher config = a skin) be stored.

In the structurer files (or panels) e.g.
http://svn.apache.org/viewvc/forrest/trunk/whiteboard/plugins/org.apache.forrest.themes.core/themes/common/panels/common-html.panel.xml?view=markup
<forrest:contract name="branding-css-links">
<!-- More information around this contract
        http://marc.theaimsgroup.com/?l=forrest-dev&m=113473237805195&w=2
        -->
    <forrest:property name="branding-css-links-input">
      <css url="common.css"/>
    </forrest:property>
  </forrest:contract>

However each contract can as well access all forrest properties (e.g.
index.props in a dispatcher project will show them) by implementing
following lines:
<!-- If you need default variables: -->
<xsl:param name="defaultVariables" select="'test.html'"/>
<!-- then extract the variable like: -->
<xsl:variable name="skin-img-dir" select="$defaultVariables/*/*[@name='skin-img-dir']/@value"/>

So you see the dispatcher implements following configurations:
- global - forrest.properties.xml
  Accessible via <xsl:param name="defaultVariables" /> in any contract.
- theme/url specific via structurer/panel
  
> 
> Individually in each contract make technological sense but 
> is hard on the user and ugly to maintain.

There are standalone contracts that are not configurable, but most are
configured like described above.  

> 
> Can structurer create a configuration layer for each set of 
> contracts used?

Yes, that is one of its main technological function.

>  Meaning each contract would have publish his 
> own original properties 

No, contracts do not have default properties. They are coming from the
structurer.

> but a dispatcher config would offer 
> a configuration file that can override each of these 
> original properties to configure the properties in the 
> context of a "skin".

Theme - yes.

> 
> > Like I said in the other mail: "The only plugin that should
> > use skinconf is a skin plugin (if it would exist)!"
> 
> Is what you mean by skin-plugin what I explained in the para 
> before? No, is it?

No, the skin plugin is an output plugin that contains all skin specific
pipelines and matches which has been moved out of the core. Very similar
to your work on the pdf plugin (moving all fo stuff to the plugin).

...
> > If you look into 
> > https://svn.apache.org/repos/asf/forrest/trunk/whiteboard/cocoon-2.2-blocks/
> > there I ported only three plugins/core functionality to
> > cocoon-2.2-blocks/. Meaning it is very much possible.
> 
> My java is still a bit limited to do that.
> What are you saying?

The two blocks 
- locationmap/
- propertiesGenerator/

are mainly responsible for the configuration of forrest. However in the
above case they are decoupled from the core.

> 
> >> - Plugins
> >>   create properties, set default values, allow overriding 
> >> these values in a project
> >>   = plugin-dependant properties
> >>      page format and other settings specific to pdf-generation
> >>   = specific css to be used when generating html from an 
> >> input-plugin
> > 
> > IMO that are presentational properties and should be handled and defined
> > from the presentational engine. The core should not process them. 
> 
> Yes and No.
> Yes: They are presentational properties.
> No: They cannot be handled by the presentational engine
>      because it would break the plugin-concept or make it
>      very inflexible like it is now.

I do not see it like this.

> 
> To make myself clearer:
> 
> The plugin concept allows us to add support for all kinds of 
> xml-grammars to Forrest. It does not at the moment allow a 
> plugin
> 
> - to add reliably add class-information
>    this is a matter of fixing the pipelines to pass class and
>    id reliably

Do not understand.

> 
> - to add styling hints that suggest to the presentational
>    engine how these classes could be presented.

That is very much possible (not for skins but for dispatcher). Skins are
very limited in this context since plugin cannot add output specific
processing to skins. However that is not true for the dispatcher. e.g.
the solr plugin is a very good example where we do this.

> As a result a plugin can at best add class attributes (and 
> hope they don't disappear) and the user can then either 
> accept that their classes "instruction step" or "instruction 
> result"  or "board members" will all look the same (perhaps 
> like a bulleted list) or they take the extra step of adding 
> extra css or adjusting the skin or a contract.

css is always presentational. All above is a problem of skins but is
solved in the dispatcher.

> 
> And that is what I see as breaking the plugin-concept here.

No the plugin-concept works very fine as it is IMHO.

> 
> By being able to offer style hints, an input-plugin could 
> pass the information that the list of board members might 
> look good with a little people logo in front of it.

This is perfectly possible with the current code.

>  And the 
> "skinning" could then deside to take that hin, do something 
> of its own with a class or ignore the class and hint altogether.

That is how dispatcher work but not skins. You describe the many
problems of skins as presentational engine but the dispatcher solves all
of the above.

...
> >> Many properties will be used and might even be set by 
> >> different components.
> >> For example the pdf-plugin might come with a basic set of 
> >> properties and defaults.
> > 
> > That is why we have default.plugin.properties.xml 
> 
> ... searching ...
> 
> Ah, ok. Thanks.
> org.apache.forrest.plugin.input.projectInfo\default.plugin.properties.xml
> has one.
> 
> Could we perhaps add a documented version of it to the 
> plugin template?

Sure, better we once and for all document our properties system where we
mention this file as well.

> 
> 
> >> But a skin might also offer defaults for pdf-output matching 
> >> the skins specific style.
> > 
> > If it is kept in the project properties there is no problem otherwise it
> > is hard to control which plugin has preference. AFAIR the one that is
> > first mentioned in the required plugins, but not sure.
> 
> Agreed. But this a problem to be solved anyway. And so far 
> order of loading (= order of mention in the required 
> plugins) would be a good and realiable start.

Not reliable since we never have tested whether it is the case.

> >> The ability to validate a properties-storage should be kept 
> >> while the process of extending
> >> the property set in plugins or skins should be simplified.
> > 
> > Hmm, not sure what you mean with validation of properties.
> 
> I meant that we don't simply check if a property adheres the 
> general structure of the file
> 
> key=value or <key>value</key>
> 
> but use the full power of relax or schema to
> 
> - check if a property is valid (offered in the context of
>    checking)
> - has a valid value for this propertys.
> 

Very interesting!

> Defining a grammar for each property would avaid errors in 
> several ways:
> 
> - A user could not enter invalid properties

agree

> - Properties that are no longer offered could be flagged
>    when validating the properties or will be shown next time
>    the files is edited with a grammar aware editor.

nice

> - New properties will be offered by a validating editor even
>    in project files that were created before the property
>    even exists.

nice

> - The value of a property can be checked and entry of valid
>    values can be supported by the editor. For example if the
>    skin placement of the search dialog had the legal
>    values of "top" and "right", a grammar aware editor would
>    only offer and allow one of these.
>    No more in file documentation that might long be outdated
>    in my project properties files. Just editing my project
>    properties would show me what is legal NOW.

totally agree that having this ability rocks!

Not sure about implementing it ATM but this should be discussed in a new
thread.

...
> > Actually skinconf had become a mix of presentational properties and
> > other properties (like the fo ones). IMO one need to move (and flatten)
> > all common properties of skinconf into properties.xml files. This way
> > they got picked up by ForrestConfModule.java and are usable everywhere
> > in forrest.
> 
> 
> +1 to seperate them.
> 
> But why flatten? What's wrong with bundling properties that 
> belong together in a parent element?

With flatten I mean: 

In forrest.properties or forrest.properties.xml. That would mean to
flatten some 
<pdf>
   ...
    <page size="letter" orientation="portrait" text-align="left"/>

into e.g. forrest.properties.xml:
<properties>
  <property name="pdf.page.size" value="letter"/>
  <property name="pdf.page.orientation" value="portrait"/>
  <property name="pdf.page.text-align" value="left"/>

The hierarchy is reflected in the name. 

> 
> >> ** Clear hierarchical structure and inheritance **
> >>
> >> I'd much prefer inheritance to the current need of copying 
> >> new properties into existing project files.
> > 
> > Hmm, that is only true for skinconf. We have a fallback in place for
> > forrest.properties et.al. That is the reason why I said "The user would
> > need to update/migrate/implement this changes to the properties file
> > (and only this changes since we are using fallbacks in properties)."
> 
> Hmm. Perhaps a question of handling this. I agree. If the 
> project properties started out as any empty file it would work.

David has cleaned up a lot of forrest.properties files to only add what
is needed. We are close to a blank file.

...
> >> A clear hierarchie should make it easy where to look.
> >> In order of decreasing priority
...
> OK. Thanks for the pointer.
> The order is
> 
>   - %Project Dir%/forrest.properties
>   - %Project Dir%/local.forrest.properties.xml
>   - %Project Dir%/forrest.properties.xml
>   - %User Home Dir%/forrest.properties.xml
>     (where is user home on windows, or rather what is
>     the dir name in application data dir?)

AFAIR c:/documents and settings/USER/forrest.properties.xml

>   - %Global home%/forrest.properties.xml
>     (where would that be?)

wheresoever you define global.home (we do not have a default)

>   - %forrest home dir%/main/default.forrest.properties.xml
> 
>   - plugins properties in order they are loaded in required
>     plugins
> 
>   - %forrest home dir%/main/default.forrest.properties
> 
> Why are the plugins wedged in between the xml and the 
> non-xml-version of the default properties.

Not sure myself.

> 
> Would it not make more sense to load them after both?

Yeah, why not.

> 
> 
> >> This also means that a skin can, but doesn't need to set 
> >> anything for pdf-generation if it didn't want to change 
> >> anything.
> > 
> > yes, but it is not the skin that sets this properties but the project
> > configuration.
> 
> well, I was thinking that the skin could set/add properties 
> that could then be overridden by the project properties. The 
> skin setting the default for properties introduced by a skin.
> 

That could be possible.

> 
> > The
> > https://svn.apache.org/repos/asf/forrest/trunk/plugins/org.apache.forrest.plugin.output.inputModule/
is returning such properties if ask for the "properties" module.
> 
> Ah, reading the docs for the plugin helps :-)
> 
>  > http://localhost:8888/module.properties.properties
> 
> to list properties.
> 
> Cool!
> Can I also get a list where the source of a setting is 
> shown? How about adding the source of a setting as a third 
> element?
> 

Yeah would be possible, what would be the benefit?

> > 
> >> Meaning: Insert the 
> >> plugin-properties before the Forrest core properties, the 
> >> insert the skins
> >> properties before the plugin properties.
> > 
> > Actually for me skinconf/contract properties are apart from other
> > properties since they are normally view dependent.
> 
> Can the input plugin offer another pipeline for that?
> And also for CSS-Aggregation while we are at it ...

Regarding extra css and a like that is perfectly solved in the
dispatcher where each plugin can offer extra css as it pleased (as css
contract) and the dispatcher can pick it up or ignore it.

Yet another skin limitation.

> 
> >> Validation is tricky. Ideal would be that every source of 
> >> properties publishes a realx-NG grammar-module in a way that 
> >> all
> >> modules can be aggregated in a pipeline. 
> > 
> > IMO properties files should be flat. Like forrest.properties/~.xml and
> > the standard java properties. This way we have only one dtd/ng schema
> > and the validation is trivial.
> 
> IMHO keeping validation trivial only saves work on the part 
> of the author of new properties while it increases the risk 
> of errors for all users and programmers.
> 
> As I mentioned above, adding true validation of property 
> name and value avoids configuration errors by the user and 
> makes it very clear to any programmer using the property 
> what values he or she has to deal with.

Very good point and having validation in an editor has many benefits and
will save a lot of times. IMO we should start a new thread around the
validation of properties as you describe.

> 
> 
> Thanks Thorsten for taking the time. Now I can actually 
> understand what you are trying to so and help move those 
> pdf-specific settings into the plugin-properties.

Perfect, hopefully somebody can find the time to document the outcoming
of the thread.

salu2
-- 
Thorsten Scherler                                 thorsten.at.apache.org
Open Source Java                      consulting, training and solutions


Mime
View raw message