aboutsummaryrefslogtreecommitdiffstats
path: root/documentation/articles/ComponentAddonProjectSetupHOWTO.asciidoc
blob: e8d063e27c76e6a695ab17b4a1a49048e1dd876f (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffff
---
title: Component Addon Project Setup HOWTO
order: 77
layout: page
---

[[component-add-on-project-setup-howto]]
Component add-on project setup how-to
------------------------------------

This how-to walks you through a complete setup for a project for
developing, building and publishing your own Vaadin UI component
add-ons. The goal here is not to teach how to write an add-on, but to
make the process of setting up your project environment as smooth as
possible. I hope this encourages you to try building and publishing your
own add-ons :)

[[goals-for-the-project-environment]]
Goals for the project environment
---------------------------------

* Fully automated build with Maven
* Allow anyone to re-build your project easily regardless of the IDE:s
* Almost instant save-build-deploy-try cycle
* Simple, but complete, project setup
* Project publishing to GitHub
* Easy publishing of the results to Vaadin Directory

[[install-toolchain]]
Install toolchain
-----------------

If you do not already have the following tools in use, install them:

* Eclipse IDE for Java EE developers from http://www.eclipse.org (Indigo
Service Release 1 was used in this how-to)
* Google Chrome browser from https://www.google.com/chrome/ (other
browsers will do, but Chrome is recommended)
* Eclipse plugins: m4e-wtp, vaadin, egit (optional) and jrebel
(optional) from Marketplace (just select Help->Marketplace... from the
menu)

[[create-a-new-widget-project]]
Create a new widget project
---------------------------

Start project creation wizard: File -> New -> Other... -> "Maven
Project"

Give a proper name for your project and save it under workspace. For
this example I am building a list widget and name it MyList.

Ensure that your Maven archetype catalogs contain
http://repo1.maven.org/maven2/archetype-catalog.xml as remote catalog
and select it.

Select vaadin-archetype-widget from the list.

Give a proper name for the project. I use "org.vaadin" as group id as it
can be used by anyone who wants to contribute non-commercial widgets to
Vaadin project and name of the widget as artifact id in this case i use
"mylist" as example. For a package name use "org.vaadin.mylist".

Observe that pom.xml shows two errors. This is because m2e does not
directly support gwt and vaadin -plugins. To fix the problem, choose the
problems one by one and choose "ignore" quick fix. Then edit the pom.xml
by changing all `<ignore></ignore>` tags to `<execute></execute>` to get the
plugins to execute. Finally, clear the remaining "project configuration
needs update" error with quickfix (that not surprisingly updates project
configuration). In the end, pom.xml should look like
https://raw.github.com/jojule/MyList/56ac906f9cc6442e0817eb0cc945eee023ff9001/pom.xml[this].

Refactor the name of the component you are building.

* Instead of using `MyComponent` and `VMyComponent`, use your own name. In
this example I use `MyList` and `VMyList`.
* Also change the theme directory name from
`src/main/java/org/vaadin/mylist/gwt/public/mywidget` to
`src/main/java/org/vaadin/mylist/gwt/public/mylist`
* and update the reference in `MyWidgetSet.gwt.xml`.
* Also rename `MyWidgetSet.gwt.xml` to `MyListWidgetSet.gwt.xml`
* and update references in `pom.xml` and `web.xml`.

Test that the project compiles and runs by running (Run -> Run as ... ->
Maven Build...) maven goal "package jetty:run". If everything compiles
fine and Jetty server starts, you can access the application at
http://localhost:8080/mylist/. You should see "It works!" on the web
page. Do not worry that the build takes a lot of time, we'll get back to
it in a minute.

Finally, if you prefer to use Git, create a repository for the project.
You could simply choose "Share Project..." from the Project's Team menu.
Choose "Use or create repository in parent folder" and click "Create
Repository". Then, add project resources to commit. Choose pom.xml and
src directory from Navigator view and select Team -> Add to Index. Then
add the rest of the files (.settings, .project, .classpath and target)
to .gitignore with Team -> Ignore. Finally, just do Team -> Commit.

At this point - or later whenever you are ready for it - you can
publish the project to GitHub. Just go to github.com and create a new
repository. Use MyList as the name for the repository. Then follow the
instructions on the screen. In my case, I executed the following command
line commands: `cd /Users/phoenix/Documents/workspace/mylist; git remote
add origin git@github.com:jojule/MyList.git; git push -u origin master`.
You can see the results
https://github.com/jojule/MyList/tree/56ac906f9cc6442e0817eb0cc945eee023ff9001[at
GitHub].

