Dispatcher quickstart

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

(After answers i will put this into the Howto Structurer.)

I wanted to quickly see how an existing site goes
with the new Dispatcher.

1) added structurer and themer plugins to forrest.properties
2) deployed structurer plugins with etc/structurer.sh
3) localhost:8888/index.html ... fantastic.

Now use another theme ...

4) added project.theme=pelt to forrest.properties
5) re-start 'forrest run' ... fantastic.

Now i want to add a new what-do-i-call-it (contract?)
For example, lets add the text link at the top right.

Do i need to create a whole new structurer by
copying say pelt.fv to src/documentation/content/xdocs/common.fv
and insert a new contract for the text link.

Say i want to remove the default xml link.

Sorry for asking potentially silly questions.
I am trying to see how to extend/modify an existing
structurer without creating a maintenance problem.

-David

Re: Dispatcher quickstart

[Cyriaque Dupoirieux <Cy...@pcotech.fr>]

David Crossley a écrit :

>(After answers i will put this into the Howto Structurer.)
>
>I wanted to quickly see how an existing site goes
>with the new Dispatcher.
>
>1) added structurer and themer plugins to forrest.properties
>2) deployed structurer plugins with etc/structurer.sh
>3) localhost:8888/index.html ... fantastic.
>
>Now use another theme ...
>
>4) added project.theme=pelt to forrest.properties
>5) re-start 'forrest run' ... fantastic.
>
>Now i want to add a new what-do-i-call-it (contract?)
>For example, lets add the text link at the top right.
>
>Do i need to create a whole new structurer by
>copying say pelt.fv to src/documentation/content/xdocs/common.fv
>and insert a new contract for the text link.
>
>Say i want to remove the default xml link.
>  
>
Export links is not exactly a good example because I think, for a while, 
that it should be grouped in one contract with argument since exports 
links generally have nearly the same layout...
Please take another to let us the time to conclude this point ;-)

Let's say that you don't want the search boxes :

    * Then you search for the contract named "search-input" - it should
      appear twice if you use pelt theme and you comment them - or
      simply remove them form your fv file.

And know - on the opposite - let's say you want to add a contract of 
your own that you have saved in 
$Project_HOME/src/documentation/resources/themes/pelt/html
Your contract is called yourContract.ft

    * Then you include your contract in your file (where you want it to
      be displayed possibly embbeded between hooks) :
    *         <forrest:contract name="youContract">
                  <forrest:property name="myArg">... </forrest:property>
              </forrest:contract>

Later, we will have a specific URL which will display the documented 
list of available contracts for your selected theme as well as your 
custom contracts.
So that it will be easier to find the contract you need (or the contract 
you want to remove !)

HTH

Cyriaque,


>Sorry for asking potentially silly questions.
>I am trying to see how to extend/modify an existing
>structurer without creating a maintenance problem.
>
>-David
>
>
>  
>

Re: Dispatcher quickstart

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

David Crossley wrote:
> The first installment is at
> http://forrest.apache.org/docs/dev/howto/howto-dispatcher-quickstart.html
> 
> I still need to add the excellent extra stuff
> about being careful where plugins are stored,
> but at least i have a link to the mail discussion.

Wow, a dispatcher doc for us mere mortals ;-)

Thanks David,
Ross

Re: Dispatcher quickstart

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

The first installment is at
http://forrest.apache.org/docs/dev/howto/howto-dispatcher-quickstart.html

I still need to add the excellent extra stuff
about being careful where plugins are stored,
but at least i have a link to the mail discussion.

-David 

Re: Dispatcher quickstart

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

Thanks a million to you both. That gives me plenty of
clues to solve the task and to write some docs.

-David

Re: Dispatcher quickstart

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

Ross Gardler wrote:
> David Crossley wrote:
> 
>> (After answers i will put this into the Howto Structurer.)

...

> 2) is the contract only useful in a particular theme?
> 
> if you answered yes place the contract in 
> THEMER_PLUGIN/resources/themes/THEME_NAME/OUTPUT_FORMAT
> 
> if you answered no place the contract in 
> THEMER_PLUGIN/resources/themes/common/OUTPUT_FORMAT

Since this is for a how-to:

