How to Run a Sample¶

Various z2-based sample system configurations have been prepared as Git repositories.

Assuming you know the repository URL these three steps (with or without Eclipse) are all there is to do:

Eclipse users¶

Most likely you also want to look at code or configuration files of an example. That is why we recommend to start from within the Eclipse IDE. If you prefer the command line or another IDE, please proceed to

From the Command Line¶

hello_world

Sample macro.

macro_list

Displays a list of all available macros, including description if available.

child_pages

Displays a list of child pages. With no argument, it displays the child pages of the current wiki page. Examples:

{{child_pages}} -- can be used from a wiki page only
{{child_pages(depth=2)}} -- display 2 levels nesting only
{{child_pages(Foo)}} -- lists all children of page Foo
{{child_pages(Foo, parent=1)}} -- same as above with a link to page Foo

include

Includes a wiki page. Examples:

{{include(Foo)}}
{{include(projectname:Foo)}} -- to include a page of a specific project wiki

collapse

Inserts of collapsed block of text. Examples:

{{collapse
This is a block of text that is collapsed by default.
It can be expanded by clicking a link.
}}

{{collapse(View details...)
With custom link text.
}}

thumbnail

Displays a clickable thumbnail of an attached image.
Default size is 200 pixels. Examples:

{{thumbnail(image.png)}}
{{thumbnail(image.png, size=300, title=Thumbnail)}} -- with custom title and size

issue

Displays an issue link including additional information. Examples:

{{issue(123)}}                              -- Issue #123: Enhance macro capabilities
{{issue(123, project=true)}}                -- Andromeda - Issue #123: Enhance macro capabilities
{{issue(123, tracker=false)}}               -- #123: Enhance macro capabilities
{{issue(123, subject=false, project=true)}} -- Andromeda - Issue #123

drawio

Draw.io widget plugin to embed diagrams. Example usage:

{{drawio(diagram_attachment.xml[, ...options...])}}

Use http://draw.io to draw diagrams, save them locally and attach to wiki or issue pages.
On page view, the diagrams are sent to draw.io site for rendering.

options:
lightbox=false  : enable lightbox usage
resize=false    : enable zoom control toolbar
zoom=100        : initial zoom of diagram (percentage of original diagram)
fit=true        : fit page width (only if resize=false)
hilight=#0000ff : color to hilight hyperlinks

drawio_attach

Macro for embedding www.draw.io diagrams stored as attachments. Example usage:

{{drawio_attach(myDiagram[, ...options...])}}

The diagram is draw from the attachment myDiagram.png; if you want to use the
SVG image format, specify thw '.svg' document extension. If the attachment doesn't exists
a default diagram wil be drawn. Double click it to start editing.

Every time a diagram is saved, a new attachment will be created; for now you must 
manually delete old attachments (missing Redmine API; version 3.3.0 seems to have included
an API to delete attachments but need investigation).

options:
size=number : forced width of the diagram image, in pixels

0. Pre-Requisites¶

All you need is Java Runtime Environment (JRE) of at least version 6. Preferrably, as that is easier to understand a sample, have the Eclipse IDE installed.
Other pre-requisites, for example some database setup may be required based on the specific example, i.e. stuff that cannot be covered here.

1. Prepare a z2-base Installation¶

Create a folder to hold the installation. We will assume that folder is called sample

In sample execute

git clone -b master http://git.z2-environment.net/z2-base.core

Go into sample/z2-base.core/run/bin and run

./gui.sh

or

gui.bat

depending on your operating system. A simple graphical console should open up that displays the console log output of the z2 <home> and worker processes - as explained in http://www.z2-environment.eu/check_it_out.

At the first start, the environment will download required resources, which may take a few minutes - depending on your network bandwidth. Subsequent starts will be faster.
Eventually the server should be up and you can go to the basic admin view at http://localhost:8080/adm (use z* with password z) to verify everything is cool.

Stop the environment again by either pressing Ctrl+C on the console where you started the GUI or by clicking the Exit button on the GUI.

2. Clone the specific sample repository¶

Given the sample repository is called z2-samples.sampleX, go into sample once more and run

git clone -b master http://git.z2-environment.net/z2-samples.sampleX

Now start the environment as described above. The environment will now run with the sample configuration and all required dependencies.

In other words: That's it.

Why does that actually work¶

If you care, here is how everything falls into place:

The z2-base.core repository contains a z2 core installation that is bound to a remote "system repository" at http://git.z2-environment.net/z2-base.base. As it is by now best practice with z2, that repository contains an environment module that describes system specific settings such as other repositories.

By cloning the sample repository you put an override of environment module into view of the dev repository. That is, the local server will take your local definitions with preference over the remote definitions. These may include other remote component repositories such as z2-addons.spring.

In addition the sample repository contains all the modules holding code and other resources that implement the actual sample.

If you already understand how the dev repository works, you will not be surprised to find files called LOCAL in the module folders of cloned repository's workspace.

References¶

• Dev Repository: http://www.z2-environment.eu/v20doc#Workspace%20Development%20Using%20the%20Dev%20Repository