Context Navigation

The Nagare component model

What is a component ?

A component has one or multiple rendering methods. They are used to generate
a HTML, XHTML, XML or any other views on it.

A component knows how to replace itself by an other component, either permanently
or temporary.

How to create a component ?

With a lots of components based frameworks, you need to make your classes inherit
from a Component class. Nagare is using composition instead of inheritance so
you only need to wrap your python object into a Component instance to obtain
a component. That's mean you can make a component from a "Plain Old Python
Object" without needed to change its code.

How to associate views to a component ?

The nagare.presentation presentation service of the framework keeps track
of the views associated to a class.

The views are plain Python methods and multiple views can be registered on a
class, each with a different model name.

The views are associated to a class using the
presentation.render_for decorator. Then when the presentation service is
asked to render a component, with a given model, the view for this model
is called with :

the object (the inner object of the component)

a renderer

the component

the model asked

and the method will generally returns a tree of DOM objects, build by using
the RendererObjects API.

The following code associates a default view (the view_by_default method) and
a view for the xml model (the xml_view method) to the class AClass:

In general, we append *args to the signature of the view methods for
compatibility with some future parameters addition. Furthermore if you're
not using, for example, the component and the model parameters into
your rendering process but only the self and h parameters, then you
could defined your view method as a simpler def render(self, h, *args)

The views for a class are defined and added externally to the class itself,
even from an other file if you want. So again, views can be added without any
modifications of the class.

Logic composition

After creating the view of the application from views of its inner components,
we will now create the logic of the application by combinating the logic of the
inner components.

First, the ColorChooser, on a click on a color, now returns the selected
color. For this purpose, we register a callback (see CallbacksAndForms)
on the link items, that calls the answer() method of the ColorChooser
component, with the value to return:

So now a little menu of two items is displayed. Clicking on the items display
the color_chooser or the text object. And, clicking on a color in the
color_chooser change again the color of the text object:

Temporary replacing a component

Permanently replacing a component is like a "goto" in some programming
languages. Temporary replacing a component is like a "call": the component
is replaced, but as soon as the replacing component calls its
answer(return_value) method, the previous component comes back in the
component graph and receives the returned value.

For example, our App component can be changed to first displays the
text_comp component and a link to choose its color. Once the link is
clicked, the App component temporary replaces itself by the color_chooser
object. Remenber that, once a color is selected, the color_chooser component
do an answer(color). So the App component is restored, receives the
selected color and change the color of the text: