How to create your own addon from an js lib

This is a step by step guide for create your own addon from an js. For our example we will implement an addon for the js library iscroll.js.

First we create a maven project with the name wicket-iscroll with the parent project wicket-js-addons:

<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<parent>
		<groupId>de.alpharogroup</groupId>
		<artifactId>wicket-js-addons</artifactId>
		<version>7.3.0</version>
		<relativePath></relativePath>
	</parent>

	<artifactId>wicket-iscroll</artifactId>

	<licenses>
		<license>
			<name>MIT license</name>
			<url>
				http://www.opensource.org/licenses/mit-license.php
			</url>
		</license>
	</licenses>

	<dependencies>
		<dependency>
			<groupId>de.alpharogroup</groupId>
			<artifactId>wicket-js-addons-core</artifactId>
		</dependency>
	</dependencies>

</project>

This extend all needed dependencies that you need for wicket and others.

As next step you have to create the JavaScriptResourceReference class for import the js and css files that are needed for iscroll.

package de.alpharogroup.wicket.js.addon.iscroll;

import org.apache.wicket.request.resource.JavaScriptResourceReference;

/**
 * The Class {@link IscrollResourceReference} holds the references(js) for the js library iscroll.
 */
public class IscrollResourceReference extends JavaScriptResourceReference
{

	/** The Constant serialVersionUID. */
	private static final long serialVersionUID = 1L;

	/**
	 * Instantiates a new {@link IscrollResourceReference}.
	 */
	private IscrollResourceReference()
	{
		super(IscrollResourceReference.class, "iscroll.js");
	}

	/** The Constant INSTANCE. */
	private static final IscrollResourceReference INSTANCE = new IscrollResourceReference();

	/**
	 * Gets the singleton instance for this resource reference.
	 *
	 * @return the {@link IscrollResourceReference} instance
	 */
	public static IscrollResourceReference get()
	{
		return INSTANCE;
	}


}

In the same directory you have to put the iscroll.js. Iscroll have more modules. If you want to include the other modules of Iscroll you can include them by overwrite the method getDependencies.

The next step is to create the Settings class for the options of the Iscroll.

package de.alpharogroup.wicket.js.addon.iscroll;

import java.util.HashSet;
import java.util.Set;

import de.alpharogroup.wicket.js.addon.core.Settings;
import de.alpharogroup.wicket.js.addon.core.StringTextType;
import de.alpharogroup.wicket.js.addon.core.StringTextValue;
import lombok.AccessLevel;
import lombok.Builder;
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.ToString;


/**
 * This class encapsulates various settings for the iscroll js library. See the documentation for the
 * iscroll js library for further information.
 */
@Getter
@EqualsAndHashCode
@ToString
@NoArgsConstructor(access = AccessLevel.PRIVATE)
@Builder
public class IscrollSettings implements Settings
{

	/**
	 * The serialVersionUID
	 */
	private static final long serialVersionUID = 1L;

	/**
	 * Listen to the mouse wheel event. Default: false
	 */
	private final StringTextValue<Boolean> mouseWheel = new StringTextValue<>("mouseWheel",
		StringTextType.BOOLEAN);

	/**
	 * {@inheritDoc}
	 */
	@Override
	public Set<StringTextValue<?>> asSet()
	{
		final Set<StringTextValue<?>> allSettings = new HashSet<>();
		allSettings.add(getMouseWheel());
		return allSettings;
	}

}

For simplicity we set only one option, the mouseWheel. To achieve all the options we have to implement them in the settings class. For further information see the documentation of the options for the iscroll js library.

The next step is to implement the JsGenerator class.

package de.alpharogroup.wicket.js.addon.iscroll;

import java.util.Map;

import org.apache.wicket.util.lang.Args;

import de.alpharogroup.wicket.js.addon.core.JavascriptGenerator;

public class IscrollJsGenerator extends JavascriptGenerator<IscrollSettings>
{

	/**
	 * The serialVersionUID
	 */
	private static final long serialVersionUID = 1L;

	/**
	 * Instantiates a new {@link IscrollJsGenerator}.
	 *
	 * @param settings
	 *            the settings for the Iscroll library.
	 * @param componentId
	 *            the component id
	 */
	public IscrollJsGenerator(final IscrollSettings settings, final String componentId)
	{
		super(settings);
		setMethodName("IScroll");
		setComponentId(Args.notNull(componentId, "componentId"));
		setWithComponentId(true);
	}

	/**
	 * Generates the javascript template code from the given map and the given method name that will
	 * be used to interpolate with the values of the given map.
	 *
	 * @param variables
	 *            the map with the javascript options.
	 * @param methodName
	 *            The method name.
	 * @return The generated javascript from the given map and the given method name.
	 */
	@Override
	public String generateJavascriptTemplateContent(final Map<String, Object> variables,
		final String methodName)
	{
		final StringBuilder sb = new StringBuilder();
		sb.append("new");
		sb.append(" ");
		sb.append(methodName);
		sb.append("(");
		sb.append("'#");
		sb.append(getComponentId());
		sb.append("', ");
		if (0 < variables.size())
		{
			generateJsOptionsForTemplateContent(variables, sb);
		}
		sb.append(");");
		return sb.toString();
	}

}

We create a unit test for see what is the result of the JsGenerator:

package de.alpharogroup.wicket.js.addon.iscroll;

import org.junit.Test;

public class IscrollJsGeneratorTest
{

	@Test
	public void testIscrollJsGenerator()
	{
		final IscrollSettings iscrollSettings = IscrollSettings.builder().build();
		iscrollSettings.getMouseWheel().setValue(Boolean.TRUE);
		final IscrollJsGenerator iscrollJsGenerator = new IscrollJsGenerator(iscrollSettings,
			"foo-component-id");
		final String result = iscrollJsGenerator.generateJs();

		System.out.println(result);
	}

}

The output should see like this:

new IScroll('#foo-component-id', {
mouseWheel: true
});

The generated js can now be added to a Behavior. This is explained in the wiki page How to use existing addons