Re: Defining Views Terminology

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> [NOTE: this is my summary of my interpretation of *part* of the 
> discussion at the views workshop at Apachecon. In other words I have 
> tried to represent the views of those present, but may have got some 
> bits wrong - this is a document for discussion not a final document.
> 
> You can get the audio from that workshop at 
> http://svn.apache.org/viewcvs.cgi/forrest/events/apachecon-eu-2005/workshop.ogg?rev=225666&view=log 
> ]
> 
> What *is* a forrest:view?
> -------------------------
> 
> Some of the confusion over Views seems to have come about because they
> do much more than just replace skins. They add a whole new feature set.
> We therefore decided to define some terminology to help clarify the
> situation.

The sooner that we get this settled the better.

I have been trying to come up with possible names
at least for the top-level names.

Stucturer: the thing that coordinates all the
bits-and-pieces and builds a stucture, probably
various structures. This provides hooks, the name
goes with the building connotation.

Themer: The process that gathers and applies the
theme or themes.

> Themes
> ......
> 
> Currently our processing pipeline looks something like this:
> 
> src -> input plugins -> core ->  skinning -> output plugins. -> out
> 
> Both skinning and output plugins are optional, so we could do any of the
> following processes when working on, for example and OOo document:
> 
> OOo -> OOo plugin -> core ->  skinning (html) -> HTML
> 
> or
> 
> OOo -> OOo plugin -> core ->  skinning (FO) -> output plugins -> PDF
> 
> or
> 
> OOo -> OOo plugin -> core -> output plugins -> TEXT
> 
> Views currently only produce HTML and the process looks like this (at
> least I think it does ;-)):
> 
> OOo -> OOo plugin -> core (views) ->  HTML
> 
> We can see that forrest:views remove the skinning system. But what about 
>   the look and feel of the page. A view does not provide that. When 
> forrest:views output XHTML we use CSS for the look and feel:
> 
> 
>                                       CSS
>                                        |
>                                       \|/
> OOo -> OOo plugin -> core (views) ->  HTML
> 
> =======================================================
> Themes are the look and feel of a forrest output format
> =======================================================
> 
> forrest:views
> =============
> 
> In order to enable themes to consist of nothing more than Look and Feel 
> configurations there needs to be some structure to the document that 
> allows the theme designer to correctly apply the theme to the output 
> generated by Forrest. It is the job of a forrest:view to define this 
> structure.

So forrest:structurer ...

> But there is more to a forrest:view than just structure. Sometimes the 
> view also defines content that should be aggregated with the source 
> file. For example it may define the copyright information, a search box 
> or even some dynamic content, such as an RSS feed.

The name "structurer" still works, this time as a doing word
The structurer needs to marshall the content to help it
to build the structure.

> So now we have:
> 
>                                      theme
>                                        |
>                                       \|/
> OOo -> OOo plugin -> core (views) ->  HTML
>                      |        /|\
>                     \|/        |
>                  forrest:contracts
> 
> Here the forrest:contracts define the templated content that should be 
> inserted into the final document. These may create a new request in 
> order to generate the content, such as an RSS feed, or they may insert 
> statically defined content, such as a copyright notice.

The name forrest:contracts seems to be applicable.

> Now, we need to be able to re-introduce different output formats, so the 
> final processing for views looks like this:
> 
>                                           theme
>                                             |
>                                            \|/
> src -> input plugin -> core (views) -> output plugin -> output
>                        |        /|\
>                       \|/        |
>                    forrest:contracts
> 
> 
> View
> ....
> 
> Forrest:views add a structure to the generated page that
> clearly identifies all the content in the final output. This is
> achieved through the use of <div class="someClass"> elements. In order
> to define these divs the view definition file has the concept of a hook.
> this tells the view system to create a <div> element with a given class
> name. For example:
> 
> <forrest:hook name="aDiv">
>   ...
> </forrest:hook>
> 
> results in
> 
> <div class="aDiv">
>   ...
> </div>

Yes, forrest:hook is fine. The structurer hangs the hooks.