[[save---build---deploy---try]]
Save - Build - Deploy - Try
---------------------------

If it takes minutes each time from code change to seeing that change on
the screen, you are not going to get your component ready anytime soon.
To solve the issue, we use two tools: 1) Google GWT Developer Mode and
2) JRebel. The first one is more important here as the GWT compilation
step is the really slow step, but JRebel also helps as it gives you
instant redeploy for the server-side changes.

To enable JRebel, open project popup menu and choose JRebel -> Generate
rebel.xml in `src/main/java`. Then click "Enable JRebel" on the JRebel tab
for Maven run configuration for "jetty:run". Now when you make any
changes to server-side code - for example to `WidgetTestApplication.java`
- hit save and reload the browser pointing to
http://localhost:8080/mylist/?restartApplication, the changes are
applied immediately. Even better - you can start the project with Debug
As and add break points to the application.

Client-side changes are more tricky as they are compiled from Java to
JavaScript by GWT. To make those changes immediately you, must be
running a GWT Development Mode. This is done by running Maven goal gwt:run
instead of just pointing your web browser to the running application.
Note that must be running both jetty:run and gwt:run concurrently.
gwt:run starts application called "GWT Development Mode". From there you
can launch your browser - or cut-n-paste URL to Chrome - if that is not
your default browser. When the application is started, add
`&restartApplication` parameter to the end of the URL to ensure that the
server-side of the application is reloaded each time you reload the
page. In this case, the full url is
http://127.0.0.1:8080/mylist/?gwt.codesvr=127.0.0.1:9997&restartApplication.
Try making a change to the client-side code (for example `VMyList.java`),
hitting save and reloading the page to see how everything works
together. You can also run gwt:run in Debug As to debug the client-side
code.

Now the "save - build - deploy - try" cycle has been reduced to almost
instant for both client-side as well as server-side changes. Let the
real development begin.

[[developing-a-new-component-for-vaadin]]
Developing a new component for Vaadin
-------------------------------------

Wait for an amazing idea, code like crazy, enjoy and POOOF, there it is
- your own brand new component.

If you need guidance with this,
https://vaadin.com/book/-/page/gwt.html[Book of Vaadin] is a recommended
reading :)

For this example, I implemented a trivial list component. Take a look of
1.0.0 version
https://github.com/jojule/MyList/tree/496a8bdf629154a4da7b83c4a11979272959aa96[at
GitHub], but do not expect too much :) To try it out just do: `git clone
git@github.com:jojule/MyList.git; mvn package; mvn jetty:run` and point
your web browser to http://localhost:8080/mylist/.

[[packaging-and-submitting-the-widget-to-directory]]
Packaging and submitting the widget to directory
------------------------------------------------

Set the version number in pom.xml

Run Maven target "package" and you'll have a ready made package at
target/mylist-1.0.0.jar ready for upload to vaadin directory.

Go to https://vaadin.com/directory/my-components, select UI Component and
click upload.

