forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <ferdin...@apache.org>
Subject Re: RT: Storage of Properties
Date Sat, 23 Feb 2008 04:43:12 GMT
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?

>>       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.

> skin and dispatcher can share resources as demonstrated with the fo
> stuff. 

+1 That is cool.

> In the same way it is possible to share *-to-html stylesheets
> between skins and dispatcher (if capsuled like in the pdf plugin).

+1

> However skins have one major different approach to dispatcher:
> Skins await an aggregation (without it will not work at all) mix out of 
> - content
> - skinconf
> - navigation
> - tabs
> This mix are normally used in one big stylesheet document-to-html.xsl
> which makes it very hard to implement url specific stuff.

Actually site-2-xhtml, isn't it.
But yes. I agree.


> 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.

Individually in each contract make technological sense but 
is hard on the user and ugly to maintain.

Can structurer create a configuration layer for each set of 
contracts used? Meaning each contract would have publish his 
own original properties 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".

> 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?

> The property system should be decouple completely from any
> presentational engine (being skin or dispatcher). 

+1

> 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?

>> - 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.

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

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

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.

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

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. 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.

>> Each input-plugin could tag there input with ids or 
>> classes and influence
>>      final formatting by offering a css-block to be inserted 
>> at the end of the Forrest
>>      css and before user css-files.

And this is the mechanism to pass the styles.

>> 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?


>> 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.

>> 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.

Defining a grammar for each property would avaid errors in 
several ways:

- A user could not enter invalid properties
- 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.
- New properties will be offered by a validating editor even
   in project files that were created before the property
   even exists.
- 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.

>> Blocks of included data that hinder validation (such as 
>> extra-css in skinconfig) should be
>> avoided. Grammatically different information like css or 
>> xml-properties should be kept separate.
> 
> 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?

>> ** 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.

>> New properties should automatically become available to all 
>> projects and entries in project-files would
>> only be required if I wanted to set the property different 
>> from the default.
> 
> That is how ForrestConfModule.java works.

OK, found your commit

>> A clear hierarchie should make it easy where to look.
>> In order of decreasing priority
>>
>> project properties > skin/dispatcher properties > plugin 
>> defaults > Forrest defaults
> 
> See the initialize() method there is the actual order but
> skin/dispatcher properties are normal plugin defaults.

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?)
  - %Global home%/forrest.properties.xml
    (where would that be?)
  - %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.

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


>> 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.


> 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?

> 
>> 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 ...

>> 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.


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.

Best regards,
Ferdinand Soethe


Mime
View raw message