Tutorial revisions #321
Tutorial revisions #321
Conversation
EHandtkeBasis
requested review from
hyyan,
MatthewHawkins,
nmlynx and
mschned
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| 3) Open your browser and navigate to http://localhost:8080 to view the app. | ||
|
|
||
| Repeat this process for each step as you follow along with the tutorial, allowing you to explore the app’s features as they are added. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Contractions] Use 'they're' instead of 'they are'.
| context.onValidate(e -> submit.setEnabled(e.isValid())); | ||
| ``` | ||
|
|
||
| `e.isValid()` returns true if all fields are valid, and false if not. This means that the `Submit` button is enabled as long as all fields are valid; otherwise, it remains turned off, preventing submission until corrections are made. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Semicolons] Use semicolons judiciously.
|
|
||
| Calling `context.write(customer)` will return an instance of a `ValidationResult`. This class indicates whether or not the validation was successful, and stores any messages associated with this result. | ||
|
|
||
| In this code we check to see if this result was valid before adding a customer. This ensures that all changes are validated and automatically applied to the model before being processed. |
There was a problem hiding this comment.
[Google.We] Try to avoid using first-person plural like 'we'.
| webforj.entry = com.webforj.demos.DemoApplication | ||
| ``` | ||
|
|
||
| #### Debug Mode `(webforj.debug)` |
There was a problem hiding this comment.
[Google.Headings] 'Debug Mode ***************' should use sentence-style capitalization.
|
|
||
| ### Server and client side components | ||
|
|
||
| Each of these [server-side component](../../components/overview) created in webforJ has a corresponding [client-side web component](../../client-components/overview). These client-side components are web components, implemented by webforJ's design system called DWC. When viewing information about the various components available in the webforJ documentation, each page will like the relevant information needed to style the client components. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'DWC', if it's unfamiliar to the audience.
| Specify the directory from which static files should be served. Use the `<webApp>` in the `pom.xml` configuration to point to your static directory. | ||
| ::: | ||
|
|
||
| The following code would import a stylesheet found in the following directory structure: |
There was a problem hiding this comment.
[Google.WordList] Use 'style sheet' instead of 'stylesheet'.
| ``` | ||
|
|
||
| ### `@StyleSheet` | ||
| Use the `@StyleSheet` annotation to include CSS files hosted at external URLs. This is useful for integrating third-party stylesheets. When referencing external URLs, the framework fetches and applies the stylesheet directly from the specified URL. Make sure the resource is accessible and uses the correct protocol (http or https). |
There was a problem hiding this comment.
[Google.WordList] Use 'style sheet' instead of 'stylesheet'.
| ``` | ||
|
|
||
| ### `@StyleSheet` | ||
| Use the `@StyleSheet` annotation to include CSS files hosted at external URLs. This is useful for integrating third-party stylesheets. When referencing external URLs, the framework fetches and applies the stylesheet directly from the specified URL. Make sure the resource is accessible and uses the correct protocol (http or https). |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.
|
|
||
| The app created in the [previous step](./working-with-data) will have a robust routing setup that supports multiple views, enabling users to manage customer data more effectively while maintaining a clean and scalable codebase. | ||
|
|
||
| <img src={require('@site/static/img/tutorial_images/step3-1.png').default} alt="Screenshot of first app" className="tutorial-image" /> |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.
|
|
||
| <img src={require('@site/static/img/tutorial_images/step3-1.png').default} alt="Screenshot of first app" className="tutorial-image" /> | ||
|
|
||
| <img src={require('@site/static/img/tutorial_images/step3-2.png').default} alt="Screenshot of first app" className="tutorial-image" /> |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.
| ``` | ||
|
|
||
| ### `@StyleSheet` | ||
| Use the `@StyleSheet` annotation to include CSS files hosted at external URLs. This is useful for integrating third-party stylesheets. When referencing external URLs, the framework fetches and applies the style sheet directly from the specified URL. Make sure the resource is accessible and uses the correct protocol (http or https). |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.
|
/rebase |
There was a problem hiding this comment.
@MatthewHawkins, please take care of the requested changes yourself.
|
|
||
| - Working with data in a table. | ||
| - Using the [`ObjectTable`](https://javadoc.io/doc/com.webforj/webforj-foundation/latest/com/webforj/environment/ObjectTable.html) and asset management. | ||
| - Routing and navigation |
| - Working with data in a table. | ||
| - Using the [`ObjectTable`](https://javadoc.io/doc/com.webforj/webforj-foundation/latest/com/webforj/environment/ObjectTable.html) and asset management. | ||
| - Routing and navigation | ||
| - [Data Bindings](../../data-binding/overview) and validation |
| - A Java IDE | ||
| - A web browser | ||
| <!-- vale off --> | ||
| - Git (recommended but not required) |
| - Routing and navigation | ||
| - [Data Bindings](../../data-binding/overview) and validation | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Link to webforJ (maybe as a tip) Prerequisites
| `BindingContext.of(this, Customer.class, true)` initializes the binding context for the `Customer` class. The third parameter, `true`, enables [jakarta validation](https://beanvalidation.org/). | ||
|
|
||
| :::info | ||
| This implementation uses autobinding as described in the [Data Binding Article](../../data-binding/automatic-binding). This works if the fields in the data model `Customer` are named the same as the corresponding fields in the `FormView`. |
There was a problem hiding this comment.
change "autobinding" to "auto-binding"
| :::info | ||
| This implementation uses autobinding as described in the [Data Binding Article](../../data-binding/automatic-binding). This works if the fields in the data model `Customer` are named the same as the corresponding fields in the `FormView`. | ||
|
|
||
| Should the fields not be named the same you can add the `UseProperty` annotation in the form over the field you want to bind so they know which datafields to refer to. |
|
|
||
| Validation ensures that the data entered into the form adheres to specified rules, improving data quality and preventing invalid submissions. With data binding, validation no longer needs to be manually implemented but instead simply configured, allowing real-time feedback on user inputs. | ||
|
|
||
| ### Defining valdiation rules |
| private void submitCustomer() { | ||
| ValidationResult results = context.write(customer); | ||
| if (results.isValid()) { | ||
| if (customerId.isEmpty()) { | ||
| Service.getCurrent().addCustomer(customer); | ||
| } | ||
| Router.getCurrent().navigate(DemoView.class); | ||
| } | ||
| } |
| @@ -0,0 +1,69 @@ | |||
| --- | |||
| title: Integrating the AppLayout | |||
|
@MatthewHawkins please make sure this PR is rebased |
… step two and three.
MatthewHawkins
force-pushed
the
tutorial-revisions
branch
from
e93793f to
e140393
Compare
| title: Working With Data | ||
| sidebar_position: 3 | ||
| --- | ||
| import Tabs from '@theme/Tabs'; |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Semicolons] Use semicolons judiciously.
| sidebar_position: 3 | ||
| --- | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Semicolons] Use semicolons judiciously.
|
|
||
| Implementing the `HasEntityKey` interface is crucial for managing unique identifiers in models used with a `Table`. It ensures that each instance of the model has a unique key, allowing the `Table` to identify and manage rows effectively. | ||
|
|
||
| For this demo, the `getEntityKey()` method returns a UUID for each customer, ensuring unique identification. While UUIDs are used here for simplicity, in real-world applications, a database primary key is often a better choice for generating unique keys. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'UUID', if it's unfamiliar to the audience.
|
|
||
| For more information on data binding reference [this article.](../../data-binding/overview) | ||
|
|
||
| <img src={require('@site/static/img/tutorial_images/step4.png').default} alt="Screenshot of first app" className="tutorial-image" /> |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.
|
|
||
| Once routing has been enabled, create separate Java files for each view, the app will contain. In this case, `DemoView.java` and `FormView.java`. Assign unique routes to these views using the `@Route` annotation. This ensures that each view is accessible through a specific URL. | ||
|
|
||
| When the `@Route` annotation is left blank above a class with one of these suffixes, webforJ automatically assigns the class's name without the suffix as the route. For example, `DemoView` would use the route `/demo` by default. Since in this case `DemoView` is supposed to be the default route tho you will assign it a route. |
There was a problem hiding this comment.
[Google.WordList] Use 'preceding' instead of 'above'.
|
|
||
| ### Submitting data | ||
|
|
||
| When you are done editing the data, it is necessary to submit it to the service handling the repository. Therefore the |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Contractions] Use 'it's' instead of 'it is'.
|
|
||
| ### Server and client side components | ||
|
|
||
| Each server-side component in webforJ has a matching client-side web component implemented by the DWC design system. Server-side components handle logic and backend interactions, while client-side components like `dwc-button` and `dwc-dialog` manage frontend rendering and styling. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'DWC', if it's unfamiliar to the audience.
|
|
||
| This tutorial is designed to guide you step by step through the process of creating the app. This app, designed to manage customer information, demonstrates how to use webforJ to build a functional and user-friendly interface with features for viewing, adding, and editing customer data. Each section will build upon the last, but feel free to skip ahead as needed. | ||
|
|
||
| Each step in the tutorial will result in a program that compiles into a WAR file, which can be deployed to any Java web app server. For this tutorial, the Maven Jetty plugin will be used to deploy the app locally. This lightweight setup ensures the app can quickly run, and that changes will be seen in real time during development. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'WAR', if it's unfamiliar to the audience.
| <!-- vale on --> | ||
|
|
||
| :::tip webforJ Prerequisites | ||
| See [this article](../prerequisites) for a more detailed overview of required tools outlined above. |
There was a problem hiding this comment.
[Google.WordList] Use 'preceding' instead of 'above'.
|
|
||
| Once routing has been enabled, separate Java files for each view the app will contain are created, in this case, `DemoView.java` and `FormView.java`. Unique routes are assigned to these views using the `@Route` annotation. This ensures that each view is accessible through a specific URL. | ||
|
|
||
| When the `@Route` annotation has no value above a class with one of these suffixes, webforJ automatically assigns the class's name without the suffix as the route. For example, `DemoView` will map the route `/demo` by default. Since in this case `DemoView` is supposed to be the default route tho you will assign it a route. |
There was a problem hiding this comment.
[Google.WordList] Use 'preceding' instead of 'above'.
No description provided.