Fill the form, preview and publish.
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-26 16:06:50 +0000
class="w"> parent, done: make(chan struct{}), } } // propagateCancel arranges for child to be canceled when parent is. func propagateCancel(parent Context, child canceler) { if parent.Done() == nil { return // parent is never canceled } if p, ok := parentCancelCtx(parent); ok { p.mu.Lock() if p.err != nil { // parent has already been canceled child.cancel(false, p.err) } else { if p.children == nil { p.children = make(map[canceler]bool) } p.children[child] = true } p.mu.Unlock() } else { go func() { select { case <-parent.Done(): child.cancel(false, parent.Err()) case <-child.Done(): } }() } } // parentCancelCtx follows a chain of parent references until it finds a // *cancelCtx. This function understands how each of the concrete types in this // package represents its parent. func parentCancelCtx(parent Context) (*cancelCtx, bool) { for { switch c := parent.(type) { case *cancelCtx: return c, true case *timerCtx: return c.cancelCtx, true case *valueCtx: parent = c.Context default: return nil, false } } } // removeChild removes a context from its parent. func removeChild(parent Context, child canceler) { p, ok := parentCancelCtx(parent) if !ok { return } p.mu.Lock() if p.children != nil { delete(p.children, child) } p.mu.Unlock() } // A canceler is a context type that can be canceled directly. The // implementations are *cancelCtx and *timerCtx. type canceler interface { cancel(removeFromParent bool, err error) Done() <-chan struct{} } // A cancelCtx can be canceled. When canceled, it also cancels any children // that implement canceler. type cancelCtx struct { Context done chan struct{} // closed by the first cancel call. mu sync.Mutex children map[canceler]bool // set to nil by the first cancel call err error // set to non-nil by the first cancel call } func (c *cancelCtx) Done() <-chan struct{} { return c.done } func (c *cancelCtx) Err() error { c.mu.Lock() defer c.mu.Unlock() return c.err } func (c *cancelCtx) String() string { return fmt.Sprintf("%v.WithCancel", c.Context) } // cancel closes c.done, cancels each of c's children, and, if // removeFromParent is true, removes c from its parent's children. func (c *cancelCtx) cancel(removeFromParent bool, err error) { if err == nil { panic("context: internal error: missing cancel error") } c.mu.Lock() if c.err != nil { c.mu.Unlock() return // already canceled } c.err = err close(c.done) for child := range c.children { // NOTE: acquiring the child's lock while holding parent's lock. child.cancel(false, err) } c.children = nil c.mu.Unlock() if removeFromParent { removeChild(c.Context, c) } } // WithDeadline returns a copy of the parent context with the deadline adjusted // to be no later than d. If the parent's deadline is already earlier than d, // WithDeadline(parent, d) is semantically equivalent to parent. The returned // context's Done channel is closed when the deadline expires, when the returned // cancel function is called, or when the parent context's Done channel is // closed, whichever happens first. // // Canceling this context releases resources associated with it, so code should // call cancel as soon as the operations running in this Context complete. func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc) { if cur, ok := parent.Deadline(); ok && cur.Before(deadline) { // The current deadline is already sooner than the new one. return WithCancel(parent) } c := &timerCtx{ cancelCtx: newCancelCtx(parent), deadline: deadline, } propagateCancel(parent, c) d := deadline.Sub(time.Now()) if d <= 0 { c.cancel(true, DeadlineExceeded) // deadline has already passed return c, func() { c.cancel(true, Canceled) } } c.mu.Lock() defer c.mu.Unlock() if c.err == nil { c.timer = time.AfterFunc(d, func() { c.cancel(true, DeadlineExceeded) }) } return c, func() { c.cancel(true, Canceled) } } // A timerCtx carries a timer and a deadline. It embeds a cancelCtx to // implement Done and Err. It implements cancel by stopping its timer then // delegating to cancelCtx.cancel. type timerCtx struct { *cancelCtx timer *time.Timer // Under cancelCtx.mu. deadline time.Time } func (c *timerCtx) Deadline() (deadline time.Time, ok bool) { return c.deadline, true } func (c *timerCtx) String() string { return fmt.Sprintf("%v.WithDeadline(%s [%s])", c.cancelCtx.Context, c.deadline, c.deadline.Sub(time.Now())) } func (c *timerCtx) cancel(removeFromParent bool, err error) { c.cancelCtx.cancel(false, err) if removeFromParent { // Remove this timerCtx from its parent cancelCtx's children. removeChild(c.cancelCtx.Context, c) } c.mu.Lock() if c.timer != nil { c.timer.Stop() c.timer = nil } c.mu.Unlock() } // WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)). // // Canceling this context releases resources associated with it, so code should // call cancel as soon as the operations running in this Context complete: // // func slowOperationWithTimeout(ctx context.Context) (Result, error) { // ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond) // defer cancel() // releases resources if slowOperation completes before timeout elapses // return slowOperation(ctx) // } func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) { return WithDeadline(parent, time.Now().Add(timeout)) } // WithValue returns a copy of parent in which the value associated with key is // val. // // Use context Values only for request-scoped data that transits processes and // APIs, not for passing optional parameters to functions. func WithValue(parent Context, key interface{}, val interface{}) Context { return &valueCtx{parent, key, val} } // A valueCtx carries a key-value pair. It implements Value for that key and // delegates all other calls to the embedded Context. type valueCtx struct { Context key, val interface{} } func (c *valueCtx) String() string { return fmt.Sprintf("%v.WithValue(%#v, %#v)", c.Context, c.key, c.val) } func (c *valueCtx) Value(key interface{}) interface{} { if c.key == key { return c.val } return c.Context.Value(key) }
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-26 16:06:49 +0000