Merge pull request #45 from crazyserver/app-docs

Update coding guides for 5.1

Author: dpalou

general/app/upgrading/plugins-upgrade-guide.md

@@ -18,6 +18,20 @@ Depending on which version of the app you're upgrading from, you'll need to go t
 
 Other than the changes outlined in this document, there may be smaller API changes that aren't highlighted here. Make sure to check the [UPGRADE.md](https://github.com/moodlehq/moodleapp/blob/latest/UPGRADE.md) file for an exhaustive list with all the changes.
 
+## 5.0 to 5.1
+
+In this version, the app has undergone a major framework modernization. The most significant change is the upgrade of **Angular from v17 to v20**.
+
+### Angular 20 Upgrade
+
+This is a major jump that aligns the app with the latest web standards and performance improvements. While Angular 20 maintains backward compatibility for many patterns, there is a key area you should review in your site plugins:
+
+**[New Control Flow Syntax](https://v20.angular.dev/guide/templates/control-flow):** Angular 20 stabilizes the modern control flow syntax. We recommend replacing structural directives like `*ngIf`, `*ngFor`, and `[ngSwitch]` with the new `@if`, `@for`, and `@switch` blocks. We strongly recommend migrating to this new syntax as it offers better performance, improved type safety, and is the current standard for Angular development, while the old directives have been deprecated. This new control flow can be used since Moodle app 4.4.
+
+Make sure to test your plugin thoroughly, especially any custom templates that might be affected by in newer Angular versions. Refer to the official Angular upgrade guide for a detailed list of breaking changes between v17 and v20.
+
+**Note for developers:** Please remember to check the [UPGRADE.md](https://github.com/moodlehq/moodleapp/blob/latest/UPGRADE.md) file regularly for any deprecated methods or classes within the Moodle App API to ensure your plugin remains compatible with future releases.
+
 ## 4.4 to 4.5
 
 The Ionic version has been upgraded to v8 (from v7), make sure to check the relevant upgrade guides for [v8](https://ionicframework.com/docs/updating/8-0). In particular, the legacy syntax to declare input labels that was deprecated on Ionic7 now has been removed.

general/development/policies/codingstyle-moodleapp.md

@@ -601,37 +601,9 @@ There is a maximum line length of 140 characters for templates. Whenever that le
 If you are using VSCode, this should be done automatically on every save with the [configuration that ships with the app](https://github.com/moodlehq/moodleapp/blob/latest/.vscode/settings.json#L8).
 :::
 
-### Avoid default exports
-
-Using default exports should be avoided for Angular applications because they [cause issues with AOT compiler](https://stackoverflow.com/questions/45962317/why-isnt-export-default-recommended-in-angular). Technically only components have this problem, but in order to avoid the mental load of thinking about this every time, we disallow it altogether.
-
-<ValidExample title="Good">
-
-```ts
-@Component({
-    selector: 'my-component',
-    templateUrl: 'my-component.html',
-})
-export class MyComponent {}
-```
-
-</ValidExample>
-
-<InvalidExample title="Bad">
-
-```ts
-@Component({
-    selector: 'my-component',
-    templateUrl: 'my-component.html',
-})
-export default class MyComponent {}
-```
-
-</InvalidExample>
-
 ### Declaring page modules
 
-When creating a page component, it should be declared in the feature's [lazy modules](../../../general/app/development/development-guide.md#routing). Exceptionally, pages that are used by more than one module can create a page module; but this module should only declare components, it shouldn't include any routing functionality.
+When creating a page component, it should be declared as a standalone component and exported as default class so it can be easily [lazy loaded](../../../general/app/development/development-guide.md#routing).
 
 <ValidExample title="Good">
 
@@ -640,66 +612,33 @@ When creating a page component, it should be declared in the feature's [lazy mod
 @Component({
     selector: 'page-core-feature-index',
     templateUrl: 'index.html',
+    imports: [
+        CoreSharedModule,
+    ],
 })
-export class CoreFeatureIndexPageComponent {}
+export default class CoreFeatureIndexPageComponent {}
 ```
 
 ```ts
-// file: core/features/feature/feature-lazy.module.ts
+// file: core/features/feature/feature.module.ts
 const routes: Routes = [
     {
         path: 'feature',
-        component: CoreFeatureIndexPageComponent,
+        loadComponent: () => import('./pages/index/index'),
     },
 ];
-
-@NgModule({
-    imports: [
-        RouterModule.forChild(routes),
-        CoreSharedModule,
-    ],
-    declarations: [
-        CoreFeatureIndexPageComponent,
-    ],
-})
-export class CoreFeatureLazyModule {}
 ```
 
 </ValidExample>
 
-<CodeExample type="warning" title="Allowed only if the page is used in multiple modules">
-
-```ts
-// file: core/features/feature/pages/index/index.page.ts
-@Component({
-    selector: 'page-core-feature-index',
-    templateUrl: 'index.html',
-})
-export class CoreFeatureIndexPageComponent {}
-```
-
-```ts
-// file: core/features/feature/pages/index/index.module.ts
-@NgModule({
-    imports: [
-        CoreSharedModule,
-    ],
-    declarations: [
-        CoreFeatureIndexPageComponent,
-    ],
-})
-export class CoreFeatureIndexPageModule {}
-```
-
-</CodeExample>
-
 <InvalidExample title="Bad">
 
 ```ts
 // file: core/features/feature/pages/index/index.page.ts
 @Component({
     selector: 'page-core-feature-index',
     templateUrl: 'index.html',
+    standalone: false,
 })
 export class CoreFeatureIndexPageComponent {}
 ```