> =================================================================
> Hooks are only used to define the structure in our output that is 
> required to enable a theme to apply its look and feel.
> =================================================================
> 
> The final job of views is to define where content should be placed 
> within the structure of the page. This is done by using a 
> forrest:contract.

Is this a different use for forrest:contacts? Or does
the same contract define what and where. If different
then i wonder about names like "marshall" that knows
where to get the content and "placer" that knows where
to put it.

> For example:
> 
> <forrest:contract name="content-title"/>
> 
> =================================================================
> Contracts define templates that are used to place content in
> a Forrest document.
> =================================================================
> 
> NOTE: contracts may be static or dynamic. A dynamic contract will make a 
> further request for content whenever it is used, whereas a static 
> contract will always generate the same content.
> 
> View FAQs
> =========
> 
> Does a view define how the page is displayed?
> 
> No. A view defines *what* is displayed. How it is displayed is defined
> by the Theme.
> 
> ----
> 
> What does a view define?
> 
> A view defines the structure of a document and the contracts that are to
> be placed within that structure.
> 
> ----
> 
> Why does a view define a document structure?
> 
> The view structure is used to allow a theme to be created independently
> of the view.
> 
> ----
> 
> What is a Theme?
> 
> A theme is a description of how a page is to be displayed. It describes
> the look and feel of the page, but does not define any content.

We need more detail of how the "theme" process
operates to see if we need names for subtasks.

> ----
> 
> What does a contract define?
> 
> A contract defines what content will be placed at a specific point in
> the document structure described by a View.

I get the feeling that there should be two separate
roles. The same content could go in two different places
e.g. the message of the day.

> ----
> 
> What is a nugget?
> 
> A nugget is a small piece of dynamic content described by a contract.

Or use the name "piece".

> --------------------------------------------------------------
> 
> I do hope someone will take the time to put this into the forrest:views 
> documentation once the content has been discussed and agreed.

Let us settle on the terminology and start the renaming
and documentation cleanup.

-David

Re: Defining Views Terminology

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> David Crossley wrote:
> >Ross Gardler wrote:
> >
> >>Some of the confusion over Views seems to have come about because they
> >>do much more than just replace skins. They add a whole new feature set.
> >>We therefore decided to define some terminology to help clarify the
> >>situation.
> >
> >The sooner that we get this settled the better.
> 
> +1, especially since Thorsten is refactoring things now. I'm not going 
> to comment on the thread just yet since I started it, I'd like to hear 
> other views first.
> 
> I will add one more point though. We are using the "ft:" namespace 
> identifier for templates, this is the same identifier used  for 
> forms-templates in Cocoon. We should think about a different identifier 
> (I know we can change it if there is ever a clash, but wouldn't it be 
> better to plan forward there is already an occasion where forms are 
> being used in an experimental Forrest site).

That name "templates" was missing from your overview.
We need to define its role and perhaps find a better name.

-David

Re: Defining Views Terminology

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Ross Gardler wrote:
> 
>>[NOTE: this is my summary of my interpretation of *part* of the 
>>discussion at the views workshop at Apachecon. In other words I have 
>>tried to represent the views of those present, but may have got some 
>>bits wrong - this is a document for discussion not a final document.
>>
>>You can get the audio from that workshop at 
>>http://svn.apache.org/viewcvs.cgi/forrest/events/apachecon-eu-2005/workshop.ogg?rev=225666&view=log 
>>]
>>
>>What *is* a forrest:view?
>>-------------------------
>>
>>Some of the confusion over Views seems to have come about because they
>>do much more than just replace skins. They add a whole new feature set.
>>We therefore decided to define some terminology to help clarify the
>>situation.
> 
> 
> The sooner that we get this settled the better.

+1, especially since Thorsten is refactoring things now. I'm not going 
to comment on the thread just yet since I started it, I'd like to hear 
other views first.

I will add one more point though. We are using the "ft:" namespace 
identifier for templates, this is the same identifier used  for 
forms-templates in Cocoon. We should think about a different identifier 
(I know we can change it if there is ever a clash, but wouldn't it be 
better to plan forward there is already an occasion where forms are 
being used in an experimental Forrest site).

Ross