Absurdities in docs, examples, tutorials, blogs and repositories

Vaadin 6 / 7 / 8
1

I find very frustrating that everytime I take a look at the docs to learn any new concept or simply find some example or reference, no matter if it is a very simple concept or a more tricky one, I always stumble over the same stone, having to find a lot of things by trial & error instead of having them written down in the ·$)"%·$% manual.

For instance, today I’m trying to learn how to embed custom javascript in my own components.

First of all, I went to the CustomLayout reference, as although I never used it before I knew it was there and probably would fit to my purposes because I need to manipulate a concrete tag.

Well, nowhere in https://vaadin.com/docs/-/part/framework/layout/layout-customlayout.html could I find an example on how to load the .html file that is supposed to hold the layout. They say that “a template is a HTML file located under layouts folder under a theme folder under the /VAADIN/themes/ folder, for example, /VAADIN/themes/themename/layouts/mylayout.html”, and then that “A template can also be provided dynamically from an InputStream, as explained below”.

Well, there’s NO SINGLE PLACE ANYWHERE I CAN FIND explaining how are you supposed to initialize your layout with that file. There is an example below telling how to initialize the object… ¡with a new ByteArrayInputStream() with some inline HTML! And another one using a new FileInputStream(file). BUT NO SINGLE PLACE DOING SOMETHING LIKE new CustomLayout(“mylayout”) or “mylayout.html” or “layouts/mylayout” or “layouts/mylayout.html”. Go to the sampler (http://demo.vaadin.com/sampler/#ui/layout/custom-layout) and there, in the “Source” tab, they say that the custom HTML belongs to examplecustomlayout.html, but, AGAIN, YOU CAN’T FIND ANYWHERE HOW THEY LOADED THAT FILE: again, in the source code excerpt, they “load” “someething” with a sample = new CustomLayout(inputStream) (what an obsession with inputStream!), but they even don’t bother to write that “inputStream” is. Finally, you end trying many combinations in order to find if you can put an string with an html file name in the constructor (something that, to this moment, I still haven’t accomplished yet).

Then you go to the Javascript integration section (https://vaadin.com/docs/-/part/framework/gwt/gwt-javascript.html) and you decide that the approach of extending AbstractJavaScriptComponent seems to be the right one for you. They say that in the @JavaScript annotation you put the js files you want to use, and it is clear when it is an external one (you put the full url), but when it comes to place YOUR OWN js files (for instance, ({“mylibrary.js”})), again IT ISN’T STATED ANYWHERE WHERE YOU ARE SUPPOSED TO PLACE THOSE FILES. Should it be in the same folder where the corresponding java file is? Should it be in /VAADIN? in /WEB-INF? in some /js child folder of any of those prior two directories? WHY is it not stated anywhere? You do some googling in order to try to save some trial-and-erroring and you seem to find a reference in the Vaadin blog (https://vaadin.com/wiki?p_p_id=36&p_p_lifecycle=0&p_p_state=normal&p_p_mode=view&p_p_col_id=row-1&p_p_col_pos=2&p_p_col_count=4&_36_struts_action=%2Fwiki%2Fview&p_r_p_185834411_nodeName=vaadin.com+wiki&p_r_p_185834411_title=Integrating+a+JavaScript+component). But, again… amazingle… they don’t say that there neither! Oh wait; maybe there’s some source code of the example available. Look, they say something about “a repository with the code at https://github.com/aanno/More-Vaadin, directory Blog_2012-08-13” in the 1st comment (what a strange place to inform that the source code is available!); let’s take a look… Wait! The repository exists, but… THERE’S NO SUCH DIRECTORY and the example source code cannot be found anywhere. There are even some users in the comments complaining that they cannot be found. I will post a comment asking for them… Oh no! “The Vaadin Wiki is temporarily in read only mode due to large recent spam attacks”! Haven’t this message been on display for ages?

Well, we have one last chance before some even more trialanderroring. I will place my .js file wherever my gonades tell me and I will take a look at the source code to see if there is some path info added to the specified name. OH WAIT. “http://localhost:8080/app/APP/PUBLISHED/myFile.js”??? “/APP/PUBLISHED”??? Where in the filesystem am I supposed to find such a path???

It’s been an hour of trial & error and all I see in my Vaadin app is a message saying “Could not initialize JavaScriptConnector because no JavaScript init function was found. Make sure one of these functions are defined: com_my_fq_dn_myFile”, and yeah, that function exists in my file, but my file it’s still not found. Mix that with a silly upper/lowercase letter mistake and you’ll inter into infinite loop for ages.

Why? WHY these absurdities and inconsistences? Sum the hour I’ve already spent these rants and you’ll find why development with Vaadin is SOOOOOOO slow and frustrating. You have to resort to the forum to see if some frustrated user like has alread pulled his hair trying to find the answer, and usually what you find are posts from several years ago with such silly bugs that still hasn’t been fixed.

Instead of bombing with marketing email, discount offers, friendship requests, customer service agents while browsing the site and spam emails to addresses never been used to contact the Vaadin staff (yes, my boss even received a direct marketing email and we still haven’t figured out how they got the address because he wasn’t in the CC list), it would offer a far better image if these frustrating issues where addressed.

2

Just for the record and for my own reference:

  1. You can initialize a CustomLayout by just passing an String to the constructor with the name, without extension, of the HTML file you’re using to hold the layout after having put it inside
    /VAADIN/themes/yourTeme/layouts/
    . For instance, if you have /VAADIN/themes/yourTeme/layouts/yourhtmlfile.html, you could do:
layout = new CustomLayout("yourhtmlfile");
3
  1. You can find the source code missing at the Javascript integration tutorial commented above (or something close enough) here:

https://github.com/osbominix/vaadin-jquery-flot

Credit for this goes to
ridcully
 of the vaadin freenode irc channel, who kindly enough provided it to me after I failed miserably when searching for it at gitHub. Thanks ridcully!!

4
  1. A finding I just did thanks to the link above:

I found an ¿undocumented? url/link/path format in the source code of the example (or, at least, I’ve been unable to find it in my Book of Vaadin) which is used to link to the js sources and partly answers my doubts about the placement of the .js files:

@JavaScript({"https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js", "vaadin://js/jquery.flot.js", "vaadin://js/flot_connector.js"})

Looking at the vaadin:// and knowing the source code tree of the project, looks like you can reference everything you put inside your /VAADIN folder this way. Amazing they didn’t consider this important enough to mention it in the docs. Wow!

5

Hi,

Thanks for the feedback. You can open a issue at
https://github.com/vaadin/framework/issues
 Those kind of issues with documentation are highly valuable for the Vaadin development team and the community in the end. I know sometimes is hard to find the documentation for some specific feature. It’s a huge challenge to maintain documentation in software projects! But yeah, there definitively are things that can be improved a lot. But let me share how I deal with this.

When I’m coding, I usually read the API documentation in the javadocs, directly in the IDE, which is the fastest thing to do (also available at
vaadin.com/api
). Then, if for some reason that’s not good enough for me, I search on google.com. If that doesn’t help, I jump to
vaadin.com/docs
. If still nothing, I search in the forums at
vaadin.com/forum
. If no luck, I try with the sampler at
demo.vaadin.com/sampler
. If still nothing, I ask on the forums, and meanwhile, jump to the IDE again and try following the source code. So far, that has resulted in not only an effective strategy, but an enriching one, and I consider it an escential part of the fun when working with Open Source technologies.

Just my two cents. Cheers!

6

Thanks for your reply, Alejandro.

I just want to say that… of course I do all that. Evidently, I use autocompletion/code hinting/intellisense/whatever they want to call this feature in their ide (in my case, I use Netbeans). I would be terribly lost if I hadn’t this feature enabled.

Of course, during day I do a lot of googling (it would be absurd if I didn’t try an answer by myself before asking, here or wherever), and I’m a user of sites like
StackOverflow
, which often is a valuable source of help for Vaadin questions, too.

As you may found out, I’m an avid user of this forum, if you take into account the number of messages I’ve written in the relatively little amount of time I’ve been a user of it.

Not to say that I first always RTFM and/or try to find examples in the sampler. That’s the 1st thing I said when I opened this thread.

Following the source code? Of course. In fact I have to admit that I’ve been navigating through hundreds of lines of Vaadin source code and I think I have a somewhow deep knowledge of how certain parts of the framework work, specially those regarding database access. Hadn’t done that, I wouldn’t have been able to ever solve a lot of aspects. That’s being doing in conjunction with debugger: I place certain breakpoints in my code when it’s about to fail, then proceed line by line to see what Vaadin is doing and haven’t been able to find a prior explanation anywhere. That’s the last resource when you are totally lost, although a very slow and tedious method, and it’s not always applicable.

There is even another great source of help I use regularly, as you can infer from my previous comments, that you forgot to mention: IRC.

I appreciate your suggestions, but again, and sadly feeling that I’m going to sound rude again, I feel like your answer is more of a “semi-automatic” one, as it doesn’t address what I complained about in my original message. As if you where somehow forced by your bosses to reply users in the forum.

What I complained about the constructor of CustomLayout is not quick nor funny to find out in any case. Just by trial and error. Whatever solution you take (googling, debugging or trial and error) it’s gonna be slow for such a trivial thing. I already solved it hours ago, but it was a pain. I hadn’t still resolved it by trial and error when I found the missing sources of the referenced wiki entry and saw the vaadin:// syntax I’d never seen before. Then it was a breeze: tried it and it worked at the 1st attempt. D’oh.

I understand that maybe posts in the wiki are not guaranteed to be the best realiable source of help and/or not mantained by Vaadin, inc. (I sincerely don’t know if the entry I referenced was done by a member of the team), but please understand that if the wiki hadn’t been in “read mode due to recent spam attacks” other users could have post there their findings had they found them, and/or the author would have noticed that visitors were complaining because the sources were missing. That has nothing to do with the ability one has finding more or less creative ways of getting help.

My impression is that some basical issues should be addressed before attempting very agressive marketing tactics and/or even releasing new major versions. Of course, it’s not my bussiness and I’m benefiting of your work for free (?) (the truth is that it’s been an imposition that’s not in my hands), but I had to express my opinion.

And, finally, I know that I may sound rude sometimes and that I need to be more polite. I feel really sorry for that. Also English is not my mother tongue and most of times it’s already enough difficult for me to make me explain that I don’t know how to express it more “subtly”. Shame on me.

As a last word, at least I always try to share my findings in order to contribute somehow.

7

Fortunatelly, I’m not forced to do anything. If I wanted, I could stop answering forum posts :slight_smile: But anyways… Good that you have a space where to share your thoughts and contribute. Also, good that you figured out the solution to your technical problem. Cheers!

8

One helpful resource I use quite a lot: add-ons in the Directory. Most of them have sources available and there’s a ton of helpful code examples to be found there. It’s not easily browseable, but once you’ve got a picture what you can find there, it can be a good place to look.

9

Well, Alejandro, unfortunately I haven’t found the solution to the problem that lead me to open this thread, which is related to http basic auth to another url inside my Vaadin app, but at least I think everything is resolved from the Vaadin part. Again, as I think I really tried all the points from your checklist of help resources, at least it’s been put here for reference for anyone else. And also I must admit that, although I considered it in prior situations, I had almost forgot about the proposed point by Olli: resorting to the add-ons in the Directory. I considered once to check the source code of some of them, but quickly abandoned the idea because either I found the solution by any other mean(s) and/or was thinking that maybe they were only available in binary form. Thanks a lot to both of you!

10

Pere,
THANK YOU SO MUCH for this post!!! None of the examples I’ve seen for the JavaScript Component information seem to work. I’ve gotten to the point of where my js files are now recognized and published, but I’m not able to invoke any methods from the js file.

Alejandro x Olli, thank you for the tips. However, could either of you point us in the direction of a comprehensive guide to implementing the Java/JavaScript integration?

-TU

11

Tajiri, some resources:


https://vaadin.com/docs/-/part/framework/advanced/advanced-javascript.html


https://vaadin.com/docs/-/part/framework/gwt/gwt-javascript.html


https://vaadin.com/api/com/vaadin/ui/AbstractJavaScriptComponent.html

Quite fragmented at the moment, though. I’ll write a blog post or record a video showing this in practice at some point :slight_smile:

12

Alejandro,

Thanks a mil! Those links have actualy been pages in my JS Component Implementation BIBLE. :slight_smile: Another informative post is https://vaadin.com/forum#!/thread/8041905.

So, I have done most of what is outlined in the links above. My widgetset compiles, but when I launch the web app I get:

“Communication problem…Invalid JSON response from server”

Please see the attached PNG. We’re deploying to WebLogic.

I’m hoping that tutorial can be done in the very near future!

-TU
32301.png

13

Thanks a lot for your nice words, Tajiri. Althought I cannot help you with your last question about the “Communication problem” (maybe you could provide a bit more background info about what you are doing), I’m posting another inconsistence I’ve found in Vaadin (it’s not related to your problem but I thought of this thread as a container for miscellaneous findings).

This time it’s regarding the difference between “ReadOnly” and “Disabled” fields. Well, the explanations
here
 (
https://vaadin.com/wiki/-/wiki/Main/ReadOnly+vs.+Disabled+fields
) would be great if it weren’t because
when you set a CheckBox field as ReadOnly it looks exactly as if it were / was (?) writable
 in the Valo theme by default, thus forcing you to set it (erronously) as disabled if you don’t know how to style it, or providing a bad UI experience if you leave it that way because the user will try to check / uncheck it.

Probably it would look better and provide some difference with the disabled and writeable states if they had styled it with, let’s say, its label in black and the box itself as greyed out.

PS: I would have posted this as a comment there if it weren’t because

PS 2: cursives in the quote above are mine.

14

In fact, that whole wiki entry is totally outdated. The text field itself that they used as an example looks now almost identical both in disabled and readonly mode. They’d better remove it as looks like they are against their own reasoning…

15

Changing the look of the ReadOnly CheckBox was relatively easy with css:

span.v-checkbox.v-readonly > input ~ label:before {
       background-color: #fafafa !important;
        background-image: linear-gradient(to bottom,#fafafa 2%,#efefef 98%) !important;
        border-color: #eaeaea !important;
    }

Unfortunately, the absurdities of the ReadOnly / Disabled behaviour didn’t end here: I just discovered that you cannot programatically set a value for a ReadOnly TextField. There is code in AbstractField.java that that explicitly will throw an exception in this case. Well, it’s stated in the link the the wiki I posted above, but it seems I’m not the only one who didn’t notice it at 1st sight, as others did about 3 years ago:


http://stackoverflow.com/questions/25192327/programmatically-set-a-textfields-value-while-in-readonly-mode

So this is a good one. I think that, in the end, I shouldn’t try to understand what the Vaadin team didn’t understand themselves and better stick to what “kind of” works, ie, Disabled.