http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc deleted file mode 100644 index 042b8b2..0000000 --- a/wicket-user-guide/src/docs/guide/jee/jee_1.gdoc +++ /dev/null @@ -1,51 +0,0 @@ - - -WicketStuff provides a module called wicketstuff-javaee-inject that contains component instantiation listener @JavaEEComponentInjector@. If we register this listener in our application we can use standard EJB annotations to inject dependencies into our Wicket components. - -To register a component instantiation listener in Wicket we must use @Application@'s method @getComponentInstantiationListeners@ which returns a typed collection of @IComponentInstantiationListeners@. - -The following initialization code is taken from project @EjbInjectionExample@: - -{code} -public class WicketApplication extends WebApplication -{ - //Constructor... - - @Override - public void init() - { - super.init(); - getComponentInstantiationListeners().add(new JavaEEComponentInjector(this)); - } -} -{code} - -In this example the object that we want to inject is a simple class containing a greeting message: - -{code} -@ManagedBean -public class EnterpriseMessage { - public String message = "Welcome to the EJB world!"; -} -{code} - -Please note that we have used annotation ManagedBean to decorate our object. Now to inject it into the home page we must add a field of type EnterpriseMessage and annotate it with annotation @EJB: - -{code} -public class HomePage extends WebPage { - - @EJB - private EnterpriseMessage enterpriseMessage; - //getter and setter for enterpriseMessage... - - public HomePage(final PageParameters parameters) { - super(parameters); - - add(new Label("message", enterpriseMessage.message)); - } -} -{code} - -That is all. We can point the browser to the home page of the project and see the greeting message injected into the page: - -!EjbInjectionExample.png! \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc deleted file mode 100644 index 5e006ca..0000000 --- a/wicket-user-guide/src/docs/guide/jee/jee_2.gdoc +++ /dev/null @@ -1,60 +0,0 @@ - - -If we need to inject dependencies with Spring we can use listener @org.apache.wicket.spring.injection.annot.SpringComponentInjector@ provided by module wicket-spring. - -For the sake of simplicity in the example project @SpringInjectionExample@ we have used Spring class @AnnotationConfigApplicationContext@ to avoid any XML file and create a Spring context directly from code: - -{code} -public class WicketApplication extends WebApplication -{ - //Constructor... - - @Override - public void init() - { - super.init(); - - AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext(); - //Scan package for annotated beans - ctx.scan("org.wicketTutorial.ejbBean"); - ctx.refresh(); - - getComponentInstantiationListeners().add(new SpringComponentInjector(this, ctx)); - } -} -{code} - -As we can see in the code above, the constructor of @SpringComponentInjector@ takes in input also an instance of Spring context. - -The injected object is the same used in the previous project @EjbInjectionExample@, it differs only for the greeting message: - -{code} -@ManagedBean -public class EnterpriseMessage { - public String message = "Welcome to the Spring world!"; -} -{code} - -In the home page of the project the object is injected using Wicket annotation @SpringBean: - -{code} -public class HomePage extends WebPage { - @SpringBean - private EnterpriseMessage enterpriseMessage; - //getter and setter for enterpriseMessage... - - public HomePage(final PageParameters parameters) { - super(parameters); - - add(new Label("message", enterpriseMessage.message)); - } -} -{code} - -By default @SpringBean@ searches into Spring context for a bean having the same type of the annotated field. If we want we can specify also the name of the bean to use as injected object and we can declare if the dependency is required or not. By default dependencies are required and if they can not be resolved to a compatible bean, Wicket will throw an @IllegalStateException@: - -{code} - //set the dependency as not required, i.e the field can be left null - @SpringBean(name="anotherName", required=false) - private EnterpriseMessage enterpriseMessage; -{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc deleted file mode 100644 index f190a98..0000000 --- a/wicket-user-guide/src/docs/guide/jee/jee_3.gdoc +++ /dev/null @@ -1,10 +0,0 @@ - - -Spring (and Guice) users can use standard "JSR-330":http://jcp.org/en/jsr/detail?id=330 annotations to wire their dependencies. This will make their code more interoperable with other containers that support this standard: - -{code} - //inject a bean specifying its name with JSR-330 annotations - @Inject - @Named("anotherName") - private EnterpriseMessage enterpriseMessage; -{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc b/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc deleted file mode 100644 index b7c9c45..0000000 --- a/wicket-user-guide/src/docs/guide/jee/jee_4.gdoc +++ /dev/null @@ -1,5 +0,0 @@ - - -In this chapter we have seen how to integrate Wicket applications with Spring and with an EJB container. Module wicket-examples contains also an example of integration with Guice (see application class @org.apache.wicket.examples.guice.GuiceApplication@). - - http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jsintegration.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration.gdoc b/wicket-user-guide/src/docs/guide/jsintegration.gdoc deleted file mode 100644 index e34ed0e..0000000 --- a/wicket-user-guide/src/docs/guide/jsintegration.gdoc +++ /dev/null @@ -1 +0,0 @@ -It's time to put into practice what we have learnt so far in this guide. To do this we will build a custom date component consisting of a text field to edit a date value and a fancy calendar icon to open a JavaScript datepicker. This chapter will also illustrate an example of integration of Wicket with a JavaScript library like "JQuery":http://jquery.com/ and its child project "JQuery UI":http://jqueryui.com/ . \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc deleted file mode 100644 index 936ea92..0000000 --- a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_1.gdoc +++ /dev/null @@ -1,23 +0,0 @@ - - -For end-users a datepicker is one of the most appreciated widget. It allows to simply edit a date value with the help of a user-friendly pop-up calendar. That's why nearly all UI frameworks provide a version of this widget. - -Popular JavaScript libraries like YUI and JQuery come with a ready-to-use datepicker to enrich the user experience of our web applications. Wicket already provides a component which integrates a text field with a calendar widget from YUI library, but there is no built-in component that uses a datepicker based on JQuery library. - -As both JQuery and its child project JQueryUI have gained a huge popularity in the last years, it's quite interesting to see how to integrate them in Wicket building a custom component. In this chapter we will create a custom datepicker based on the corresponding widget from JQueryUI project: - -!datepicker-screenshot.png! - -{warning} -On Internet you can find different libraries that already offer a strong integration between Wicket and JQuery. The goal of this chapter is to see how to integrate Wicket with a JavaScript framework building a simple homemade datepicker which is not intended to provide every feature of the original JavaScript widget. -{warning} - -h3. What features we want to implement - -Before starting to write code, we must clearly define what features we want to implement for our component. The new component should: - -* *Be self-contained*: we must be able to distribute it and use it in other projects without requiring any kind of additional configuration. -* *Have a customizable date format*: developer must be able to decide the date format used to display date value and to parse user input. -* *Be localizable*: the pop-up calendar must be localizable in order to support different languages. - -That's what we'd like to have with our custom datepicker. In the rest of the chapter we will see how to implement the features listed above and which resources must be packaged with our component. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc deleted file mode 100644 index 3b289e4..0000000 --- a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_2.gdoc +++ /dev/null @@ -1,137 +0,0 @@ - - -Our new component will extend the a built-in text field @org.apache.wicket.extensions.markup.html.form.DateTextField@ which already uses a java.util.Date as model object and already performs conversion and validation for input values. Since the component must be self-contained, we must ensure that the JavaScript libraries it relies on (JQuery and JQuery UI) will be always available. - -Starting from version 6.0 Wicket has adopted JQuery as backing JavaScript library so we can use the version bundled with Wicket for our custom datepicker. - -To make JQuery UI available we should instead go to its official site, download the required artifacts and use them as package resources of our component. - -h3. Component package resources - -JQuery UI needs the following static resources in order to work properly: - -* *jquery-ui.min.js*: the minified version of the library. -* *jquery-ui.css*: the CSS containing the style used by JQuery UI widgets. -* *jquery-ui-i18n.min.js*: the minified JavaScript containing the built-in support for localization. -* *Folder 'images'*: the folder containing picture files used by JQuery UI widgets. - -In the following picture we can see these package resources with our component class (named JQueryDateField): - -!datepicker-package-resources.png! - -Along with the four static resources listed above, we can find also file calendar.jpg, which is the calendar icon used to open the pop up calendar, and file JQDatePicker.js which contains the following custom JavaScript code that binds our component to a JQuery UI datepicker: - -{code:javascript} -function initJQDatepicker(inputId, countryIsoCode, dateFormat, calendarIcon) { - var localizedArray = $.datepicker.regional[countryIsoCode]; - localizedArray['buttonImage'] = calendarIcon; - localizedArray['dateFormat'] = dateFormat; - initCalendar(localizedArray); - $("#" + inputId).datepicker(localizedArray); -}; - -function initCalendar(localizedArray){ - localizedArray['changeMonth']= true; - localizedArray['changeYear']= true; - localizedArray['showOn'] = 'button'; - localizedArray['buttonImageOnly'] = true; -}; -{code} - -Function initJQDatepicker takes in input the following parameters: - -* *inputId*: the id of the HTML text field corresponding to our custom component instance. -* *countryIsoCode*: a two-letter low-case ISO language code. It can contain also the two-letter upper-case ISO country code separated with a minus sign (for example en-GB) -* *dateFormat*: the date format to use for parsing and displaying date values. -* *calendarIcon*: the relative URL of the icon used as calendar icon. - -As we will see in the next paragraphs, its up to our component to generate this parameters and invoke the initJQDatepicker function. - -Function initCalendar is a simple utility function that sets the initialization array for datepicker widget. For more details on JQuery UI datepicker usage see the documentation at http://jqueryui.com/ datepicker. - -h3. Initialization code - -The initialization code for our component is contained inside its method onInitialize and is the following: - -{code} -@Override -protected void onInitialize() { - super.onInitialize(); - setOutputMarkupId(true); - - datePattern = new ResourceModel("jqueryDateField.shortDatePattern", "mm/dd/yy") - .getObject(); - countryIsoCode = new ResourceModel("jqueryDateField.countryIsoCode", "en-GB") - .getObject(); - - PackageResourceReference resourceReference = - new PackageResourceReference(getClass(), "calendar.jpg"); - - urlForIcon = urlFor(resourceReference, new PageParameters()); - dateConverter = new PatternDateConverter(datePattern, false); -} - -@Override -public <Date> IConverter<Date> getConverter(Class<Date> type) { - return (IConverter<Date>) dateConverter; -} -{code} - -The first thing to do inside onInitialize is to ensure that our component will have a markup id for its related text field. This is done invoking setOutputMarkupId(true). - -Next, JQueryDateField tries to retrieve the date format and the ISO language code that must be used as initialization parameters. This is done using class @ResourceModel@ which searches for a given resource in the available bundles. If no value is found for date format or for ISO language code, default values will be used ('mm/dd/yy' and 'en-GB'). - -To generate the relative URL for calendar icon, we load it as package resource reference and then we use @Component@'s method urlFor to get the URL value (we have seen this method in [paragraph 9.3.2|guide:requestProcessing_3]). - -The last configuration instruction executed inside onInitialize is the instantiation of the custom converter used by our component. This converter is an instance of the built-in class @org.apache.wicket.datetime.PatternDateConvert@ and must use the previously retrieved date format to perform conversion operations. Now to tell our component to use this converter we must return it overriding @FormComponent@'s method @getConverter@. - -h3. Header contributor code - -The rest of the code of our custom component is inside method @renderHeader@, which is responsible for adding to page header the bundled JQuery library, the three files from JQuery UI distribution, the custom file JQDatePicker.js and the invocation of function @initJQDatepicker@: - -{code} -@Override -public void renderHead(IHeaderResponse response) { - super.renderHead(response); - - //if component is disabled we don't have to load the JQueryUI datepicker - if(!isEnabledInHierarchy()) - return; - //add bundled JQuery - JavaScriptLibrarySettings javaScriptSettings = - getApplication().getJavaScriptLibrarySettings(); - response.render(JavaScriptHeaderItem. - forReference(javaScriptSettings.getJQueryReference())); - //add package resources - response.render(JavaScriptHeaderItem. - forReference(new PackageResourceReference(getClass(), "jquery-ui.min.js"))); - response.render(JavaScriptHeaderItem. - forReference(new PackageResourceReference(getClass(), "jquery-ui-i18n.min.js"))); - response.render(CssHeaderItem. - forReference(new PackageResourceReference(getClass(), "jquery-ui.css"))); - //add custom file JQDatePicker.js. Reference JQDatePickerRef is a static field - response.render(JavaScriptHeaderItem.forReference(JQDatePickerRef)); - - //add the init script for datepicker - String jqueryDateFormat = datePattern.replace("yyyy", "yy").toLowerCase(); - String initScript = ";initJQDatepicker('" + getMarkupId() + "', '" + countryIsoCode + - "', '" + jqueryDateFormat + "', " + "'" + urlForIcon +"');"; - response.render(OnLoadHeaderItem.forScript(initScript)); -} -{code} - -If component is disabled the calendar icon must be hidden and no datepicker must be displayed. That's why @renderHeader@ is skipped if component is not enabled. - -To get a reference to the bundled JQuery library we used the JavaScript setting class @JavaScriptLibrarySettings@ and its method @getJQueryReference@. - -In the last part of @renderHeader@ we build the string to invoke function @initJQDatepicker@ using the values obtained inside onInitialize. Unfortunately the date format used by JQuery UI is different from the one adopted in Java so we have to convert it before building the JavaScript code. This init script is rendered into header section using a @OnLoadHeaderItem@ to ensure that it will be executed after all the other scripts have been loaded. - -{note} -If we add more than one instance of our custom component to a single page, static resources are rendered to the header section just once. Wicket automatically checks if a static resource is already referenced by a page and if so, it will not render it again. - -This does not apply to the init script which is dynamically generated and is rendered for every instance of the component. -{note} - -{warning} -Our datepicker is not ready yet to be used with AJAX. In [chapter 19|guide:ajax] we will see how to modify it to make it AJAX-compatible. -{warning} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc b/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc deleted file mode 100644 index f1ba1d3..0000000 --- a/wicket-user-guide/src/docs/guide/jsintegration/jsintegration_3.gdoc +++ /dev/null @@ -1,6 +0,0 @@ - - -In this brief chapter we have seen how custom components can be integrated with [DHTML|http://en.wikipedia.org/wiki/Dynamic_HTML] technologies. To do so we have used most of what we have learnt in this guide. Now we are able to build complex components with a rich user experience. However this is not enough yet to develop "Web 2.0":http://en.wikipedia.org/wiki/Web_2.0 applications. We still have to cover a fundamental technology like AJAX and some other Wicket-related topics that will help us building our application in more modular and efficient way. - - - http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl.gdoc b/wicket-user-guide/src/docs/guide/keepControl.gdoc deleted file mode 100644 index 657341e..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl.gdoc +++ /dev/null @@ -1,3 +0,0 @@ -Many Wicket newbies are initially scared by its approach to web development because they have the impression that the component-oriented nature of the framework prevents them from having direct control over the generated markup. This is due to the fact that many developers come from other server-side technologies like JSP where we physically implement the logic that controls how the final HTML is generated. - -This chapter will prevent you from having any initial misleading feeling about Wicket showing you how to control and manipulate the generated HTML with the built-in tools shipped with the framework. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc deleted file mode 100644 index cbf7bf8..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_1.gdoc +++ /dev/null @@ -1,7 +0,0 @@ -At the end of the previous chapter we have seen how to hide a component calling its method @setVisible@. In a similar fashion, we can also decide to disable a component using method @setEnabled@. When a component is disabled all the links inside it will be in turn disabled (they will be rendered as @<span>@) and it can not fire JavaScript events. - -Class @Component@ provides two getter methods to determinate if a component is visible or enabled: @isVisible@ and @isEnabled@. - -Even if nothing prevents us from overriding these two methods to implement a custom logic to determinate the state of a component, we should keep in mind that methods @isVisible@ and @isEnabled@ are called multiple times before a component is fully rendered. Hence, if we place non-trivial code inside these two methods, we can sensibly deteriorate the responsiveness of our pages. - -As we will see in the next chapter, class @Component@ provides method @onConfigure@ which is more suited to contain code that contributes to determinate component states because it is called just once during rendering phase. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc deleted file mode 100644 index 525f11c..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_10.gdoc +++ /dev/null @@ -1,92 +0,0 @@ -Component @org.apache.wicket.markup.html.border.Border@ is a special purpose container created to enclose its tag body with its related markup. Just like panels and pages, borders also have their own markup file which is defined following the same rules seen for panels and pages. In this file @<wicket:border>@ tag is used to indicate which part of the content is to be considered as border markup: - -{code:html} -<?xml version="1.0" encoding="UTF-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wicket="http://wicket.apache.org"> -<head></head> -<body> - <!-- everything above <wicket:border> tag will be discarded...--> - <wicket:border> - <div> - foo<br /> - <wicket:body/><br /> - buz <br /> - - </div> - </wicket:border> - <!-- everything below </wicket:border> tag will be discarded...--> -</body> -</html> -{code} - -The @<wicket:body/>@ tag used in the example above is used to indicate where the body of the tag will be placed inside border markup. Now if we attached this border to the following tag - -{code:html} -<span wicket:id="myBorder"> - bar -</span> -{code} - -we would obtain the following resulting HTML: - -{code:html} -<span wicket:id="myBorder"> - <div> - foo<br /> - bar<br /> - buz <br /> - </div> -</span> -{code} - -@Border@ can also contain children components which can be placed either inside its markup file or inside its corresponding HTML tag. In the first case children must be added to the border component with method @addToBorder(Component...)@, while in the second case we must use the @add(Component...)@ method. - -The following example illustrates both use cases: - -Border class: - -{code} -public class MyBorder extends Border { - - public MyBorder(String id) { - super(id); - } - -} -{code} - -Border Markup: - -{code:html} -<?xml version="1.0" encoding="UTF-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wicket="http://wicket.apache.org"> -<head></head> -<body> - <wicket:border> - <div> - <div wicket:id="childMarkup"></div> - <wicket:body/><br /> - </div> - </wicket:border> -</body> -</html> -{code} - -Border tag: - -{code:html} -<div wicket:id="myBorder"> - <span wicket:id="childTag"></span> -</div> -{code} - -Initialization code for border: - -{code} -MyBorder myBorder = new MyBorder("myBorder"); - -myBorder.addToBorder(new Label("childMarkup", "Child inside markup.")); -myBorder.add(new Label("childTag", "Child inside tag.")); - -add(myBorder); -{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc deleted file mode 100644 index 9e118ed..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_11.gdoc +++ /dev/null @@ -1,6 +0,0 @@ - - -In this chapter we have seen the tools provided by Wicket to gain complete control over the generated HTML. However we didn't see yet how we can repeat a portion of HTML with Wicket. With classic server-side technologies like PHP or JSP we use loops (like @while@ or @for@) inside our pages to achieve this result. -To perform this task Wicket provides a special-purpose family of components called repeaters and designed to repeat their markup body to display a set of items. - -But to fully understand how these components work, we must first learn more of Wicket's basics. That's why repeaters will be introduced later in [chapter 13|guide:repeaters]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc deleted file mode 100644 index c231cf0..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_2.gdoc +++ /dev/null @@ -1,32 +0,0 @@ -To modify tag attributes we can use class @org.apache.wicket.AttributeModifier@. This class extends @org.apache.wicket.behavior.Behavior@ and can be added to any component via the @Component@'s @add@ method. Class @Behavior@ is used to expand component functionalities and it can also modify component markup. We will see this class in detail later in [chapter 19.1|guide:advanced_1]. - -As first example of attribute manipulation let's consider a @Label@ component bound to the following markup: - -{code:html} -<span wicket:id="simpleLabel"></span> -{code} - -Suppose we want to add some style to label content making it red and bolded. We can add to the label an @AttributeModifier@ which creates the tag attribute @style@ with value @"color:red;font-weight:bold"@: - -{code} -label.add(new AttributeModifier("style", "color:red;font-weight:bold")); -{code} - -If attribute @style@ already exists in the original markup, it will be replaced with the value specified by @AttributeModifier@. If we don't want to overwrite the existing value of an attribute we can use subclass @AttributeAppender@ which will append its value to the existing one: - -{code} -label.add(new AttributeAppender("style", "color:red;font-weight:bold")); -{code} - -We can also create attribute modifiers using factory methods provided by class @AttributeModifier@ and it's also possible to prepend a given value to an existing attribute: - -{code} -//replaces existing value with the given one -label.add(AttributeModifier.replace("style", "color:red;font-weight:bold")); - -//appends the given value to the existing one -label.add(AttributeModifier.append("style", "color:red;font-weight:bold")); - -//prepends the given value to the existing one -label.add(AttributeModifier.prepend("style", "color:red;font-weight:bold")); -{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc deleted file mode 100644 index b83542a..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_3.gdoc +++ /dev/null @@ -1,14 +0,0 @@ -Tag attribute @id@ plays a crucial role in web development as it allows JavaScript to identify a DOM element. That's why class @Component@ provides two dedicated methods to set this attribute. With method @setOutputMarkupId(boolean output)@ we can decide if the @id@ attribute will be rendered or not in the final markup (by default is not rendered). The value of this attribute will be automatically generated by Wicket and it will be unique for the entire page. -If we need to specify this value by hand, we can use method @setMarkupId(String id)@. The value of the id can be retrieved with method @getMarkupId()@. - -Wicket generates markup ids using an instance of interface @org.apache.wicket.IMarkupIdGenerator@. The default implementation is @org.apache.wicket.DefaultMarkupIdGenerator@ and it uses a session-scoped counter to generate the final id. A different generator can be set with the markup settings class @org.apache.wicket.settings.MarkupSettings@ available in the application class: - -{code} -@Override -public void init() -{ - super.init(); - //wrap disabled links with <b> tag - getMarkupSettings().setMarkupIdGenerator(myGenerator); -} -{code} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc deleted file mode 100644 index 1e0965d..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_4.gdoc +++ /dev/null @@ -1,26 +0,0 @@ -Create custom panels is a great way to handle complex user interfaces. However, sometimes we may need to create a panel which is used only by a specific page and only for a specific task. - -In situations like these component @org.apache.wicket.markup.html.WebMarkupContainer@ is better suited than custom panels because it can be directly attached to a tag in the parent markup without needing a corresponding html file (hence it is less reusable). Let's consider for example the main page of a mail service where users can see a list of received mails. Suppose that this page shows a notification box where user can see if new messages have arrived. This box must be hidden if there are no messages to display and it would be nice if we could handle it as if it was a Wicket component. - -Suppose also that this information box is a @<div>@ tag like this inside the page: - -{code:html} -<div wicket:id="informationBox"> - //here's the body - You've got <span wicket:id="messagesNumber"></span> new messages. -</div> -{code} - -Under those conditions we can consider using a @WebMarkupContainer@ component rather than implementing a new panel. The code needed to handle the information box inside the page could be the following: - -{code} -//Page initialization code -WebMarkupContainer informationBox = new WebMarkupContainer ("informationBox"); -informationBox.add(new Label("messagesNumber", messagesNumber)); -add(informationBox); - -//If there are no new messages, hide informationBox -informationBox.setVisible(false); -{code} - -As you can see in the snippet above we can handle our information box from Java code as we do with any other Wicket component. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc deleted file mode 100644 index 8c99f31..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_5.gdoc +++ /dev/null @@ -1,58 +0,0 @@ -Another circumstance in which we may prefer to avoid the creation of custom panels is when we want to conditionally display in a page small fragments of markup. In this case if we decided to use panels, we would end up having a huge number of small panel classes with their related markup file. - -To better cope with situations like this, Wicket defines component @Fragment@ in package @org.apache.wicket.markup.html.panel@. Just like its parent component @WebMarkupContainer@, Fragment doesn't have its own markup file but it uses a markup fragment defined in the markup file of its parent container, which can be a page or a panel. The fragment must be delimited with tag @<wicket:fragment>@ and must be identified by a @wicket:id@ attribute. In addition to the component id, @Fragment@'s constructor takes as input also the id of the fragment and a reference to its container. - -In the following example we have defined a fragment in a page and we used it as content area: - -*Page markup:* - -{code:html} -<html> - ... -<body> -... - <div wicket:id="contentArea"></div> - <wicket:fragment wicket:id="fragmentId"> - <!-- Fragment markup goes here --> - </wicket:fragment> -</body> -</html> -{code} - -*Java code:* - -{code} -Fragment fragment = new Fragment ("contentArea", "fragmentId", this); -add(fragment); -{code} - -Fragments can be very helpful with complex pages or components. For example let's say that we have a page where users can register to our forum. This page should first display a form where user must insert his/her personal data (name, username, password, email and so on), then, once the user has submitted the form, the page should display a message like âYour registration is complete! Please check your mail to activate your user profile.â. - -Instead of displaying this message with a new component or in a new page, we can define two fragments: one for the initial form and one to display the confirmation message. The second fragment will replace the first one after the form has been submitted: - -*Page markup:* - -{code:html} -<html> -<body> - <div wicket:id="contentArea"></div> - <wicket:fragment wicket:id="formFrag"> - <!-- Form markup goes here --> - </wicket:fragment> - <wicket:fragment wicket:id="messageFrag"> - <!-- Message markup goes here --> - </wicket:fragment> -</body> -</html> -{code} - -*Java code:* - -{code} -Fragment fragment = new Fragment ("contentArea", "formFrag", this); -add(fragment); - -//form has been submitted -Fragment fragment = new Fragment ("contentArea", "messageFrag", this); -replace(fragment); -{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc deleted file mode 100644 index 0aa20a7..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_6.gdoc +++ /dev/null @@ -1,38 +0,0 @@ -Panel's markup can also contain HTML tags which must go inside header section of the final page, like tags @<script>@ or @<style>@. To tell Wicket to put these tags inside page @<head>@, we must surround them with the @<wicket:head>@ tag. - -Considering the markup of a generic panel, we can use @<wicket:head>@ tag in this way: - -{code:html} -<wicket:head> - <script type="text/javascript"> - function myPanelFunction(){ - } - </script> - - <style> - .myPanelClass{ - font-weight: bold; - color: red; - } - </style> -</wicket:head> -<body> - <wicket:panel> - - </wicket:panel> -</body> -{code} - -Wicket will take care of placing the content of @<wicket:head>@ inside the @<head>@ tag of the final page. - -{note} -The @<wicket:head>@ tag can also be used with children pages/panels which extend parent markup using tag @<wicket:extend>@. -{note} - -{note} -The content of the @<wicket:head>@ tag is added to the header section once per component class. In other words, if we add multiple instances of the same panel to a page, the @<head>@ tag will be populated just once with the content of @<wicket:head>@. -{note} - -{warning} -The @<wicket:head>@ tag is ideal if we want to define small in-line blocks of CSS or JavaScript. However Wicket provides also a more sophisticated technique to let components contribute to header section with in-line blocks and resource files like CSS or JavaScript files. We will see this technique later in [chapter 16|guide:resources]. -{warning} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc deleted file mode 100644 index ac6d177..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_7.gdoc +++ /dev/null @@ -1,14 +0,0 @@ -Wicket's @<wicket:remove>@ tag can be very useful when our web designer needs to show us how a page or a panel should look like. The markup inside this tag will be stripped out in the final page, so it's the ideal place for web designers to put their stub markup: - -{code:html} -<html> -<head> - -</head> -<body> - <wicket:remove> - <!-- Stub markup goes here --> - </wicket:remove> -</body> -</html> -{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc deleted file mode 100644 index 2d1f78d..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_8.gdoc +++ /dev/null @@ -1,39 +0,0 @@ -When we bind a component to its corresponding tag we can choose to get rid of this outer tag in the final markup. If we call method @setRenderBodyOnly(true)@ on a component Wicket will remove the surrounding tag. - -For example given the following markup and code: - -*HTML markup:* - -{code:html} -<html> -<head> - <title>Hello world page</title> -</head> -<body> -<div wicket:id="helloWorld">[helloWorld]</div> -</body> -</html> -{code} - -*Java code:* - -{code} -Label label = new Label("helloWorld", âHello World!â); -label.setRenderBodyOnly(true); -add(label); -{code} - -the output will be: - -{code:html} -<html> -<head> - <title>Hello world page</title> -</head> -<body> - Hello World! -</body> -</html> -{code} - -As you can see the @<div>@ tag used for component @Label@ is not present in the final markup. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc b/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc deleted file mode 100644 index 7b1aa7a..0000000 --- a/wicket-user-guide/src/docs/guide/keepControl/keepControl_9.gdoc +++ /dev/null @@ -1,33 +0,0 @@ -Our data are rarely displayed alone without a caption or other graphic elements that make clear the meaning of their value. For example: - -{code:html} -<label>Total amount: </label><span wicket:id="totalAmount"></span> -{code} - -Wicket comes with a nice utility tag called @<wicket:enclosure>@ that automatically hides those decorating elements if the related data value is not visible. All we have to do is to put the involved markup inside this tag. Applying @<wicket:enclosure>@ to the previous example we get the following markup: - -{code:html} -<wicket:enclosure> - <label>Total amount: </label><span wicket:id="totalAmount"></span> -</wicket:enclosure> -{code} - -Now if component @totalAmount@ is not visible, its description (@Total amount:@) will be automatically hidden. If we have more than a Wicket component inside @<wicket:enclosure>@ we can use @child@ attribute to specify which component will control the overall visibility: - -{code:html} -<wicket:enclosure child="totalAmount"> - <label>Total amount: </label><span wicket:id="totalAmount"></span><br/> - <label>Expected delivery date: </label><span wicket:id="delivDate"></span> -</wicket:enclosure> -{code} - -@child@ attribute supports also nested components with a colon-separated path: - -{code:html} -<wicket:enclosure child="totalAmountContainer:totalAmount"> - <div wicket:id="totalAmountContainer"> - <label>Total amount: </label><span wicket:id="totalAmount"></span> - </div> - <label>Expected delivery date: </label><span wicket:id="delivDate"></span> -</wicket:enclosure> -{code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/layout.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout.gdoc b/wicket-user-guide/src/docs/guide/layout.gdoc deleted file mode 100644 index de0034a..0000000 --- a/wicket-user-guide/src/docs/guide/layout.gdoc +++ /dev/null @@ -1 +0,0 @@ -Before going ahead with more advanced topics, we will see how to maintain a consistent layout across our site using Wicket and its component-oriented features. Probably this is not the most interesting use we can get out of Wicket, but it is surely the simplest one so it's the best way to get our hands dirty with some code. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc deleted file mode 100644 index 1630a61..0000000 --- a/wicket-user-guide/src/docs/guide/layout/layout_1.gdoc +++ /dev/null @@ -1,28 +0,0 @@ -There was a time in the 90s when Internet was just a buzzword and watching a plain HTML page being rendered by a browser was a new and amazing experience. In those days we used to organize our page layout using the @<frame>@ HTML tag. Over the years this tag has almost disappeared from our code and it survives only in few specific domains. For example is still being used by JavaDoc. - -With the adoption of server side technologies like JSP, ASP or PHP the tag @<frame>@ has been replaced by a template-based approach where we divide our page layout into some common areas that will be present in each page of our web application. Then, we manually insert these areas in every page including the appropriate markup fragments. - -In this chapter we will see how to use Wicket to build a site layout. The sample layout we will use is a typical page layout consisting of the following areas: - -* *a header* which could contain site title, some logos, a navigation bar, etc... -* *a left* menu with a bunch of links to different areas/functionalities of the site. -* *a footer* with generic informations like web master's email, the company address, etc... -* *a content* area which usually contains the functional part of the page. - -The following picture summarises the layout structure: - -!layout.png! - -Once we have chosen a page layout, our web designer can start building up the site theme. The result is a beautiful mock of our future web pages. Over this mock we can map the original layout areas: - -!layout-mock.png! - -Now in order to have a consistent layout across all the site, we must ensure that each page will include the layout areas seen above. With an old template-based approach we must manually put them inside every page. If we were using JSP we would probably end up using @include@ directive to add layout areas in our pages. We would have one @include@ for each of the areas (except for the content): - -!layout-include.png! - -{note} -For the sake of simplicity we can consider each included area as a static HTML fragment. -{note} - -Now let's see how we can handle the layout of our web application using Wicket. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc deleted file mode 100644 index f4e839d..0000000 --- a/wicket-user-guide/src/docs/guide/layout/layout_2.gdoc +++ /dev/null @@ -1,64 +0,0 @@ -The need of ensuring a consistent layout across our pages unveiled a serious limit of the HTML: the inability to apply inheritance to web pages and their markup. Wouldn't be great if we could write our layout once in a page and then inherit it in the other pages of our application? -One of the goals of Wicket is to overcome this kind of limit. - -h3. Markup inheritance - -As we have seen in the previous chapter, Wicket pages are pure Java classes, so we can easily write a page which is a subclass of another parent page. But in Wicket inheritance is not limited to the classic object-oriented code inheritance. When a class subclasses a @WebPage@ it also inherits the HTML file of the parent class. This type of inheritance is called markup inheritance. -To better illustrate this concept let's consider the following example where we have a page class called @GenericSitePage@ with the corresponding HTML file GenericSitePage.html. Now let's create a specific page called @OrderCheckOutPage@ where users can check out their orders on our web site. This class extends @GenericSitePage@ but we don't provide it with any corresponding HTML file. -In this scenario @OrderCheckOutPage@ will use GenericSitePage.html as markup file: - -!markup-inheritance.png! - -Markup inheritance comes in handy for page layout management as it helps us avoid the burden of checking that each page conforms to the site layout. However to fully take advantage of markup inheritance we must first learn how to use another important component of the framework that supports this feature: the panel. - -{warning} -If no markup is found (nor directly assigned to the class, neither inherited from an ancestor) a @MarkupNotFoundException@ is thrown. -{warning} - -h3. Panel class - -Class @org.apache.wicket.markup.html.panel.Panel@ is a special component which lets us reuse GUI code and HTML markup across different pages and different web applications. It shares a common ancestor class with WebPage class, which is @org.apache.wicket.MarkupContainer@: - -!page-panel-hierarchy.png! - -_Illustration: Hierarchy of WebPage and Panel classes_ - -Subclasses of @MarkupContainer@ can contain children components that can be added with method @add(Component...)@ (seen in [chapter 3.3|guide:whyLearn_3]). @MarkupContainer@ implements a full set of methods to manage children components. The basic operations we can do on them are: - -* add one or more children components (with method @add@). -* remove a specific child component (with method @remove@). -* retrieve a specific child component with method @get(String)@. The string parameter is the id of the component or its relative path if the component is nested inside other @MarkupContainer@s. This path is a colon-separated string containing also the ids of the intermediate containers traversed to get to the child component. To illustrate an example of component path, let's consider the code of the following page: - -{code} -MyPanel myPanel = new MyPanel ("innerContainer"); -add(myPanel); -{code} - -Component @MyPanel@ is a custom panel containing only a label having @"name"@ as id. Under those conditions we could retrieve this label from the container page using the following path expression: - -{code} -Label name = (Label)get("innerContainer:name"); -{code} - -* replace a specific child component with a new component having the same id (with method @replace@). -* iterate thought children components with the iterator returned by method @iterator@ or using visitor pattern1 with methods @visitChildren@. - -Both @Panel@ and @WebPage@ have their own associated markup file which is used to render the corresponding component. If such file is not provided, Wicket will apply markup inheritance looking for a markup file through their ancestor classes. When a panel is attached to a container, the content of its markup file is inserted into its related tag. - -While panels and pages have much in common, there are some notable differences between these two components that we should keep in mind. The main difference between them is that pages can be rendered as standalone entities while panels must be placed inside a page to be rendered. Another important difference is the content of their markup file: for both @WebPage@ and @Panel@ this is a standard HTML file, but @Panel@ uses a special tag to indicate which part of the whole file will be considered as markup source. This tag is @<wicket:panel>@. A markup file for a panel will typically look like this: - -{code:html} -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -... -</head> -<body> - <wicket:panel> - <!-- Your markup goes here --> - </wicket:panel> -</body> -</html> -{code} - -The HTML outside tag @<wicket:panel>@ will be removed during rendering phase. The space outside this tag can be used by both web developers and web designers to place some mock HTML to show how the final panel should look like. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/layout/layout_3.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_3.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_3.gdoc deleted file mode 100644 index 4ebdb7f..0000000 --- a/wicket-user-guide/src/docs/guide/layout/layout_3.gdoc +++ /dev/null @@ -1,162 +0,0 @@ -Let's go back to our layout example. In [chapter 5.1|guide:layout_1] we have divided our layout in common areas that must be part of every page. Now we will build a reusable template page for our web application combining pages and panels. The code examples are from project MarkupInheritanceExample. - -h3. Panels and layout areas - -First, let's build a custom panel for each layout area (except for 'content' area). For example given the header area - -!header-area.png! - -we can build a panel called @HeaderPanel@ with a related markup file called HeaderPanel.html containing the HTML for this area: - -{code:html} -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -... -</head> -<body> - <wicket:panel> - <table width="100%" style="border: 0px none;"> - <tbody> - <tr> - <td> - <img alt="Jug4Tenda" src="wicketLayout_files/logo_jug4tenda.gif"> - </td> - <td> - <h1>Gestione Anagrafica</h1> - </td> - </tr> - </tbody> - </table> - </wicket:panel> -</body> -<html> -{code} - -The class for this panel simply extends base class @Panel@: - -{code} -package helloWorld.layoutTenda; - -import org.apache.wicket.markup.html.panel.Panel; - -public class HeaderPanel extends Panel { - - public HeaderPanel(String id) { - super(id); - } -} -{code} - -For each layout area we will build a panel like the one above that holds the appropriate HTML markup. In the end we will have the following set of panels: - -* HeaderPanel -* FooterPanel -* MenuPanel - -Content area will change from page to page, so we don't need a reusable panel for it. - -h3. Template page - -Now we can build a generic template page using our brand new panels. Its markup is quite straightforward : - -{code:html} -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -... -<!--Include CSS--> -... -</head> -<body> -<div id="header" wicket:id="headerPanel">header</div> -<div id="body"> - <div id="menu" wicket:id="menuPanel">menu</div> - <div id="content" wicket:id="contentComponent">content</div> -</div> -<div id="footer" wicket:id="footerPanel">footer</div> -</body> -</html> -{code} - -The HTML code for this page implements the generic left-menu layout of our site. You can note the 4 @<div>@ tags used as containers for the corresponding areas. -The page class contains the code to physically assemble the page and panels: - -{code} -package helloWorld.layoutTenda; - -import org.apache.wicket.markup.html.WebPage; -import org.apache.wicket.Component; -import org.apache.wicket.markup.html.basic.Label; - -public class JugTemplate extends WebPage { - public static final String CONTENT_ID = "contentComponent"; - - private Component headerPanel; - private Component menuPanel; - private Component footerPanel; - - public JugTemplate(){ - add(headerPanel = new HeaderPanel("headerPanel")); - add(menuPanel = new MenuPanel("menuPanel")); - add(footerPanel = new FooterPanel("footerPanel")); - add(new Label(CONTENT_ID, "Put your content here")); - } - - //getters for layout areas - //... -} -{code} - -Done! Our template page is ready to be used. Now all the pages of our site will be subclasses of this parent page and they will inherit the layout and the HTML markup. They will only substitute the @Label@ inserted as content area with their custom content. - -h3. Final example - -As final example we will build the login page for our site. We will call it @SimpleLoginPage@. First, we need a panel containing the login form. This will be the content area of our page. We will call it @LoginPanel@ and the markup is the following: - -{code:html} -<html> -<head> -</head> -<body> - <wicket:panel> - <div style="margin: auto; width: 40%;"> - <form id="loginForm" method="get"> - <fieldset id="login" class="center"> - <legend >Login</legend> - <span >Username: </span><input type="text" id="username"/><br/> - <span >Password: </span><input type="password" id="password" /> - <p> - <input type="submit" name="login" value="login"/> - </p> - </fieldset> - </form> - </div> - </wicket:panel> -</body> -</html> -{code} - -The class for this panel just extends @Panel@ class so we won't see the relative code. The form of this panel is for illustrative purpose only. We will see how to work with Wicket forms in chapters [11|guide:modelsforms] and [12|guide:forms2]. Since this is a login page we don't want it to display the left menu area. That's not a big deal as @Component@ class exposes a method called @setVisible@ which sets whether the component and its children should be displayed. - -The resulting Java code for the login page is the following: - -{code} -package helloWorld.layoutTenda; -import helloWorld.LoginPanel; -import org.apache.wicket.event.Broadcast; -import org.apache.wicket.event.IEventSink; - -public class SimpleLoginPage extends JugTemplate { - public SimpleLoginPage(){ - super(); - replace(new LoginPanel(CONTENT_ID)); - getMenuPanel().setVisible(false); - } -} -{code} - -Obviously this page doesn't come with a related markup file. You can see the final page in the following picture: - -!final-login-page.png! - http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/layout/layout_4.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_4.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_4.gdoc deleted file mode 100644 index 068bf86..0000000 --- a/wicket-user-guide/src/docs/guide/layout/layout_4.gdoc +++ /dev/null @@ -1,94 +0,0 @@ -With Wicket we can apply markup inheritance using another approach based on the tag @<wicket:child>@. This tag is used inside the parent's markup to define where the children pages/panels can âinjectâ their custom markup extending the markup inherited from the parent component. -An example of a parent page using the tag @<wicket:child>@ is the following: - -{code:html} -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -</head> -<body> - This is parent body! - <wicket:child/> -</body> -</html> -{code} - -The markup of a child page/panel must be placed inside the tag @<wicket:extend>@. Only the markup inside @<wicket:extend>@ will be included in final markup. Here is an example of child page markup: - -{code} -<html> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -</head> -<body> - <wicket:extend> - This is child body! - </wicket:extend> -</body> -</html> -{code} - -Considering the two pages seen above, the final markup generated for child page will be the following: - -{code:html} -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -</head> -<body> - This is parent body! - <wicket:child> - <wicket:extend> - This is child body! - </wicket:extend> - </wicket:child> -</body> -</html> -{code} - -h3. Our example revisited - -Applying @<wicket:child>@ tag to our layout example, we obtain the following markup for the main template page: - -{code:html} -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -</head> -<body> -<div id="header" wicket:id="headerPanel">header</div> -<div id="body"> - <div id="menu" wicket:id="menuPanel">menu</div> - <wicket:child/> -</div> -<div id="footer" wicket:id="footerPanel">footer</div> -</body> -</html> -{code} - -We have replaced the @<div>@ tag of the content area with the tag @<wicket:child>@. Going forward with our example we can build a login page creating class @SimpleLoginPage@ which extends the @JugTemplate@ page, but with a related markup file like this: - -{code:html} -<html> -<head> -</head> -<body> - <wicket:extend> - <div style="margin: auto; width: 40%;"> - <form id="loginForm" method="get"> - <fieldset id="login" class="center"> - <legend >Login</legend> - <span >Username: </span><input type="text" id="username"/><br/> - <span >Password: </span><input type="password" id="password" /> - <p> - <input type="submit" name="login" value="login"/> - </p> - </fieldset> - </form> - </div> - </wicket:extend> -</body> -</html> -{code} - -As we can see this approach doesn't require to create custom panels to use as content area and it can be useful if we don't have to handle a GUI with a high degree of complexity. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/layout/layout_5.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/layout/layout_5.gdoc b/wicket-user-guide/src/docs/guide/layout/layout_5.gdoc deleted file mode 100644 index 6eb8a54..0000000 --- a/wicket-user-guide/src/docs/guide/layout/layout_5.gdoc +++ /dev/null @@ -1,2 +0,0 @@ - -Wicket applies inheritance also to HTML markup making layout management much easier and less error-prone. Defining a master template page to use as base class for the other pages is a great way to build a consistent layout and use it across all the pages on the web site. During the chapter we have also introduced the @Panel@ component, a very important Wicket class that is primarily designed to let us divide our pages in smaller and reusable UI components. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/maven.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/maven.gdoc b/wicket-user-guide/src/docs/guide/maven.gdoc deleted file mode 100644 index 8b13789..0000000 --- a/wicket-user-guide/src/docs/guide/maven.gdoc +++ /dev/null @@ -1 +0,0 @@ - http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/maven/maven_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/maven/maven_1.gdoc b/wicket-user-guide/src/docs/guide/maven/maven_1.gdoc deleted file mode 100644 index a20d570..0000000 --- a/wicket-user-guide/src/docs/guide/maven/maven_1.gdoc +++ /dev/null @@ -1,52 +0,0 @@ - - -As pointed out in the note in [paragraph 4.2|guide:helloWorld_2], Wicket can be started in two modes, DEVELOPMENT and DEPLOYMENT. When we are in DEVELOPMENT mode Wicket warns us at application startup with the following message: - -{code} -******************************************************************** -*** WARNING: Wicket is running in DEVELOPMENT mode. *** -*** ^^^^^^^^^^^ *** -*** Do NOT deploy to your live server(s) without changing this. *** -*** See Application#getConfigurationType() for more information. *** -******************************************************************** -{code} - -As we can read Wicket itself discourages us from using DEVELOPMENT mode into production environment. The running mode of our application can be configured in four different ways. The first one is adding a filter parameter inside deployment descriptor web.xml: - -{code:html} -<filter> - <filter-name>wicket.MyApp</filter-name> - <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class> - <init-param> - <param-name>applicationClassName</param-name> - <param-value>org.wicketTutorial.WicketApplication</param-value> - </init-param> - <init-param> - <param-name>configuration</param-name> - <param-value>deployment</param-value> - </init-param> -</filter> -{code} - -The additional parameter is written in bold. The same parameter can be also expressed as context parameter: - -{code:html} -<context-param> - <param-name>configuration</param-name> - <param-value>deployment</param-value> -</context-param> -{code} - -The third way to set the running mode is using system property wicket.configuration. This parameter can be specified in the command line that starts up the server: - -{code} -java -Dwicket.configuration=deployment ... -{code} - -The last option is to set it in your Java code (e.g. in the init-method of your WebApplication): - -{code} -setConfigurationType(RuntimeConfigurationType.DEPLOYMENT); -{code} - -Remember that system properties overwrite other settings, so they are ideal to ensure that on production machine the running mode will be always set to DEPLOYMENT. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/maven/maven_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/maven/maven_2.gdoc b/wicket-user-guide/src/docs/guide/maven/maven_2.gdoc deleted file mode 100644 index 04b5f62..0000000 --- a/wicket-user-guide/src/docs/guide/maven/maven_2.gdoc +++ /dev/null @@ -1,129 +0,0 @@ - - -{note} -In order to follow the instructions of this paragraph you must have Maven installed on your system. The installation of Maven is out of the scope of this guide but you can easily find an extensive documentation about it on Internet. -Another requirement is a good Internet connection (a flat ADSL is enough) because Maven needs to connect to its central repository to download the required dependencies. -{note} - - -h3. From Maven to our IDE - -Wicket project and its dependencies are managed using Maven. This tool is very useful also when we want to create a new project based on Wicket from scratch. With a couple of shell commands we can generate a new project properly configured and ready to be imported into our favourite IDE. -The main step to create such a project is to run the command which generates project's structure and its artifacts. If we are not familiar with Maven or we simply don't want to type this command by hand, we can use the utility form on Wicket site at "http://wicket.apache.org/start/quickstart.html":http://wicket.apache.org/start/quickstart.html : - -!quickstart-webpage.png! - -Here we have to specify the root package of our project (GroupId), the project name (ArtifactId) and which version of Wicket we want to use (Version). -Once we have run the resulting command in the OS shell, we will have a new folder with the same name of the project (i.e the ArtifactId). Inside this folder we can find a file called pom.xml. This is the main file used by Maven to manage our project. For example, using âorg.wicketTutorialâ as GroupId and âMyProjectâ as ArtifactId, we would obtain the following artifacts: - -{code} - .\MyProject - | pom.xml - | - \---src - +---main - | +---java - | | \---org - | | \---wicketTutorial - | | HomePage.html - | | HomePage.java - | | WicketApplication.java - | | - | +---resources - | | log4j.properties - | | - | \---webapp - | \---WEB-INF - | web.xml - | - \---test - \---java - \---org - \---wicketTutorial - TestHomePage.java - -{code} - -Amongst other things, file pom.xml contains a section delimited by tag <dependencies> which declares the dependencies of our project. By default the Maven archetype will add the following Wicket modules as dependencies: - -{code:xml} -... -<dependencies> - <!-- WICKET DEPENDENCIES --> - <dependency> - <groupId>org.apache.wicket</groupId> - <artifactId>wicket-core</artifactId> - <version>${wicket.version}</version> - </dependency> - <dependency> - <groupId>org.apache.wicket</groupId> - <artifactId>wicket-ioc</artifactId> - <version>${wicket.version}</version> - </dependency> - <!-- OPTIONAL DEPENDENCY - <dependency> - <groupId>org.apache.wicket</groupId> - <artifactId>wicket-extensions</artifactId> - <version>${wicket.version}</version> - </dependency> - --> - ... -</dependencies> -... -{code} - -If we need to use more Wicket modules or additional libraries, we can add the appropriate XML fragments here. - -h3. Importing a Maven project into our IDE - -Maven projects can be easily imported into the most popular Java IDEs. However, the procedure needed to do this differs from IDE to IDE. In this paragraph we can find the instructions to import Maven projects into three of the most popular IDEs among Java developers : NetBeans, JetBrains IDEA and Eclipse. - -*NetBeans* -Starting from version 6.7, NetBeans includes Maven support, hence we can start it and directly open the folder containing our project: - -!netbeans-maven-import.png! - -*Intellj IDEA* -Intellj IDEA comes with a Maven importing functionality that can be started under âFile/New Project/Import from external model/Mavenâ. Then, we just have to select the pom.xml file of our project: - -!intellj-maven-import.png! - -*Eclipse* -If our IDE is Eclipse the import procedure is a little more complex. Before opening the new project we must generate the Eclipse project artifacts running the following command from project root: - -{code} -mvn eclipse:eclipse -{code} - - Now to import our project into Eclipse we must create a classpath variable called M2_REPO that must point to your local Maven repository. This can be done selecting âWindow/Preferencesâ and searching for âClasspath Variablesâ. The folder containing our local Maven repository is usually under our user folder and is called .m2 (for example under Unix system is /home/<myUserName>/.m2/repository): - -!eclipse-classpath-variables.png! - -Once we have created the classpath variable we can go to âFile/Import.../Existing Project into Workspaceâ, select the directory of the project and press âFinishâ: - -!eclipse-maven-import.png! - -Once the project has been imported into Eclipse, we are free to use our favourite plug-ins to run it or debug it (like for example "run-jetty-run": http://code.google.com/p/run-jetty-run/ ). - -{note} -Please note the option âCopy projects into workspaceâ in the previous illustration. If we select it, the original project generated with Maven won't be affected by the changes made inside Eclipse because we will work on a copy of it under the current workspace. -{note} - -{note} -If we modify the pom.xml file (for example adding further dependencies) we must regenerate project's artifacts and refresh the project (F5 key) to reflect changes into Eclipse. -{note} - -h3. Speeding up development with plugins. - -Now that we have our project loaded into our IDE we could start coding our components directly by hand. However it would be a shame to not leverage the free and good Wicket plugins available for our IDE. The following is a brief overview of the most widely used plugins for each of the three main IDEs considered so far. - -*NetBeans* -NetBeans offers Wicket support through 'NetBeans Plugin for Wicket' hosted at "http://plugins.netbeans.org/plugin/3586/wicket-1-4-support":http://plugins.netbeans.org/plugin/3586/wicket-1-4-support . This plugin is released under CDDL-1.0 license. -You can find a nice introduction guide to this plugin at "http://netbeans.org/kb/docs/web/quickstart-webapps-wicket.html":http://netbeans.org/kb/docs/web/quickstart-webapps-wicket.html . - -*Intellj IDEA* -For JetBrain IDEA we can use WicketForge plugin, hosted at Google Code "http://code.google.com/p/wicketforge/":http://code.google.com/p/wicketforge/ . The plugin is released under ASF 2.0 license. - -*Eclipse* -With Eclipse we can install one of the plugins that supports Wicket. As of the writing of this document, the most popular is probably Qwickie, available in the Eclipse Marketplace and hosted on Google Code at "http://code.google.com/p/qwickie/":http://code.google.com/p/qwickie/ . -QWickie is released under ASF 2.0 license. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/modelsforms.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/modelsforms.gdoc b/wicket-user-guide/src/docs/guide/modelsforms.gdoc deleted file mode 100644 index 392dca4..0000000 --- a/wicket-user-guide/src/docs/guide/modelsforms.gdoc +++ /dev/null @@ -1 +0,0 @@ -In Wicket the concept of âmodelâ is probably the most important topic of the entire framework and it is strictly related to the usage of its components. In addition, models are also an important element for internationalization, as we will see in paragraph 12.6. However, despite their fundamental role, in Wicket models are not difficult to understand but the best way to learn how they work is to use them with forms. That's why we haven't talked about models so far, and why this chapter discusses these two topics together. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_1.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_1.gdoc b/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_1.gdoc deleted file mode 100644 index 95d1c3e..0000000 --- a/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_1.gdoc +++ /dev/null @@ -1,53 +0,0 @@ - - -Model is essentially a "facade":http://en.wikipedia.org/wiki/Facade_pattern interface which allows components to access and modify their data without knowing any detail about how they are managed or persisted. Every component has at most one related model, while a model can be shared among different components. In Wicket a model is any implementation of the interface @org.apache.wicket.model.IModel@: - -!uml-imodel.png! - -The main goal of @IModel@ interface is to decouple components from concrete details about the persistence strategy adopted for their data. In order to achieve this level of abstraction IModel defines the two methods required to get and set a data object: @getObject()@ and @setObject()@. The level of indirection introduced by models allows access data object only when it is really needed (for example during the rendering phase) and not earlier when it may not be ready to be used. In addition to @getObject()@ and @setObject()@, @IModel@ defines a richer set of methods, mostly meant to work with Java 8 lambdas. We will introduce them in the next paragraph. - -Any component can get/set its model as well as its data object using the 4 public shortcut methods listed in the class diagram above. The two methods @onModelChanged()@ and @onModelChanging()@ are triggered by Wicket each time a model is modified: the first one is called after the model has been changed, the second one just before the change occurs. In the examples seen so far we have worked with Label component using its constructor which takes as input two string parameters, the component id and the text to display: - -{code} -add(new Label("helloMessage", "Hello WicketWorld!")); -{code} - -This constructor internally builds a model which wraps the second string parameter. That's why we didn't mention label model in the previous examples. Here is the code of this constructor: - -{code} -public Label(final String id, String label) { - this(id, new Model<String>(label)); -} -{code} - -Class @org.apache.wicket.model.Model@ is a basic implementation of @IModel@. It can wrap any object that implements the interface java.io.Serializable. The reason of this constraint over data object is that this model is stored in the web session, and we know from chapter 6 that data are stored into session using serialization. - -{note} -In general, Wicket models support a detaching capability that allows us to work also with non-serializable objects as data model. We will see the detaching mechanism later in this chapter. -{note} - -Just like any other Wicket components, Label provides a constructor that takes as input the component id and the model to use with the component. Using this constructor the previous example becomes: - -{code} -add(new Label("helloMessage", new Model<String>("Hello WicketWorld!"))); -{code} - -{note} -The Model class comes with a bunch of factory methods that makes it easier to build new model instances. For example the @of(T object)@ method creates a new instance of Model which wraps any Object instance inside it. So instead of writing - - new Model<String>("Hello WicketWorld!") - -we can write - - Model.of("Hello WicketWorld!") - -If the data object is a @List@, a @Map@ or a @Set@ we can use similar methods called @ofList@, @ofMap@ and @ofSet@. -From now on we will use these factory methods in our examples. -{note} - -It's quite clear that if our Label must display a static text it doesn't make much sense to build a model by hand like we did in the last code example. -However is not unusual to have a Label that must display a dynamic value, like the input provided by a user or a value read from a database. Wicket models are designed to solve these kinds of problems. - -{note} -By default the class Component escapes HTML sensitive characters (like '<', '>' or '&') from the textual representation of its model object. The term 'escape' means that these characters will be replaced with their corresponding HTML "entity":http://en.wikipedia.org/wiki/Character_entity_reference (for example '<' becomes '< '). This is done for security reasons as a malicious user could attempt to inject markup or JavaScript into our pages. If we want to display the raw content stored inside a model, we can tell the Component class not to escape characters by calling the setEscapeModelStrings(false) method. -{note} http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_10.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_10.gdoc b/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_10.gdoc deleted file mode 100644 index 95f3d97..0000000 --- a/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_10.gdoc +++ /dev/null @@ -1,4 +0,0 @@ - - -Models are at the core of Wicket and they are the basic ingredient needed to taste the real power of the framework. In this chapter we have seen how to use models to bring data to our components without littering their code with technical details about their persistence strategy. -We have also introduced Wicket forms as complementary topic. With forms and models we are able to bring our applications to life allowing them to interact with users. But what we have seen in this chapter about Wicket forms is just the tip of the iceberg. That's why the next chapter is entirely dedicated to them. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_2.gdoc b/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_2.gdoc deleted file mode 100644 index 9f1584c..0000000 --- a/wicket-user-guide/src/docs/guide/modelsforms/modelsforms_2.gdoc +++ /dev/null @@ -1,70 +0,0 @@ -With Wicket 8 @IModel@ has been extended with new methods to fully leverage lambdas. The most interesting thing of the new version of @IModel@ is that it provides a default implementation for all of its methods (included @setObject()@), with the only exception of @getObject()@. -In this way @IModel@ is eligible as functional interface and this greatly simplify the creation of custom models. As long as we need to display a static text it doesn't make much sense building a custom model, but if we need to display a dynamic value (like the input provided by a user or a value read from a database), defining a model with a lambda expression comes quite in handy. - -Let's say we need a label to display the current time stamp each time a page is rendered. This could be a possible solution: - -{code} -add(new Label("timeStamp", () -> java.time.LocalDate.now())); -{code} - -As mentioned above, method @setObject()@ comes with a default implementation. The code is the following: - -{code:java} -default void setObject(final T object) -{ - throw new UnsupportedOperationException( - "Override this method to support setObject(Object)"); -} -{code} - -This means that models obtained using @IModel@ as lambda expressions are _read-only_. When we work with forms we need to use a model that support also data storing. In the next paragraph we will see a couple of models shipped with Wicket that allow us to easily use JavaBeans as backing objects. - -h3. Lambda Goodies - -Most of the default methods we find in @IModel@ are meant to leverage Lambda expressions to transform model object. The following is a short reference for such methods: - -* *filter(predicate)*: Returns a @IModel@ checking whether the predicate holds for the contained object, if it is not null. If the predicate doesn't evaluate to true, the contained object will be null. Example: - {divcontainer:li-nested-content} - {code:java} -//the filtered model will have a null model object if person's name -//is not "Jane" -IModel<Person> janeModel = Model.of(person) - .filter((p) -> p.getName().equals("Jane")); - {code} - {divcontainer} -* *map(mapperFunction)*: Returns a @IModel@ applying the given mapper to the contained object, if it is not null. Example: - {divcontainer:li-nested-content} - {code:java} -//the new read-only model will contain the person's first name -IModel<String> personNameModel = Model.of(person).map(Person::getName); - {code} - {divcontainer} -* *flatMap(mapperFunction)*: Returns a @IModel@ applying the given @IModel@-bearing mapper to the contained object, if it is not null. Example: - {divcontainer:li-nested-content} - {code:java} -//returns a read/write model for person's first name -//NOTE: LambdaModel will be discussed later. -IModel<String> personNameModel = Model.of(person).flatMap(targetPerson -> -LambdaModel.of( - () -> targetPerson::getName, targetPerson::setName -)); - {code} - {divcontainer} - * *flatMap(otherModel, combiner)*: Returns a @IModel@ applying the given combining function to the current model object and to the one from the other model, if they are not null. Example: - {divcontainer:li-nested-content} - {code:java} -IModel<String> hello = Model.of("hello"); -IModel<String> world = Model.of("world"); -IModel<String> combinedModel = hello.combineWith( - world, (thisObj, otherObj) -> thisObj + " " + otherObj); - -assertEquals("hello world", combinedModel.getObject()); - {code} - {divcontainer} - * *orElseGet(supplier)*: Returns a read-only @IModel@ using either the contained object or invoking the given supplier to get a default value. Example: - {divcontainer:li-nested-content} - {code:java} -IModel<String> nullObj = new Model(); -assertEquals("hello!", nullObj.orElseGet(() -> "hello!"); - {code} - {divcontainer}