Moodle App Development Guide - Revision history

Devdocsbot: Update migration status and path

2022-07-14T13:03:38Z

Update migration status and path

← Older revision		Revision as of 13:03, 14 July 2022
Line 1:		Line 1:
	{{Template:Migrated\|newDocId=/~~docs~~/~~moodleapp~~/development/development-guide}}		{{Template:Migrated\|newDocId=/general/app/development/development-guide}}
	{{Moodle App (Ionic 5)}}		{{Moodle App (Ionic 5)}}
	This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.		This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.

Devdocsbot: Protected "Moodle App Development Guide": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-05-06T07:27:09Z

Protected "Moodle App Development Guide": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 07:27, 6 May 2022
(No difference)

Devdocsbot: Update migration status and path

2022-05-03T14:40:59Z

Update migration status and path

← Older revision		Revision as of 14:40, 3 May 2022
Line 1:		Line 1:
	{{Template:Migrated\|newDocId=/docs~~/guides~~/moodleapp/development/development-guide}}		{{Template:Migrated\|newDocId=/docs/moodleapp/development/development-guide}}
	{{Moodle App (Ionic 5)}}		{{Moodle App (Ionic 5)}}
	This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.		This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.

Devdocsbot: Update migration status and path

2022-05-03T13:46:47Z

Update migration status and path

← Older revision		Revision as of 13:46, 3 May 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/guides/moodleapp/development/development-guide}}
	{{Moodle App (Ionic 5)}}		{{Moodle App (Ionic 5)}}
	This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.		This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.

Dpalou: /* Acceptance */

2022-03-15T08:55:05Z

Acceptance

Show changes

Noeldemartin: Document utils folders

2022-02-17T14:27:23Z

Document utils folders

