Bug 859962 - Inaccuracies in Getting Started with Mobile POH5"
Inaccuracies in Getting Started with Mobile POH5"
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise WFK Platform 2
Classification: JBoss
Component: doc-Getting-Started-With-HTML5-Mobile-Web-Development (Show other bugs)
2.1.0
Unspecified Unspecified
high Severity medium
: GA
: 2.2.0
Assigned To: Sneha
Tomas Repel
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-09-24 09:43 EDT by Karel Piwko
Modified: 2014-11-09 18:02 EST (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-05-14 10:55:13 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
1.0.0.M6c index.html (17.52 KB, text/html)
2012-11-16 09:49 EST, Tomas Repel
no flags Details


External Trackers
Tracker ID Priority Status Summary Last Updated
JBoss Issue Tracker AEROGEAR-469 Critical Resolved Inaccuracies in Getting started with HTML5 tutorial 2013-03-25 10:10:18 EDT

  None (edit)
Comment 1 Karel Piwko 2012-09-24 09:46:08 EDT
Tomas Repel:
I've read the document, here are my observations. Hopefully at least some of them are relevant:

1.2.1. Using the Command Line
 - currently latest version of archetype available in maven central is 1.0.0.M4
 - at the very end of page there is a note about QUnit. What I miss is to tell the reader that the application server has to be up and running and the example should be deployed for QUnit tests to pass

1.2.2. Using JBoss Developer Studio
 - in Procedure 1.3. Deploying the Project with JBoss Developer Studio, after step 3.,Figure 1.2 Management tab picture is redundant, can be deleted

2.1. Client Source Code
 - the file index.html has a bit different content than the one shown in source code border, e.g. the title text and the paths to *.js files have changed

2.1.1. HTML5 Semantic Tags and Structure
 - in generated example in index.html, footer element is outside the the section element, not inside as shown in source code border

2.1.2. HTML5 Form API
 - in source code border, 'Register a user' should by replaced by 'Register a member'
 - typo in paragraph Input Validation: 'Safari,a nd' should be 'Safari, and'

2.1.4. CSS Files
 - it is said that there are two css files: screen.css and m.screen.css, but in the generated example there is third css file: d.screen.css

2.1.6.1. Member.java (and a few further sections too)
 - the package 'org/jboss/as/quickstarts/html5_mobile' used in the document does not correspond to the default package value 'org.jboss.tools.example.html5'

2.1.6.2. MemberService.java, the text between 2nd and 3rd source code border
 - It starts with 'The methods above...', but I think it is related to the methods in the source code border below, not above
 - I can't see the way how to access the members in XML format in the example, but the last sentence claims that it is possible
 - there is neither createMemberGet nor createMemberPost method in MemberService.java, only one createMember method. The 3rd and 4th source code border show code that is not in the example at all
 - only the last comment and last command from the code in the last (7th) source code border remain in MemberServce.java, the rest of code is shifted to the MemberRegistration's register method
Comment 2 Isaac Rooskov 2012-11-08 20:52:03 EST
1.2.1: Correct version shown and QUnit testing text updated

1.2.2: Agreed the image is redundant but may assist a user with their understanding of the procedure. 

2.1: Can you please provide the correct title and *.js file paths please
Comment 3 Isaac Rooskov 2012-11-08 21:05:17 EST
2.1.1: The footer element can be used inside or outside of a section.
Comment 4 Isaac Rooskov 2012-11-08 21:12:04 EST
2.1.2: code updated and typo fixed
Comment 5 Isaac Rooskov 2012-11-08 21:17:28 EST
2.1.4: Can you please let me know what the third CSS file is for? d.screen.css. The text in the book describes what the other two are for so I would like to be able to do the same for this third one. 

Thanks :)
Comment 6 Isaac Rooskov 2012-11-08 21:24:45 EST
2.1.6.1: Sorry I'm not sure what has to be changed here? Is the file location in the document wrong and should be pointing to a different file? If so, can you please let me know the filepath for the correct file. Thanks :D
Comment 7 Isaac Rooskov 2012-11-08 21:34:02 EST
2.1.6.2: All updated, though the text of below or above does refer to the above code sample.

For this: "I can't see the way how to access the members in XML format in the example" -> are you able to provide any missing XML?
Comment 9 Isaac Rooskov 2012-11-08 23:42:04 EST
In terms of 1.2.2, I now understand what you mean and have removed the image. Thanks for picking that up :) I didn't even notice the image was duplicated when looking over it again myself.
Comment 10 Tomas Repel 2012-11-16 09:47:28 EST
Hi Isaac, here's my notes:

1.2.1 - now OK, but meanwhile there are newer version available on maven central: 1.0.0.M6c

2.1 - see index.html in the attachment for content generated by 1.0.0.M6c archetype version

2.1.1 - hm, but if the footer is outside the section in generated example, it is better if the same says the documentation, but I agree this is a minor thing.