Please provide a patch via our issue tracker so that we can include this 
new contract in future releases.

Ross

Re: Dispatcher quickstart

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

David Crossley wrote:
> (After answers i will put this into the Howto Structurer.)

The let me try and explain first - that way people get a chance to 
correct my misunderstandings too:

> 
> I wanted to quickly see how an existing site goes
> with the new Dispatcher.
> 
> 1) added structurer and themer plugins to forrest.properties
> 2) deployed structurer plugins with etc/structurer.sh
> 3) localhost:8888/index.html ... fantastic.
> 
> Now use another theme ...
> 
> 4) added project.theme=pelt to forrest.properties
> 5) re-start 'forrest run' ... fantastic.
> 
> Now i want to add a new what-do-i-call-it (contract?)
> For example, lets add the text link at the top right.

Yes, it is a contract.

> 
> Do i need to create a whole new structurer by
> copying say pelt.fv to src/documentation/content/xdocs/common.fv
> and insert a new contract for the text link.

Try this decision tree:

1) is this contract:
   a) of general use

   b) specific to a particular purpose

if you answered a) goto 2)
if you answered a) goto 3)

---

2) is the contract only useful in a particular theme?

if you answered yes place the contract in 
THEMER_PLUGIN/resources/themes/THEME_NAME/OUTPUT_FORMAT

if you answered no place the contract in 
THEMER_PLUGIN/resources/themes/common/OUTPUT_FORMAT

---

3) is the purpose of the contract
   a)  defined by an existing plugin or to this site only (e.g. a 
"employment history" contract is specific to the resume plugin)

   b)  defined by a specific site, e.g. a "process order" contract that 
integrates with an in-house order management system

if you answered a) place the contract in 
PLUGIN_NAME/resources/themes/THEME_NAME/OUTPUT_FORMAT (WARNING - at the 
time of writing this does not work, we need to update the plugin install 
scripts - I volunteered for this, help welcome)

if you answered b) think hard about this question. Most contracts can be 
generalised to be useful in more than one environment. If you are still 
sure that this is a site-specific contract then place it in 
PROJECT_HOME/src/documentation/resources/themes/common

> Say i want to remove the default xml link.

Normally we would...

You need to edit the *.fv file. In your steps above you have not altered 
the defaults which means you are using pelt.fv provided by the themer 
plugin. You don't want to edit it in place so copy the file 
THEMER_PLUGIN/resources/themes/pelt.fv into your project at 
PROJECT_HOME/src/documentation/resources/themes/pelt.fv.

Now you need to discover which contract is adding the xml link. You can 
do this by examining the pelt.fv file you just copied. If you are unsure 
you can look in the generated code to find the class name of the 
surrounding elements, then find the relevant forrest:hook in pelt.fv

But in this case ...

We have picked a contract which is not quite so easy to find. You know 
this because you can't see the class name you are looking for in pelt.fv

In this case we are using a "tile" to apply the various "export" links, 
pdf, xml etc. A tile is a collection of contracts for easy inclusion in 
a theme. So how do we find which tile is in use?

(this is a *guess* not tried it out - it's how I would first tackle this 
problem - no guarantees that it works)

Look for the classname you discovered earlier in the page that documents 
all contracts in this project (can't recall the URL just now but you can 
get to it via the forresttbar when you are "forrest run"-ning your site 
(devs -> ls.contracts). This will tell you the name of the contract, now 
  search the same document for the name of the contract, this should 
turn up the name of the tile(s) that include it.

Now you know the name of the relevant tile(s) you can return to your 
pelt.fv file and find which tile is importing the xml link contract. In 
this case you should end up at:

<jx:import uri="cocoon://prepare.tiles.export-link"/>

Now, you didn't want to remove all export links, just the XML one. If 
you remove the above jx:import line you will remove all export links 
contained in that tile. So you will need to replace any that you still 
want (i.e. the pdf link). See the list of contracts for details of how 
to include it.

> Sorry for asking potentially silly questions.
> I am trying to see how to extend/modify an existing
> structurer without creating a maintenance problem.

New blood looking at this is *very* important - you should know better 
than most that the silly questions are the most important (not that your 
questions are silly, but that you always reassure people that we want them).

Ross