How do you create a component in Tapestry 5?

开发者_运维知识库I have been using Tapestry's built-in components, but now I'd like to try making my own. Assuming this is possible, how is it done and is it generally expected that developers are going to be creating their own components in addition to what comes out of the box?

---

Yes it is expected that developers will create their own components and it is pretty easy to do. There are quite a few projects out there where people are creating their libraries of components. If you want to see some examples take a look at:

• http://chenillekit.org/demo/
• http://code.google.com/p/corner/
• http://code.google.com/p/myt5lib/
• http://tapestry.formos.com/nightly/tapx/tapx-datefield/
• http://code.google.com/p/tapestry5-treegrid/

Components are much like pages. They usually have a .tml file and a .java file. The .java file goes in a src directory called components (src/main/java/com/examples/app/components) and the .tml file goes in the same place, but under resources (src/main/resources/com/examples/app/components)

Here is an example of a component that renders as a Facebook share link that links to the EventInfo page and takes an Event object in order to construct the URL to share on Facebook.

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;

import javax.persistence.Transient;

import net.xeric.register.entities.Event;

import org.apache.tapestry5.Link;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.Property;
import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.services.PageRenderLinkSource;

public class ShareEventOnFacebook {

    @Inject
    private PageRenderLinkSource linkSource;

    @Parameter(required=true)
    @Property
    private Event event;


    public String getFacebookShareURL() {
        Link link = linkSource.createPageRenderLinkWithContext("EventInfo", event);
        String linkURL = "";
        try {
            linkURL =  URLEncoder.encode(link.toAbsoluteURI(),"UTF-8");
        } catch (UnsupportedEncodingException e) {

            e.printStackTrace();
        }
        return linkURL;
    }

    public String getFacebookShareTitle() {
        String returnValue = "";
        try {
            returnValue = URLEncoder.encode(event.getDescription(), "UTF-8");
        } catch (Exception e) {
            e.printStackTrace();
        }
        return returnValue;       
    }

}

Pay particular attention to how the Event property is annotated to mark it as a required Parameter. This makes it a parameter of your component so you can call it from a template saying <t:shareeventonfacebook event="myEvent"/>

And the corresponding template file:

<t:container 
    xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">


    <a href="http://www.facebook.com/sharer.php?u=${facebookShareURL}">
        Share on Facebook
    </a><br/>

</t:container>

You want to use the component in your page template you use:

<t:shareeventonfacebook event="event"/>

---

It is not only possible, but simple and well-documented. Take a look at the relevant bits in the Tapestry documentation: Component classes, component templates, component events and component parameters. Effectively, pages are only top-level components, so you should feel right at home.

You can also take a look at the built-in components to see how they are implemented.

---

If you've been creating pages and using existing components, then you've already been creating components (pages are specialized components). The main difference is:

• Components go in a different package
• Components often do not have a template (they render in code)
• Components can have Parameters

Please check the Tapestry web site for all the remaining details.