2.1.4 - there is a m.screen.css for Mobile devices, d.screen.css for Desktop machines and screen.css with styles common for both.

2.1.6.1 - the paths to the classes depends on how you generated the example from archetype. See chapter 1.2.1, Step Three. The paths depends on value for Package. If you leave the Package blank, the value from GroupID is taken. So the 'org/jboss/as/quickstarts/html5_mobile' part is not necessarily correct because reader can provide different Package or GroupID during generation. The solution could be to add some example value for Package or GroupID in 1.2.1, Step Three and then use this value in paths to java classes, e.g.: <project-root>/src/main/java/<example_value_for_package>/rest/MemberService.java

2.1.6.2
 - 3rd paragraph: 'There are two ways of ...till the very end' - this section is not true anymore, currently there is only one way how to create member, the one using POST approach. Thus this has to be rewording accordingly. Something simple should be enough, there is also the code snippet of createMember method that is responsible for creating new members.

 - 3rd code border '//Create a new member class from fields ...' - this refers to removed GET approach, this code is no longer in the example. The two lines above relates to this code border, should be removed as well.

Hopefully it's a bit clearer now, I will see :)
Comment 11 Tomas Repel 2012-11-16 09:49:03 EST
Created attachment 646350 [details]
1.0.0.M6c index.html
Comment 12 Isaac Rooskov 2012-11-19 23:07:39 EST
2.1: Do we need to include the code? Since the code will continually change can we just remove it and explain the file without the code snippets included
Comment 13 Isaac Rooskov 2012-11-19 23:23:07 EST
2.1.6.1: As same as for 2.1 I feel that the code can become very outdated, very fast and doesn't add much to a users understanding of what is being explained (since they could easily look at the distributed code). So I think we could remove the code....what do you think?
Comment 14 Isaac Rooskov 2012-11-19 23:29:17 EST
All other issues have been corrected
Comment 16 Tomas Repel 2012-11-20 04:46:34 EST
I would say the code can be removed. You're right that users can look at the code directly.

2.1 (Header title): I have noticed that the all the paragraphs here refer to index.html with one exception - the 'The app.js...' paragraph. I would move this to the end of the section (right after the '3. When these are complete...')
Comment 17 Isaac Rooskov 2012-11-21 01:28:25 EST
Hey Tomas,

I've updated the guide with the fix in your last comment and have removed the code I feel doesn't need to be in the guide to assist with explanation.
Comment 19 Tomas Repel 2012-11-26 11:41:10 EST
Hello, few other issues:

1.2.1 - in '$JBOSS_HOME/bin/standalone.bat' path for windows the backslashes should be used. There are two occurrences of this path.

Chapter 2. Further Information - in very first paragraph, 'quickstarts that are part' should be replaced by 'quickstart that is part'

2.1.4. CSS Files
  - just reminder that note about d.screen.css still missing (see comment 5 and comment 10)
  - in code border, replace 'tr:' by '> div:'

2.1.6.2 MemberService.java - replace 'them' by 'then' in '...member is not valid them a map is created...'
Comment 20 Isaac Rooskov 2012-11-26 19:37:51 EST
for d.screen.css the text was rewritten based on the information given in the referenced comments and the note is no longer necessary for what is being described.
Comment 21 Isaac Rooskov 2012-11-26 19:38:09 EST
All other issues now fixed
Comment 25 JBoss JIRA Server 2012-11-28 08:47:19 EST
Lucas Holmquist <lholmqui@redhat.com> made a comment on jira AEROGEAR-469

Hey guys,  just wanted to know how these changes will make it back to our repo,  will a PR be sent?
Comment 26 JBoss JIRA Server 2012-11-29 06:40:34 EST
Karel Piwko <kpiwko@redhat.com> made a comment on jira AEROGEAR-469

Hi Lucas,

for some of those changes it would definitely make sense to do a PR and backport changes to upstream. I'll try to coordinate that next week.
Comment 27 JBoss JIRA Server 2012-12-10 08:42:17 EST
Lucas Holmquist <lholmqui@redhat.com> made a comment on jira AEROGEAR-469

Hey Karel,  just wanted to see if there was any new status on this
Comment 31 JBoss JIRA Server 2012-12-11 09:14:32 EST
Tomas Repel <trepel@redhat.com> made a comment on jira AEROGEAR-469

Hello Lucas,
Pull Request sent, if something unclear or something could be done better, just let me know. Pull Request URL: https://github.com/aerogear/aerogear.org/pull/16
Comment 32 JBoss JIRA Server 2012-12-17 14:41:36 EST
Lucas Holmquist <lholmqui@redhat.com> updated the status of jira AEROGEAR-469 to Resolved
Comment 36 Tomas Repel 2013-03-08 05:37:02 EST
Verified in WFK 2.2.0.ER1.
Comment 37 Karel Piwko 2013-05-14 10:55:13 EDT
Closed as CURRENTRELEASE, part of WFK 2.2.0 distributables.

Note You need to log in before you can comment on or make changes to this bug.