Merge branch 'main' into pr-43430

Author: HLeithner

docs/building-extensions/components/component-examples/_assets/component-example-ajax.png

@@ -5,17 +5,15 @@ title: Ajax demo component
 Ajaxdemo Component
 ==================
 
-This is an example component which you can download from [com_ajaxdemo](https://github.com/joomla/manual-examples/tree/main/component-ajaxdemo).
+This example component demonstrates the use of Ajax to interact with the server without requiring a page load. For further background see the General Concepts section on [Ajax and JsonResponse](../../../general-concepts/javascript/ajax.md).
 
-It demonstrates the use of Ajax within a Joomla component; 
-for further background see the section [Ajax and JsonResponse](../../../general-concepts/javascript/ajax.md).
+The component can be easily adapted to demonstrate the use of [com_ajax](../../../general-concepts/javascript/com-ajax.md) for plugins and templates. Simply change `url` in media/js/divide.js to point to com_ajax instead of com_ajaxdemo and set the other required URL parameters.
 
-It can be easily adapted to demonstrate the use of [com_ajax](../../../general-concepts/javascript/com-ajax.md) for plugins and templates; 
-simply change the url in media/js/divide.js to point to com_ajax instead of com_ajaxdemo, and set the other required URL parameters.
+An installable ZIP file can be obtained via [DownGit](https://downgit.github.io/#/home?url=https://github.com/joomla/manual-examples/tree/main/component-ajaxdemo/com_ajaxdemo). After installation go to `<your domain>/index.php?option=com_ajaxdemo` to run it in your Joomla instance.
 
-Once you have downloaded the source, zip up the com_ajaxdemo directory and install the component.
+The following screenshot shows the example form with some data added:
 
-Then go to `<your domain>/index.php?option=com_ajaxdemo` to run it on your Joomla instance.
+![example form with added data](_assets/component-example-ajax.png)
 
 The component displays a form to capture two numbers A and B, and a button to calculate A/B. 
 The division is performed by an Ajax call to the server, and if B is zero then an exception is raised.

docs/building-extensions/components/component-examples/_assets/component-example-form.png

@@ -6,13 +6,7 @@ title: Example Form Component
 Example Form Component
 ======================
 
-This is an example component which you can download from [com_exampleform](https://github.com/joomla/manual-examples/tree/main/component-exampleform).
-
-Once you have downloaded the source, zip up the com_exampleform directory and install the component.
-
-Then go to `<your domain>/index.php?option=com_exampleform` to run it on your Joomla instance.
-
-It is an MVC component which demonstrates the following:
+This example MVC component demonstrates the following aspects of form manipulation:
 
 - using [Joomla Forms](../../../general-concepts/forms/how-forms-work.md) to capture data in a form
 - using several of the [standard form fields](../../../general-concepts/forms-fields/standard-fields/index.md)
@@ -21,9 +15,13 @@ It is an MVC component which demonstrates the following:
 - writing a [custom client-side validation rule](../../../general-concepts/forms/client-side-validation.md)
 - writing a [custom form filter](../../../general-concepts/forms-fields/standard-form-field-attributes.md#filter)
 
-You can easily adapt it to experiment with other standard fields, simply by including the standard field in the form XML file.
+An installable ZIP file can be obtained via [DownGit](https://downgit.github.io/#/home?url=https://github.com/joomla/manual-examples/tree/main/component-exampleform/com_exampleform). After installation go to `<your domain>/index.php?option=com_exampleform` to run it in your Joomla instance.
+
+The following screenshot shows the example form with some data added:
+
+![example form with added data](_assets/component-example-form.png)
 
-There are comments throughout the code to help you understand it, and brief summaries of the main source files are provided below.
+Brief summaries of the main source files are provided below. There are additional explanatory comments throughout the code.
 
 ## Administrator service provider
 

docs/building-extensions/components/component-examples/_assets/manual-examples-in-vscode.png

@@ -6,4 +6,29 @@ title: Example Components
 Component Examples
 ==================
 
-In this section you can find worked examples of components of various types.
+This section contains worked examples of components of various types. To obtain the examples source code to inspect or install you may clone the manual-examples repository or download an installable zip file for an individual example.
+
+## To clone the repository
+
+Navigate to a location on your development computer where you can keep multiple repositories. You might have a folder named `repos` or `git` or something else. In a terminal window use the following command:
+
+```sh
+git clone https://github.com/joomla/manual-examples.git
+```
+
+This takes no time at all and will give you a clone of the manual-examples repository that is very easy to inspect in an IDE. Here is an example screenshot of a clone open in VSCode:
+
+![screenshot of manual examples folder in vscode](_assets/manual-examples-in-vscode.png)
+
+To create an installable zip file, compress the subfolder containing the example code, such as the com_exampleform folder.
+
+## To download an installable zip
+
+1. Go to the [manual-examples repository](https://github.com/joomla/manual-examples) on GitHub.
+2. Select the example you wish to download, for example component-exampleform.
+3. Select the subfolder containing the example, com_exampleform.
+4. Copy the URL from the browser URL bar.
+5. Go to a download utility site such as [DownGit](https://downgit.github.io/#/home).
+6. Paste the URL copied in step 4 into the form.
+7. Select the Download button.
+8. Save the downloaded zip file. This can be installed in a Joomla instance or expanded to inspect with an IDE.

docs/building-extensions/components/component-examples/ajaxdemo.md

@@ -6,60 +6,69 @@ Build Extensions
 
 Joomla is a rich featured content management system, but if you're building a website with Joomla and you need extra features which aren't available by default, then you can easily extend it with extensions. There are five common types of extensions for Joomla: Components, Modules, Plugins, Templates, and Languages. There are three others: Packages, Files and Libraries. Each of these extensions handle specific functionality (many built-in features of Joomla are implemented using extensions).
 
-The difference between Joomla components, modules, plugins and templates can be initially confusing. If you're new to Joomla then you may find it useful to watch the video [How Joomla Works - a guide for extension developers](https://youtu.be/JKnq47Yhtvs), which describes how these 4 types of extension fit into the generation of a Joomla web page. Their output is also highlighted in different colours in the diagram below. 
+The difference between Joomla components, modules, plugins and templates can be initially confusing. If you're new to Joomla then you may find it useful to watch the video [How Joomla Works - a guide for extension developers](https://youtu.be/JKnq47Yhtvs), which describes how these 4 types of extension fit into the generation of a Joomla web page. Their output is also highlighted in different colours in the diagram below.
 
 ![Screenshot showing extension types](./_assets/screenshot-extension-types.jpg)
 
 ## Components
-[Components](./components/index.md) provide the central part of a web page on a Joomla site; each site web page displays the output from one component. They can be thought of as mini applications. Most components have two parts: a site part and an administrator part. For example, `com_content` is the component which handles articles; on the site front-end `com_content` displays articles to website visitors and on the back-end `com_content` provides the functionality for administrators to edit articles. 
 
-In general, components manage the data of the Joomla instance and provide functionality for creating, editing, removing and displaying the data. Often the data management aspects are handled in the administrator back-end and the site front-end simply displays the data, but this split of responsibility is not mandated, and some components provide front-end functionality for creating/editing/removing data.
+Components provide the central part of a web page on a Joomla site; each site web page displays the output from one component. They can be thought of as mini applications. Most components have two parts: a site part and an administrator part. For example, `com_content` is the component which handles articles; on the site frontend `com_content` displays articles to website visitors and on the backend `com_content` provides the functionality for administrators to edit articles.
 
-When you navigate to a certain page on a site or perform a certain operation such as login/logout then you're selecting the component which is going to be run. That component is the code which is primarily responsible for handling the HTTP Request, executing the requested operation, and displaying the key data on the web page. 
+In general, components manage the data of the Joomla instance and provide functionality for creating, editing, removing and displaying the data. Often the data management aspects are handled in the administrator backend and the site frontend simply displays the data, but this split of responsibility is not mandated, and some components provide frontend functionality for creating/editing/removing data.
 
-- Examples: Managing articles (com_content), Categories (com_categories), Contacts (com_contact), Images and media files (com_media)
-- Management feature: Admin menu → Components → Contacts (for com_contact)
+When you navigate to a certain page on a site or perform a certain operation such as login/logout then you're selecting the component which is going to be run. That component is the code which is primarily responsible for handling the HTTP Request, executing the requested operation, and displaying the key data on the web page.
 
-Examples of component functionality available from third party extensions include backup utilities and support for eCommerce. 
+- Core component examples: Articles (com_content), Categories (com_categories), Contacts (com_contact), Images and media files (com_media)
+- Third party examples: See the [Joomla Extensions Directory](https://extensions.joomla.org/) for third party extensions for Backup, eCommerce and many other purposes.
+
+To read more go to the [Components Index page](components).
 
 ## Modules
-[Modules](./modules/index.md) are more lightweight and flexible extensions displayed on a web page. Modules are mostly known as the “boxes” that are arranged around a component, for example: the login module or the breadcrumbs module. Modules are assigned per menu item. So you can decide to show or hide the login module depending on which menu item the user is viewing. 
+
+Modules are more lightweight and flexible extensions displayed on a web page. Modules are mostly known as the “boxes” that are arranged around a component, for example: the login module or the breadcrumbs module. Modules are assigned per menu item. So you can decide to show or hide the login module depending on which menu item the user is viewing.
 
 A module can often be a companion to the component. For example, if your web page displays an article (`com_content` component) then you might have a module (`mod_tags_similar`) in the sidebar which displays links to related articles, or a module which displays an image slider of related photos.
 
 However, modules do not need to be linked to components, as a matter of fact they don't even need to be linked to anything and can be just static HTML or text.
 
-- Examples: Latest Articles (mod_articles_latest), Menus (mod_menu), Who's Online (mod_whosonline), Custom HTML (mod_custom)
-- Management feature: Admin menu → Content → Site Modules
+- Core module examples: Latest Articles (mod_articles_latest), Menus (mod_menu), Who's Online (mod_whosonline), Custom HTML (mod_custom).
+
+If you're just beginning with Joomla extension development then developing a module is the easiest place to start.
 
-If you're just beginning with Joomla extension development then developing a module is the easiest place to start. 
+To read more go to the [Modules Index page](modules).
 
 ## Plugins
-[Plugins](./plugins/index.md) work behind the scenes to modify or enhance the basic Joomla functionality. In the execution of any part of Joomla - be it the core, a module or a component - an event can be triggered. When an event is triggered, plugins which are registered to handle that event execute, and are passed data related to that event. The plugin can then, for example, modify the data and return it to the core Joomla code. For example, a plugin could be used to intercept user-submitted articles and filter out bad words.
 
-- Examples: Content pagenavigation plugin (which generates the Prev and Next links as shown in the screenshot above)
-- Management feature: Admin menu → System → Plugins
+Joomla has over 150 Plugins that work behind the scenes to modify or enhance basic Joomla functionality. A plugin responds to a registered event triggered in the core, a component or a module and modifies the data related to that event. For example, the *Content - Email Cloaking* plugin obfuscates any email address in an output page so that it cannot be harvested by a robot.
+
+- Core examples: Content - Page Navigation (which generates the Prev and Next links as shown in the screenshot above).
+
+To read more go to the [Plugins Index page](plugins).
 
 ## Templates
-A [template](./templates/index.md) is basically the design of your Joomla-powered website. With a template you define the look and feel of your website, primarily based on CSS. Templates have certain fields in which the component (just one) and modules (as many as you like) will be shown. Building a complete Joomla template from scratch is difficult because you have to understand the variety of HTML output by the Joomla components, and the CSS classes which are used within them. However, it is relatively easy to customize the Atum (administrator) and Cassiopeia (site) templates which are shipped with Joomla, particularly as you can use the Joomla child template functionality to simply specify deviations from the parent template. 
 
-- Management feature: Admin menu → System → Templates
+A template is basically the design of your Joomla-powered website. With a template you define the look and feel of your website, primarily based on CSS. Templates have certain fields in which the component (just one) and modules (as many as you like) will be shown. Building a complete Joomla template from scratch is difficult because you have to understand the variety of HTML output by the Joomla components, and the CSS classes which are used within them. However, it is relatively easy to customize the Atum (administrator) and Cassiopeia (site) templates which are shipped with Joomla, particularly as you can use the Joomla child template functionality to simply specify deviations from the parent template.
+
+To read more go to the [Templates Index page](templates).
 
 ## Languages
-Probably the most basic extensions are languages. Languages can be packaged in two ways: either as a core package or as an extension package. In essence, both the core and the extension language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla source code. These language packs will affect both the front and administrator side of your Joomla instance. Note: these language packs also include an XML meta file which describes the language.
 
-- Management feature: Admin menu → System → Manage / Languages
+Probably the most basic extensions are languages, which can be packaged either as a core package or as an extension package. In essence, both the core and the extension language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla source code. These language packs will affect both the front and administrator side of your Joomla instance. Note: these language packs also include an XML meta file which describes the language.
 
 ## Libraries
-Libraries are standalone PHP snippets that Joomla uses. Note nearly all of Joomla's core code is available as a library within the libraries/src folder. All composer libraries (such as PHPMailer) are installed as a library "vendor" within libraries/vendor. Many of the most popular 3rd party extensions in Joomla use libraries to reuse common functionality across their components. 
+
+Libraries are standalone PHP snippets that Joomla uses. Note nearly all of Joomla's core code is available as a library within the libraries/src folder. All composer libraries (such as PHPMailer) are installed as a library "vendor" within libraries/vendor. Many of the most popular 3rd party extensions in Joomla use libraries to reuse common functionality across their components.
 
 ## File
-The File extension type is used to install individual files into a directory of the Joomla instance. There are no examples in Joomla Core of this type and it is the least used type, however it can be used for example to place [custom scripts](./custom-script/index.md) into the Joomla cli directory or to place template overrides into a specific directory. 
+
+The File extension type is used to install individual files into a directory of the Joomla instance. There are no examples in Joomla Core of this type and it is the least used type, however it can be used for example to place [custom scripts](./custom-script/index.md) into the Joomla cli directory or to place template overrides into a specific directory.
 
 ## Packages
-Packages are simply a group of any of the above types of extensions. A common use of a package would be to ship a template that also bundles a system plugin. Or a component that also installs a library it uses. In Joomla many language packs install as a package so that the frontend and backend languages can be installed independently. 
+
+Packages are simply a group of any of the above types of extensions. A common use of a package would be to ship a template that also bundles a system plugin. Or a component that also installs a library it uses. In Joomla many language packs install as a package so that the frontend and backend languages can be installed independently.
 
 ## Extension Installation
-There are 4 methods of installing an extension. You can install from the Joomla Extension Directory (Install from Web), upload the zip file of an extension, install from a folder or install from a URL. 
+
+There are four methods of installing an extension: by upload of a zip file, from a folder, from a URL or from the Joomla Extension Directory (Install from Web).
 
 ![Screenshot showing installing an extension](./_assets/screenshot-install-extension.jpg)