← Older revision		Revision as of 14:27, 17 February 2022
Line 151:		Line 151:
	==== core/classes/ ====		==== core/classes/ ====

	This folder contains classes that don’t fit into any other part of the application. We must be careful not to bloat this folder and turn it into a mess.		This folder contains classes that don’t fit into any other part of the application. We must be careful not to bloat this folder and turn it into a mess. There can be subfolders to group files with related functionality.

	Think twice before adding anything here.		Think twice before adding anything here.

			==== core/utils/ ====

			Same as [[#core.2Fclasses.2F\|core/classes/]], but containing functional utilities instead of classes.

	==== core/singletons/ ====		==== core/singletons/ ====
Line 181:		Line 185:
	* <code>{feature-name}.scss</code> — Reusable styles for components defined in this module.		* <code>{feature-name}.scss</code> — Reusable styles for components defined in this module.
	* <code>classes/</code> — Same as [[#core.2Fclasses.2F\|core/classes/]].		* <code>classes/</code> — Same as [[#core.2Fclasses.2F\|core/classes/]].
			* <code>utils/</code> — Same as [[#core.2Futils.2F\|core/utils/]].
	* <code>components/</code> — Same as [[#core.2Fcomponents.2F\|core/components/]] (with the ''core-{feature-name}-'' namespace).		* <code>components/</code> — Same as [[#core.2Fcomponents.2F\|core/components/]] (with the ''core-{feature-name}-'' namespace).
	* <code>directives/</code> and <code>pipes/</code> — Same as [[#core.2Fdirectives.2F\|core/directives/]] and [[#core.2Fpipes.2F\|core/pipes/]].		* <code>directives/</code> and <code>pipes/</code> — Same as [[#core.2Fdirectives.2F\|core/directives/]] and [[#core.2Fpipes.2F\|core/pipes/]].

Noeldemartin: Use British English

2021-09-20T08:03:39Z

Use British English

Noeldemartin: Update categories

2021-09-15T13:12:52Z

Update categories

← Older revision		Revision as of 13:12, 15 September 2021
Line 1:		Line 1:
			{{Moodle App (Ionic 5)}}

	This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.		This document contains information that developers should know before starting to code on the Mobile App. If you are only interested in developing a site plugin, you should read [[Mobile support for plugins\|the Moodle App Plugins Development Guide]] instead.

Line 405:		Line 407:
	* [[Moodle App Deep Linking]]		* [[Moodle App Deep Linking]]
	* [[Translating the Moodle App]]		* [[Translating the Moodle App]]

			[[Category: Mobile]]
			[[Category: Moodle App Ionic 5]]

Noeldemartin: Update npx gulp behat configuration

2021-09-09T15:23:41Z

Update npx gulp behat configuration

← Older revision		Revision as of 15:23, 9 September 2021
Line 393:		Line 393:
	If you are using [https://github.com/moodlehq/moodle-docker moodle-docker], you can configure it to [https://github.com/moodlehq/moodle-docker#use-containers-for-running-behat-tests-for-the-mobile-app run the tests from your local copy of the application]. Keep in mind that doing this will run the app on a docker image, and expose the dev server to your machine. So you shouldn’t be running <code>npm start</code> or any other commands launching a dev server while docker is running, or you’ll have two instances running and that can cause some problems.		If you are using [https://github.com/moodlehq/moodle-docker moodle-docker], you can configure it to [https://github.com/moodlehq/moodle-docker#use-containers-for-running-behat-tests-for-the-mobile-app run the tests from your local copy of the application]. Keep in mind that doing this will run the app on a docker image, and expose the dev server to your machine. So you shouldn’t be running <code>npm start</code> or any other commands launching a dev server while docker is running, or you’ll have two instances running and that can cause some problems.

	In order to run your Behat tests, they need to be installed in the Moodle site. You can automate this process by running the <code>npx gulp behat</code> command, which will create a local plugin containing your application tests ~~(this~~ uses the environment variables from moodle-docker, ~~so make sure to~~ configure ~~them before running~~ the ~~command)~~. If you want to keep them up to date every time you change the test files, you can run <code>npx gulp watch-behat</code>.		In order to run your Behat tests, they need to be installed in the Moodle site. You can automate this process by running the <code>npx gulp behat</code> command, which will create a local plugin containing your application tests. This uses the environment variables from moodle-docker, if you're not using it you can also configure this by setting the <code>MOODLE_APP_BEHAT_PLUGIN_PATH</code> variable. If you want to keep them up to date every time you change the test files, you can run <code>npx gulp watch-behat</code> (this is already done when developing locally, but if you're serving the app with moodle-docker you'll need to run this from your local machine).

	You can write standard Behat tests for the most part, but there are some steps specific for the Moodle App that you should use instead of the ones for the Moodle LMS.		You can write standard Behat tests for the most part, but there are some steps specific for the Moodle App that you should use instead of the ones for the Moodle LMS.

Noeldemartin: Fix lists spacing

2021-09-07T07:55:08Z

Fix lists spacing

← Older revision		Revision as of 07:55, 7 September 2021
Line 126:		Line 126:
	* <code>{namespace}-{component-name}.html</code> — Component template.		* <code>{namespace}-{component-name}.html</code> — Component template.
	* <code>{component-name}.scss</code> — Component-scoped styles.		* <code>{component-name}.scss</code> — Component-scoped styles.


	Additionally, auxiliary components that are only used locally can be defined in the same folder, starting with the name of their parent component. For example, looking at the <code>core-recaptcha</code> component we can find the following files:		Additionally, auxiliary components that are only used locally can be defined in the same folder, starting with the name of their parent component. For example, looking at the <code>core-recaptcha</code> component we can find the following files:
Line 183:		Line 184:
	* <code>services/</code> — Same as [[#core.2Fservices.2F\|core/services/]].		* <code>services/</code> — Same as [[#core.2Fservices.2F\|core/services/]].
	* <code>pages/</code> — Page folders have the same structure as [[#core.2Fcomponents.2F\|core/components/]], but in addition they often declare modules as well to allow lazy-loading the page. In some cases, they can even have their own routing modules. For example, look at <code>core/features/mainmenu/pages/home/home-routing.module.ts</code>.		* <code>pages/</code> — Page folders have the same structure as [[#core.2Fcomponents.2F\|core/components/]], but in addition they often declare modules as well to allow lazy-loading the page. In some cases, they can even have their own routing modules. For example, look at <code>core/features/mainmenu/pages/home/home-routing.module.ts</code>.


	In order to distinguish code from each feature, classes will be prefixed with the feature name. For example, the home page component declared in <code>core/features/mainmenu/pages/home/home.ts</code> is called <code>CoreMainMenuHomePage</code>.		In order to distinguish code from each feature, classes will be prefixed with the feature name. For example, the home page component declared in <code>core/features/mainmenu/pages/home/home.ts</code> is called <code>CoreMainMenuHomePage</code>.
Line 253:		Line 255:
	* The init login page declared in <code>core/features/login/pages/init/init.ts</code> is tested in <code>core/features/login/tests/pages/init.test.ts</code>. The test file can be directly under <code>pages/</code> (instead of <code>pages/init/</code>) because the page component is the only file that will be tested for this folder. So it would be unnecessary to have a folder with a single file.		* The init login page declared in <code>core/features/login/pages/init/init.ts</code> is tested in <code>core/features/login/tests/pages/init.test.ts</code>. The test file can be directly under <code>pages/</code> (instead of <code>pages/init/</code>) because the page component is the only file that will be tested for this folder. So it would be unnecessary to have a folder with a single file.
	* The root app component declared in <code>app/app.component.ts</code> is tested in <code>app/app.component.test.ts</code>. The test file can live alongside the component because this module doesn’t have any nested folders.		* The root app component declared in <code>app/app.component.ts</code> is tested in <code>app/app.component.test.ts</code>. The test file can live alongside the component because this module doesn’t have any nested folders.


	In addition to unit test files, there is also a folder at <code>testing/</code> with setup and file utilities shared among all tests.		In addition to unit test files, there is also a folder at <code>testing/</code> with setup and file utilities shared among all tests.

← Older revision		Revision as of 08:03, 20 September 2021
Line 66:		Line 66:
	== Folders structure ==		== Folders structure ==

	In this section, we’ll see how files and folders are ~~organized~~ within the <code>src/</code> folder.		In this section, we’ll see how files and folders are organised within the <code>src/</code> folder.

	=== index.html ===		=== index.html ===
Line 93:		Line 93:
	This folder contains the basic functionality of the application, and exposes pluginable interfaces for other parts to hook into. Anything defined here can be imported anywhere since it's critical for the app and it is available everywhere (in contrast to code within [[#addons.2F\|addons/]]). In order to identify code from this folder, all classes start with the <code>Core</code> prefix.		This folder contains the basic functionality of the application, and exposes pluginable interfaces for other parts to hook into. Anything defined here can be imported anywhere since it's critical for the app and it is available everywhere (in contrast to code within [[#addons.2F\|addons/]]). In order to identify code from this folder, all classes start with the <code>Core</code> prefix.

	The <code>core.module.ts</code> file defines a module that imports all the core providers and modules. It encapsulates the ~~initialization~~ of the application core.		The <code>core.module.ts</code> file defines a module that imports all the core providers and modules. It encapsulates the initialisation of the application core.

	The <code>shared.module.ts</code> file defines a [https://angular.io/guide/module-types#shared-ngmodules Shared Module] that exposes core declarables (components, directives and pipes). When other modules use any of these, it’s preferable to import this module instead of individual declarable modules separately.		The <code>shared.module.ts</code> file defines a [https://angular.io/guide/module-types#shared-ngmodules Shared Module] that exposes core declarables (components, directives and pipes). When other modules use any of these, it’s preferable to import this module instead of individual declarable modules separately.
Line 101:		Line 101:
	==== core/initializers/ ====		==== core/initializers/ ====

	This folder contains a collection of scripts that are run within the [https://angular.io/api/core/APP_INITIALIZER Angular ~~initialization~~ process].		This folder contains a collection of scripts that are run within the [https://angular.io/api/core/APP_INITIALIZER Angular initialisation process].

	These files are automatically loaded using webpack, so it isn’t necessary to import them anywhere. You can see how they are loaded in <code>src/core/initializers/index.ts</code>.		These files are automatically loaded using webpack, so it isn’t necessary to import them anywhere. You can see how they are loaded in <code>src/core/initializers/index.ts</code>.

	Keep in mind that any code placed here will delay the [[#Application_lifecycle\|application startup]], so it’s critical that only the essential processes are included here. If something can be ~~initialized~~ lazily, it should.		Keep in mind that any code placed here will delay the [[#Application_lifecycle\|application startup]], so it’s critical that only the essential processes are included here. If something can be initialised lazily, it should.

	==== core/services/ ====		==== core/services/ ====
Line 113:		Line 113:
	Most of them are [https://angular.io/guide/singleton-services Singleton Services], and they can be accessed statically using their corresponding [[#Service_singleton\|Service Singleton]].		Most of them are [https://angular.io/guide/singleton-services Singleton Services], and they can be accessed statically using their corresponding [[#Service_singleton\|Service Singleton]].

	Given that services are created on demand, none of them is guaranteed to be ~~initialized~~ when the application is ready. So anything that’s essential for the application to run should be placed in an [[#core.2Finitializers.2F\|initializer]] instead. In case that the ~~initialization~~ relies on a service, it can be accessed using its Service Singleton. One good example of this is the database ~~initialization~~, which is placed on an initializer but calls each service’s <code>initializeDatabase</code> method.		Given that services are created on demand, none of them is guaranteed to be initialised when the application is ready. So anything that’s essential for the application to run should be placed in an [[#core.2Finitializers.2F\|initializer]] instead. In case that the initialisation relies on a service, it can be accessed using its Service Singleton. One good example of this is the database initialisation, which is placed on an initializer but calls each service’s <code>initializeDatabase</code> method.

	And of course, service dependencies can be declared in the constructor to use Angular’s built-in dependency management.		And of course, service dependencies can be declared in the constructor to use Angular’s built-in dependency management.
Line 222:		Line 222:
	** <code>globals.custom.scss</code> — Global custom scss variables.		** <code>globals.custom.scss</code> — Global custom scss variables.
	** <code>globals.variables.scss</code> — Global scss variables.		** <code>globals.variables.scss</code> — Global scss variables.
	** <code>globals.mixins.scss</code> — App ~~customized~~ mixins.		** <code>globals.mixins.scss</code> — App customised mixins.
	** <code>globals.mixins.ionic.scss</code> — Imported mixins from ionic.		** <code>globals.mixins.ionic.scss</code> — Imported mixins from ionic.
	* <code>format-text.scss</code> — Contains format-text tag styles.		* <code>format-text.scss</code> — Contains format-text tag styles.
Line 334:		Line 334:
	</syntaxhighlight>		</syntaxhighlight>

	This method will create a proxy that will relay all the method calls to the service singleton instance. This proxy can be used like you would use an injected instance of the service. When any method is called, the underlying service will be ~~initialized~~ lazily. If you need to access the actual instance, you can do it via the <code>instance</code> property.		This method will create a proxy that will relay all the method calls to the service singleton instance. This proxy can be used like you would use an injected instance of the service. When any method is called, the underlying service will be initialised lazily. If you need to access the actual instance, you can do it via the <code>instance</code> property.

	Since they are normal Angular services under the hood, they can be overridden in other modules. But keep in mind that because they are singletons, they will be replaced everywhere and not just in the module where they are being defined.		Since they are normal Angular services under the hood, they can be overridden in other modules. But keep in mind that because they are singletons, they will be replaced everywhere and not just in the module where they are being defined.
Line 353:		Line 353:
	</syntaxhighlight>		</syntaxhighlight>

	This pattern can be used mostly everywhere, because the underlying system is ~~initialized~~ before the app ~~initialization~~ begins.		This pattern can be used mostly everywhere, because the underlying system is initialised before the app initialisation begins.

	The exception to this rule is within service constructors, given that we don’t have absolute control over when Angular will create service instances. For this same reason, code intended to run on application startup must be placed on an [[#core.2Finitializers.2F\|initializer]]. And anything else within a service should be ~~initialized~~ lazily, instead of using the constructor (a general good practice in programming is that constructors shouldn’t have side-effects).		The exception to this rule is within service constructors, given that we don’t have absolute control over when Angular will create service instances. For this same reason, code intended to run on application startup must be placed on an [[#core.2Finitializers.2F\|initializer]]. And anything else within a service should be initialised lazily, instead of using the constructor (a general good practice in programming is that constructors shouldn’t have side-effects).

	In the rare cases where a constructor really needs a dependency, it’s always possible to fall back to Angular’s built-in pattern of declaring dependencies in the constructor.		In the rare cases where a constructor really needs a dependency, it’s always possible to fall back to Angular’s built-in pattern of declaring dependencies in the constructor.
Line 369:		Line 369:
	When the application is launched, the contents of [[#index.html\|index.html]] are rendered on screen. This file is intentionally concise because all the flare is added by Javascript, and the splash screen will be covering the application UI until it has fully started. If you are developing in the browser, this will be a blank screen for you given that the splash screen is not available on the web. We are not targeting browsers in production, so it’s acceptable to have this behaviour during development.		When the application is launched, the contents of [[#index.html\|index.html]] are rendered on screen. This file is intentionally concise because all the flare is added by Javascript, and the splash screen will be covering the application UI until it has fully started. If you are developing in the browser, this will be a blank screen for you given that the splash screen is not available on the web. We are not targeting browsers in production, so it’s acceptable to have this behaviour during development.

	Before the UI is rendered, the startup process will take place. First, Angular will instantiate <code>AppModule</code> and all the imported modules (features, addons, etc.), and then it will execute the initializers (this includes all the initializers, not only the ones declared under [[#core.2Finitializers.2F\|core/initializers/]]). In our application, we have overriden [https://angular.io/api/core/ApplicationInitStatus Angular’s ~~initialization~~ service] to get a hold of the root injector so that we can safely use the [[#Service_singletons\|Service Singletons]] pattern within initializers. However, we should avoid this pattern within constructors, because those can be called during the instantiation phase.		Before the UI is rendered, the startup process will take place. First, Angular will instantiate <code>AppModule</code> and all the imported modules (features, addons, etc.), and then it will execute the initializers (this includes all the initializers, not only the ones declared under [[#core.2Finitializers.2F\|core/initializers/]]). In our application, we have overriden [https://angular.io/api/core/ApplicationInitStatus Angular’s initialisation service] to get a hold of the root injector so that we can safely use the [[#Service_singletons\|Service Singletons]] pattern within initializers. However, we should avoid this pattern within constructors, because those can be called during the instantiation phase.

	Once the application has finished starting up, the router will resolve the active route and the corresponding page component will be rendered. At this point, the splash screen will be hidden and the app is interactive.		Once the application has finished starting up, the router will resolve the active route and the corresponding page component will be rendered. At this point, the splash screen will be hidden and the app is interactive.