dev:angular_dev_best_practices
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
dev:angular_dev_best_practices [2019/01/18 11:32] – erickson | dev:angular_dev_best_practices [2024/09/15 13:03] (current) – [Running ng lint] add info about prerequisites sandbergja | ||
---|---|---|---|
Line 4: | Line 4: | ||
Loose collection of practices to review with developers so we can agree on UI developer guidelines. | Loose collection of practices to review with developers so we can agree on UI developer guidelines. | ||
+ | ==== Code quality ==== | ||
- | * Run 'ng build --prod' | + | * Run %%'ng build --prod' |
* This ensures the templates also compile successfully. | * This ensures the templates also compile successfully. | ||
- | * Run 'ng lint' before committing. | + | * Run 'ng lint' before committing, see details below. |
- | * This does more than check style, it also warns when an import pulls in too much code, among other things. | + | * Make sure that 'ng extract-i18n' |
* use camelCase variables when possible for consistency. | * use camelCase variables when possible for consistency. | ||
+ | * Use 2-space indentation in HTML files | ||
+ | * Use 4-space indentation in Typescript and CSS files. | ||
+ | * Avoid column widths in code that extend well beyond 80-100 characters | ||
+ | |||
+ | ==== UI ==== | ||
+ | |||
* Design for screen width of 1350 pixels. | * Design for screen width of 1350 pixels. | ||
* This is somewhat arbitrary, but seems to cover most laptops and smaller (non-mobile) screens without being too limiting. | * This is somewhat arbitrary, but seems to cover most laptops and smaller (non-mobile) screens without being too limiting. | ||
* Browser dev tools can show the width of the current browser window. | * Browser dev tools can show the width of the current browser window. | ||
- | * Use 2-space indentation in HTML files | ||
- | * Use 4-space indentation in Typescript and CSS files. | ||
- | * Avoid column widths that extend well beyond 80-100 characters | ||
* Use Bootstrap utility classes when possible instead of writing custom CSS. | * Use Bootstrap utility classes when possible instead of writing custom CSS. | ||
* https:// | * https:// | ||
Line 23: | Line 27: | ||
* Give form inputs ID values with linked i18n labels | * Give form inputs ID values with linked i18n labels | ||
* <label for=" | * <label for=" | ||
- | * Beware repeatable components have unique form input IDs (extend id with incrementor, | + | * Beware repeatable components have unique form input IDs (extend id with incrementor, |
+ | * Give buttons meaningful title or aria-label attributes | ||
+ | * Give images meaningful alt attributes (alt="" | ||
+ | * Test keyboard navigation with tab, shift+tab, arrow keys, and other keys as appropriate. Make sure that all buttons, links, and other interactive elements are focusable. | ||
+ | * The [[https:// | ||
+ | * Don't add Bootstrap' | ||
+ | * Make sure that your screens have an < | ||
+ | |||
+ | ==== ng lint ==== | ||
+ | |||
+ | We use a tool called '' | ||
+ | |||
+ | === Running ng lint === | ||
+ | |||
+ | You should run ng lint early and often in the development process, as it can help you avoid certain bugs. Definitely run it before submitting your code for community review, or before committing any Angular code to the Evergreen repository. | ||
+ | |||
+ | == Preparing to run ng lint == | ||
+ | |||
+ | Ng lint does not require a running Evergreen system. | ||
+ | |||
+ | - [[newdevs: | ||
+ | - [[https:// | ||
+ | - In a new terminal, cmd, or powershell window, use the cd command to navigate to the Open-ILS/ | ||
+ | - Run the command '' | ||
+ | - Optionally, install the Angular cli globally with '' | ||
+ | |||
+ | |||
+ | == Running the ng lint command == | ||
+ | |||
+ | |||
+ | * If you have the Angular cli installed, you can run the following command from the eg2 directory: '' | ||
+ | * If you don't have the Angular cli installed, you can run the following from the eg2 directory: '' | ||
+ | * If you use VS Code, Microsoft makes a nice eslint extension that can catch problems as you type. | ||
+ | * Finally, [[https:// | ||
+ | |||
+ | === Addressing issues found by ng lint === | ||
+ | |||
+ | * '' | ||
+ | * You can tell '' | ||
+ | |||
+ | <code javascript> | ||
+ | // eslint-disable-next-line no-var | ||
+ | var myVariable = 1; | ||
+ | </ | ||
+ | |||
+ | It's a good practice to also say a bit more in this line about why we can't do the version lint would prefer, for example: | ||
+ | |||
+ | <code javascript> | ||
+ | // eslint-disable-next-line eqeqeq -- we have to use ==, rather than ===, here since result could be a string or an integer | ||
+ | if (result == ' | ||
+ | </ | ||
+ | |||
+ | == Common lint errors == | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | < | ||
+ | // This code contains 2 rxjs/ | ||
+ | const idsToDelete = [3, 12, 30]; | ||
+ | this.pcrud.search(' | ||
+ | item.deleted(true); | ||
+ | this.pcrud.autoApply(item).subscribe(deletedItem => { | ||
+ | this.pcrud.search(' | ||
+ | console.log(`We deleted an item related to call number ${callNumber.label()}`); | ||
+ | }); | ||
+ | }); | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | Note that there are three `subscribe()` calls, nested inside of each other, each of which will probably handle three events (for each of the ids we want to change). | ||
+ | |||
+ | < | ||
+ | // This code has no rxjs/ | ||
+ | const idsToDelete = [3, 12, 30]; | ||
+ | this.pcrud.search(' | ||
+ | switchMap(item => { | ||
+ | item.deleted(true); | ||
+ | return this.pcrud.autoApply(item); | ||
+ | }), | ||
+ | switchMap(deletedItem => { | ||
+ | return this.pcrud.search(' | ||
+ | }) | ||
+ | ).subscribe(callNumber => { | ||
+ | console.log(`We deleted an item related to call number ${callNumber.label()}`); | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | In this code, the distinction between the different calls and their sequence of events is a bit clearer at a glance, making for easier troubleshooting. | ||
+ | |||
+ | ==== Unit Tests ==== | ||
+ | |||
+ | * Files named *.spec.ts are automatically treated as unit test files. | ||
+ | * Unit test files should live in the same directory as the code they are testing. | ||
+ | * e.g. idl.service.ts and idl.spec.ts are in the same directory. | ||
+ | * See Open-ILS/ | ||
+ | * The highest priority for unit test implementation are shared *.service.ts files, followed by shared components, since changes to these files have the broadest impact. | ||
+ | |||
+ | {{tag> |
dev/angular_dev_best_practices.1547829168.txt.gz · Last modified: 2022/02/10 13:34 (external edit)