From 2299b4c4988e6c0ecde6aa5107d6c7f6592fa7c9 Mon Sep 17 00:00:00 2001 From: Matt Raible Date: Fri, 14 Dec 2018 05:45:16 -0700 Subject: [PATCH 1/4] Remove duplicate section, align left where appropriate Former-commit-id: 92d3ec7074ec2ac32ef3f1d4eec828dd757f56f2 --- src/docs/asciidoc/chapters/chapter2.adoc | 146 ++---------------- src/docs/asciidoc/chapters/preface.adoc | 7 +- src/docs/asciidoc/index.adoc | 2 +- .../styles/pdf/infoq-prepress-theme.yml | 1 + .../styles/pdf/infoq-screen-theme.yml | 1 + 5 files changed, 22 insertions(+), 135 deletions(-) diff --git a/src/docs/asciidoc/chapters/chapter2.adoc b/src/docs/asciidoc/chapters/chapter2.adoc index deb3a04..d9f0dc7 100644 --- a/src/docs/asciidoc/chapters/chapter2.adoc +++ b/src/docs/asciidoc/chapters/chapter2.adoc @@ -1,137 +1,13 @@ -= Preface - -A few years ago, I consulted at several companies that used Spring and Java to develop their back-end systems. On those projects, I introduced Spring Boot to simplify development. DevOps teams often admired its external configuration and its starter dependencies made it easy to develop SOAP and REST APIs. - -I used AngularJS for several years as well. For the first project I used AngularJS on, in early 2013, I implemented in 40% of the code that jQuery would've required. I helped that company modernize its UI in a project for which we integrated Bootstrap. I was very impressed with both AngularJS and Bootstrap and have used them ever since. In 2014, I used Ionic on a project to implement a HTML5 UI in a native iOS application. We used AngularJS, Bootstrap, and Spring Boot in that project and they worked very well for us. - -When I heard about JHipster, I was motivated to use it right away. It combined my most-often-used frameworks into an easy-to-use package. For the first several months I knew about JHipster, I used it as a learning tool — generating projects and digging into files to see how it coded features. The JHipster project is a goldmine of information and lessons from several years of developer experience. - -I wanted to write this book because I knew all the tools in JHipster really well. I wanted to further the knowledge of this wonderful project. I wanted Java developers to see that they can be hip again by leveraging AngularJS and Bootstrap. I wanted to show them how JavaScript web development isn't scary, it's just another powerful platform that can improve your web-development skills. - -The first version of this book was released in October 2015, the second in December 2016, and the third (4.x to match Angular) was released in the fall of 2017 after JHipster migrated to Angular. Version 4.5 was released in April 2018 with an additional chapter on microservices. This version is updated for JHipster version 5. I spent a lot of time learning Angular and TypeScript in 2016-2018 and I'm pleased to bring you this book as an active member of the JHipster Development Team. - -== What is in an InfoQ mini-book? - -InfoQ mini-books are designed to be concise, intending to serve technical architects looking to get a firm conceptual understanding of a new technology or technique in a quick yet in-depth fashion. You can think of these books as covering a topic strategically or essentially. After reading a mini-book, the reader should have a fundamental understanding of a technology, including when and where to apply it, how it relates to other technologies, and an overall feeling that they have assimilated the combined knowledge of other professionals who have already figured out what this technology is about. The reader will then be able to make intelligent decisions about the technology once their projects require it, and can delve into sources of more detailed information (such as larger books or tutorials) at that time. - -== Who this book is for - -This book is aimed specifically at web developers who want a rapid introduction to Angular, Bootstrap, and Spring Boot by learning JHipster. JHipster 5 adds support for React as well, but I won’t be covering it in this book since Angular is the default. If I added React coverage, this would no longer be a mini-book. 😉 - -TIP: If you'd like to see a React version of the app developed in this book, check out https://github.com/robmelfi/21-points-react[Roberto Melfi's 21-points-react project]. - -== What you need for this book - -To try code samples in this book, you will need a computer running an up-to-date operating system (Windows, Linux, or Mac OS X/macOS). You will need Node.js and Java installed. The book code was tested against Node.js 8 and JDK 8, but newer versions should also work. - -NOTE: It _should_ be possible to run a JHipster app on Java 9+ because it’s possible to use Java 10 with Spring Boot 2.0.1. Java 11 support is in Spring Boot 2.1. However, JHipster depends on many plugins that are not yet Java 9+ compatible. The most common error is `java.lang.NoClassDefFoundError: javax/xml/bind/JAXBException`. For this reason, I recommend using Java 8. - -== Conventions - -We use a number of typographical conventions within this book that distinguish between different kinds of information. - -Code in the text, including commands, variables, file names, CSS class names, and property names are shown as follows. - -[example] -Spring Boot uses a `public static void main` entry-point that launches an embedded web server for you. - -A block of code is set out as follows. It may be colored, depending on the format in which you're reading this book. - -[source,html] -.src/app/search/search.component.html ----- -
- - -
----- - -[source,java] -.src/main/java/demo/DemoApplication.java ----- -@RestController -class BlogController { - private final BlogRepository repository; - - // Yay! No annotations needed for constructor injection in Spring 4.3+. - public BlogController(BlogRepository repository) { - this.repository = repository; - } - - @RequestMapping("/blogs") - Collection list() { - return repository.findAll(); - } -} ----- - -When we want to draw your attention to certain lines of code, those lines are annotated using numbers accompanied by brief descriptions. - -[source,javascript] ----- -export class SearchComponent { - constructor(private searchService: SearchService) {} <1> - - search(): void { <2> - this.searchService.search(this.query).subscribe( <3> - data => { this.searchResults = data; }, - error => console.log(error) - ); - } -} ----- -<1> To inject `SearchService` into `SearchComponent`, add it as a parameter to the constructors's argument list. -<2> `search()` is a method that's called from the HTML's ` ---- @@ -103,10 +103,13 @@ Finally, this text shows what a quote looks like: We always welcome feedback from our readers. Let us know what you thought about this book — what you liked or disliked. Reader feedback helps us develop titles that deliver the most value to you. +[.text-left] To send us feedback, email us at feedback@infoq.com, send a tweet to @jhipster_book, or post a question on Stack Overflow using the "`jhipster`" tag. +[.text-left] If you're interested in writing a mini-book for InfoQ, see http://www.infoq.com/minibook-guidelines. ifeval::["{media}" == "prepress"] +[.text-left] The most up-to-date version of this book can be downloaded from https://infoq.com/minibooks/jhipster-mini-book. endif::[] diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index b7a0ce5..6535eb7 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -2,7 +2,7 @@ :book-title: {doctitle} :author: Matt Raible :email: matt@raibledesigns.com -:revnumber: 5.0.0 +:revnumber: 5.0.1 :revdate: {docdate} :revyear: 2018 :subject: JHipster diff --git a/src/docs/asciidoc/styles/pdf/infoq-prepress-theme.yml b/src/docs/asciidoc/styles/pdf/infoq-prepress-theme.yml index fc28ea6..eedfdfe 100644 --- a/src/docs/asciidoc/styles/pdf/infoq-prepress-theme.yml +++ b/src/docs/asciidoc/styles/pdf/infoq-prepress-theme.yml @@ -206,6 +206,7 @@ outline_list: # NOTE item_spacing applies to list items that do not have complex content item_spacing: $vertical_rhythm / 2 #marker_font_color: 404040 + text_align: left table: background_color: $page_background_color #head_background_color: diff --git a/src/docs/asciidoc/styles/pdf/infoq-screen-theme.yml b/src/docs/asciidoc/styles/pdf/infoq-screen-theme.yml index f2aca04..dd9f8cd 100644 --- a/src/docs/asciidoc/styles/pdf/infoq-screen-theme.yml +++ b/src/docs/asciidoc/styles/pdf/infoq-screen-theme.yml @@ -203,6 +203,7 @@ outline_list: # NOTE item_spacing applies to list items that do not have complex content item_spacing: $vertical_rhythm / 2 #marker_font_color: 404040 + text_align: left table: background_color: $page_background_color #head_background_color: From d07501e722d1e76c7f740fde6e3990f66d7b94ba Mon Sep 17 00:00:00 2001 From: Matt Raible Date: Fri, 14 Dec 2018 06:40:10 -0700 Subject: [PATCH 2/4] Fix issues through chapter 3 Former-commit-id: 918fbca3d8647abf025328bcce6d79e99b8d8bf7 --- Gemfile | 2 +- src/docs/asciidoc/chapters/chapter2.adoc | 16 ++++---- src/docs/asciidoc/chapters/chapter3.adoc | 37 ++++++++---------- .../images/chapter2/ui-mockup.graffle | Bin 11855 -> 45388 bytes .../asciidoc/images/chapter2/ui-mockup.png | Bin 185705 -> 72690 bytes 5 files changed, 25 insertions(+), 30 deletions(-) diff --git a/Gemfile b/Gemfile index eb6f4f5..a4e2bcf 100644 --- a/Gemfile +++ b/Gemfile @@ -2,4 +2,4 @@ source 'https://rubygems.org' gem 'coderay' gem 'Ascii85' -gem 'asciidoctor-pdf', github: 'asciidoctor/asciidoctor-pdf', ref: '03ceac32e426421ebd6ef2499a14f5aac40ec47b' +gem 'asciidoctor-pdf', github: 'asciidoctor/asciidoctor-pdf', ref: 'a92ef7e7f7ecc862c2db4f5a4a46d66d0c1f111c' diff --git a/src/docs/asciidoc/chapters/chapter2.adoc b/src/docs/asciidoc/chapters/chapter2.adoc index d9f0dc7..d8588c7 100644 --- a/src/docs/asciidoc/chapters/chapter2.adoc +++ b/src/docs/asciidoc/chapters/chapter2.adoc @@ -279,7 +279,7 @@ ifeval::["{media}" == "screen"] I wanted 21-Points Health to be a bit more hip than a stock JHipster application. Bootstrap was all the rage a few years ago, but now Google's https://material.io/[Material Design] is growing in popularity. I searched for "material" in the https://www.jhipster.tech/modules/marketplace/[JHipster Marketplace] and found the https://www.jhipster.tech/modules/marketplace/#/details/generator-jhipster-bootstrap-material-design[Bootstrap Material Design] module. Unfortunately, I soon found out it doesn't support JHipster 4+. endif::[] ifeval::["{media}" == "prepress"] -I wanted 21-Points Health to be a bit more hip than a stock JHipster application. Bootstrap was all the rage a few years ago, but now Google's Material Design is growing in popularity. I searched for "material" in the JHipster Marketplace and found the Bootstrap Material Designope module. Unfortunately, I soon found out it doesn't support JHipster 4+. +I wanted 21-Points Health to be a bit more hip than a stock JHipster application. Bootstrap was all the rage a few years ago, but now Google's Material Design is growing in popularity. I searched for "material" in the JHipster Marketplace and found the Bootstrap Material Design module. Unfortunately, I soon found out it doesn't support JHipster 4+. endif::[] In v4 of this book (and 21-Points Health), I opted to use Bootstrap and its default theme; changing some variables so it looked like Angular Material. Since I got used to it, I decided to keep this same setup for this version. To make the default Bootstrap theme look like Material Design, modify `_bootstrap-variables.scss` and replace it with the contents below. @@ -650,8 +650,8 @@ Below is a consolidated list of changes I made to the HTML to make things look b * improved layout of tables and buttons, * improved titles and button labels by editing generated JSON files in `src/main/webapp/i18n/en`, -* formatted dates for local timezone with https://angular.io/api/common/DatePipe[Angular's DatePipe] - (for example: `{{bloodPressure.timestamp | date:'short': 'UTC'}}`), +* formatted dates for local timezone with Angular's DatePipe + (for example: `{{bloodPressure.timestamp | date:'short'}}`), * defaulted to current date on new entries, * replaced point metrics with icons on list/detail screens, and * replaced point metrics with checkboxes on update screen. @@ -1882,8 +1882,6 @@ I read the https://devcenter.heroku.com/articles/custom-domains[documentation], I also configured a custom resource record with a CNAME to point to `health-by-points.herokuapp.com`. -ifdef::backend-pdf[<<<] - .Custom resource record on Google Domains |=== |Name |Type |TTL |Data @@ -1969,6 +1967,7 @@ Setting SENDGRID_PASSWORD, SENDGRID_USERNAME and restarting health-by-points... Use `heroku addons:docs sendgrid` to view documentation. ---- +[.text-left] Then I updated `application-prod.yml` to use the configured `SENDGRID_PASSWORD` and `SENDGRID_USERNAME` environment variables for mail, as well as to turn on authentication. [source,yaml] @@ -1998,7 +1997,7 @@ After repackaging and redeploying, I used the built-in health-checks feature of == Monitoring and analytics -JHipster generates the code necessary for Google Analytics in every application's `src/main/webapp/index.html` file. I chose not to enable this just yet, but I hope to eventually. I already have a http://www.google.com/analytics/[Google Analytics] account, so it's just a matter of creating a new account for www.21-points.com, copying the account number, and modifying the following section of `index.html`: +JHipster generates the code necessary for Google Analytics in every application's `src/main/webapp/index.html` file. I chose not to enable this just yet, but I hope to eventually. I already have a Google Analytics account, so it's just a matter of creating a new account for www.21-points.com, copying the account number, and modifying the following section of `index.html`: [source,html] .src/main/webapp/index.html @@ -2195,13 +2194,12 @@ Then I ran all the tests and the `sonarqube` task. /gradlew -Pprod clean test sonarqube ---- -Once this process completes, an analysis of the project is available on the Sonar dashboard at http://127.0.0.1:9001. 21-Points Heath is a triple-A-rated app! Not bad, eh? +Once this process completed, an analysis of the project was available on the Sonar dashboard at http://127.0.0.1:9001. 21-Points Heath is a triple-A-rated app! Not bad, eh? [[sonar-results]] .Sonar results image::chapter2/sonar.png[Sonar results, 1500, scaledwidth=100%, align=center] - == Progressive web apps Progressive web apps, aka PWAs, are the best way for developers to make their web apps load faster and perform better. In a nutshell, PWAs are websites that use recent web standards to allow for installation on a user’s computer or device, and deliver an app-like experience to those users. @@ -2270,7 +2268,7 @@ After getting this application into a good enough state, I moved it from Bitbuck After I finished developing the MVP of 21-Points Health with JHipster 5.3.0, I wanted to upgrade it to the latest release. I used the https://www.jhipster.tech/upgrading-an-application/[upgrade sub-generator], and upgraded it to 5.3.4, then again to 5.4.2. -TIP: If the upgrade sub-generator doesn't work for you when upgrading JHipster, you can manually upgrade using http://www.syntevo.com/smartsynchronize/[SmartSynchronize]. You can do this by creating a new branch, running `rm -rf *` in your project, then running `jhipster --with-entities`. Then use SmartSynchronize to compare files and restore your custom code. +TIP: If the upgrade sub-generator doesn't work for you when upgrading JHipster, you can manually upgrade. You'll want to make sure your project is checked into source control first. Then, create a new branch and run `rm -rf *` in your project, followed by `jhipster --with-entities`. After this process completes, use your favorite tool (e.g., IntelliJ IDEA) to compare changed files and restore your custom code. If you're reading this and notice that 21-Points Health is using a version newer than 5.4.2, it's likely because I upgraded again. diff --git a/src/docs/asciidoc/chapters/chapter3.adoc b/src/docs/asciidoc/chapters/chapter3.adoc index 7bc9295..cb51195 100644 --- a/src/docs/asciidoc/chapters/chapter3.adoc +++ b/src/docs/asciidoc/chapters/chapter3.adoc @@ -9,17 +9,13 @@ This section shows how JHipster includes all of these UI components for you and JHipster supports two UI frameworks: Angular and React. In the first two versions of this book, I showed you how to use AngularJS. In the last two versions (4.0 and 4.5), I showed you how to use Angular. Since this is a mini-book, I'm going to stick with showing Angular only. You can see from the following graphs that Angular and React are the most popular among JavaScript frameworks. -[.clearfix] --- -[.left] [[img-angular-jobs-2018]] .Jobs on Indeed, September 2018 -image::chapter3/angular/indeed-jobs-sep2018.jpg[Jobs on Indeed, 450, scaledwidth=75%] -[.left] +image::chapter3/angular/indeed-jobs-sep2018.jpg[Jobs on Indeed, 450, scaledwidth=75%, align=center] + [[img-stackoverflow-tags-2018]] .Stack Overflow Tags, September 2018 -image::chapter3/angular/stackoverflow-tags-sep2018.jpg[Tags on Stack OverFlow, 450, scaledwidth=75%] --- +image::chapter3/angular/stackoverflow-tags-sep2018.jpg[Tags on Stack OverFlow, 450, scaledwidth=75%, align=center] Angular is the default UI framework used by JHipster. It's written in TypeScript, compiles to JavaScript, and just using it makes you a hipster! Like Struts in the early 2000s and Rails in the mid-2000s, Angular and other JavaScript frameworks have changed the way developers write web applications. Today, data is exposed via REST APIs and UIs are written in JavaScript (or TypeScript). As a Java developer, I was immediately attracted to Angular when I saw its separation of concerns. It recommended organizing your application into several different components: @@ -44,11 +40,11 @@ A new syntax was introduced that binds data to element properties, not attribute ---- -In March 2015, the Angular team http://www.infoq.com/news/2015/03/angular-2-concerns-addressed[addressed community concerns], announcing that they would be using http://www.typescriptlang.org/[TypeScript] over AtScript and that they would provide a migration path for Angular 1.x users. They also adopted semantic versioning and http://angularjs.blogspot.com/2017/01/branding-guidelines-for-angular-and.html[recommended people call it "Angular" instead of Angular 2.0]. +In March 2015, the Angular team http://www.infoq.com/news/2015/03/angular-2-concerns-addressed[addressed community concerns], announcing that they would be using TypeScript over AtScript and that they would provide a migration path for Angular 1.x users. They also adopted semantic versioning and http://angularjs.blogspot.com/2017/01/branding-guidelines-for-angular-and.html[recommended people call it "Angular" instead of Angular 2.0]. -Angular 2.0 was released September 2016. Angular 4.0 was released March 2017. https://www.jhipster.tech/2017/07/06/jhipster-release-4.6.0.html[JHipster 4.6.0] was released July 6, 2017 and was the first release to contain production-ready Angular support. JHipster 5 uses Angular 6. Angular https://www.infoq.com/news/2018/11/angular-7[released version 7] during the production of this book. +Angular 2.0 was released September 2016. Angular 4.0 was released March 2017. JHipster 4.6.0 was released July 6, 2017 and was the first release to contain production-ready Angular support. JHipster 5 uses Angular 6. Angular released version 7 during the production of this book. -You can find the Angular project at https://angular.io/[https://angular.io]. +You can find the Angular project at https://angular.io. === Basics Creating a component that says "Hello World" with Angular is pretty simple. @@ -228,7 +224,7 @@ In the main entry point of the app, `AppComponent` in this case, you'll need to The template for the `SearchComponent` can be as simple as a form with a button. -[source,html] +[source%autofit,html] ----

Search

@@ -482,12 +478,13 @@ The media queries effect screen widths with the given breakpoint or _larger_. Fo The following example from 21-Points Health shows how to display a shorter heading on mobile and a larger one on bigger screens. -[source,html] +[source%autofit,html] ----

Blood Pressure:

-

BP:

+

BP:

---- @@ -495,7 +492,7 @@ The following example from 21-Points Health shows how to display a shorter headi When you add Bootstrap's CSS to your web application, chances are it'll quickly start to look better. Typography, margins, and padding will look better by default. However, your forms might look funny, because Bootstrap requires a few classes on your form elements to make them look good. Below is an example of a form element. -[source,html] +[source%autofit,html] ---- include::{sourcedir}/chapter3/bootstrap/basicelement.html[] ---- @@ -506,7 +503,7 @@ image::chapter3/bootstrap/basicelement.png[Basic form element, 712, scaledwidth= If you'd like to indicate that this form element is not valid, you'll need to modify the above HTML to display validation warnings. -[source,html] +[source%autofit,html] ---- include::{sourcedir}/chapter3/bootstrap/basicelement-withvalidation.html[] ---- @@ -548,7 +545,7 @@ image::chapter3/bootstrap/navbar-on-mobile.png[Navbar on mobile, 476, scaledwidt This navbar requires quite a bit of HTML markup, not shown here for the sake of brevity. You can view this source online in link:https://getbootstrap.com/docs/4.1/components/navbar/[Bootstrap's documentation]. A simpler example below shows the basic structure. -[source,html] +[source%autofit,html] ---- include::{sourcedir}/chapter3/bootstrap/navbar.html[] ---- @@ -568,7 +565,7 @@ image::chapter3/bootstrap/alerts.png[Alerts, 776, scaledwidth=100%] To make an alert closeable, you need to add an `.alert-dismissible` class and a close button. -[source,html] +[source%autofit,html] ----