Merge pull request #332 from robbiejackson/update-sql-field

more explanation of sql field, plus changes to reflect how it changed in 5.2

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

@@ -15,7 +15,7 @@ simply change the url in media/js/divide.js to point to com_ajax instead of com_
 
 Once you have downloaded the source, zip up the com_ajaxdemo directory and install the component.
 
-Then go to `<your domain>/index.php/component/ajaxdemo` to run it on your Joomla instance.
+Then go to `<your domain>/index.php?option=com_ajaxdemo` to run it on your Joomla instance.
 
 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.
@@ -41,7 +41,7 @@ Based on this the default Dispatcher will instantiate this component's AjaxContr
 
 Path: components/com_ajaxdemo/src/Controller/DisplayController.php
 
-This controller's display method is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/ajaxdemo`).
+This controller's display method is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_ajaxdemo`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

docs/building-extensions/components/component-examples/example-form-component.md

@@ -10,7 +10,7 @@ This is an example component which you can download from [com_exampleform](https
 
 Once you have downloaded the source, zip up the com_exampleform directory and install the component.
 
-Then go to `<your domain>/index.php/component/exampleform` to run it on your Joomla instance.
+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:
 
@@ -38,7 +38,7 @@ From this file Joomla instantiates default [Extension and Dispatcher classes](..
 
 Path: components/com_exampleform/src/Controller/DisplayController.php
 
-This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/exampleform`).
+This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_exampleform`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

docs/general-concepts/forms-fields/standard-fields/modalselect.md

@@ -115,7 +115,7 @@ However, you can use this [exampleform component](../../../building-extensions/c
 />
 ```
 
-By navigating to "/index.php/component/exampleform/" on your site front-end, this will display a ModalSelect field which will allow you to select an article.
+By navigating to "/index.php?option=com_exampleform" on your site front-end, this will display a ModalSelect field which will allow you to select an article.
 
 After clicking the "Select" button the field will open a Joomla Dialog containing a iframe.
 The content of the iframe comes from `urlSelect` which is 

docs/general-concepts/forms-fields/standard-fields/sql.md

@@ -215,6 +215,11 @@ can be expressed as:
 
 ## Linked Fields as Filters
 
+:::tip
+  The description below is quite complex and you may find it helpful to install
+  the [example sqlfield component](./sql.md#example-component) and use it to help you in your understanding.
+:::
+
 One advantage to using the alternative syntax above is that it allows the use of linked
 fields as filters. For example, suppose you have a form containing two
 select lists, one called *groups* and the other called *subgroups*. The
@@ -344,7 +349,7 @@ Joomla.
 
 Let's take the example where 
 - the linked filter field is a category field, 
-- the SQL field shows the titles of articles whose category is selected in the category field.
+- the SQL field is an HTML Select field which shows the titles of articles whose category is selected in the category field.
 
 You want to allow the user to select the category, and then be shown the titles of articles with that category, so that he/she can then select the article.
 
@@ -353,9 +358,12 @@ However, whenever the user selects or changes the category, the code ***doesn't
 That said, you can implement the functionality to update the titles by following the approach below.
 
 To update the sql field you need to reload the form by
-1. sending the current form data to the server (by submitting the form), 
-2. passing the key value(s) from the current form data into the `user state` where they can be picked up by the SQL field, and,
-3. redisplaying the form via your View class and tmpl file
+1. **sending the current form data** to the server (by submitting the form in your javascript code), 
+2. **redisplaying the form** via your View class and tmpl file
+
+When you redisplay the form you inject the current form field values into the `Form` structure. 
+The SQL field will then pick up the key value(s) from the `Form` structure,
+and perform the SQL query using these new values, in order to set the new options for the SQL HTML Select field.
 
 To **send the form data**, implement an onchange javascript listener against the category field, for example, by setting in the XML the file attribute
 
@@ -381,10 +389,6 @@ Then the form is submitted with
 
 This POST request will be routed to your SqlfieldController::reload() method.
 
-To **pass the key values by user state** you need to call `setUserState`, using
-- the **context** you specified as your attribute in the SQL field
-- the relevant data items from the POST parameters
-
 So you need to include in your SqlfieldController::reload() method something like:
 
 ```php title="SqlfieldController.php"
@@ -399,22 +403,10 @@ public function reload($key = null, $urlVar = null)
     // This is the usual call to set the state for preserving the form data entered by the user
     $app->setUserState('com_sqlfield.example', $data);
 
-    $catid = filter_var($data['catid'], FILTER_SANITIZE_NUMBER_INT);
-    // This is the call you need to make to pass the sql_filter ids to the SQL field
-    // The first parameter must be `'<context>.filter'` where `context` is what you set
-    // as the context= ... attribute of the SQL field
-    $app->setUserState('sqlfield.filter', array('catid' => $catid));
-
-    // Then re-present the form
+    // Then redisplay the form
 }
 ```
 
-When you have received successfully validated data then you should clear the filter state (in the same way as you would do with the form data), so that the next time the form is displayed it doesn't contain the titles which match the category from the previous execution of the form, because this is unlikely to match what is the initial value in the category field.
-
-```php 
-$app->setUserState('sqlfield.filter', null);
-```
-
 To **redisplay the form** you can either send the form as an HTTP response to the HTTP POST request:
 
 ```php title="SqlfieldController.php"
@@ -427,8 +419,34 @@ To **redisplay the form** you can either send the form as an HTTP response to th
 
 or use the Post/Request/Get pattern to redirect to the DisplayController.
 
-You can download [this com_sqlfield component](./_assets/com_sqlfield.zip) as an example to follow (you may need to change the sql_default_catid attribute). 
-Once you have installed the com_sqlfield component you can run the form by navigating to your Joomla instance's site page index.php/component/sqlfield/
+(The example component below uses the first approach).
+
+### Example Component
+
+You can download [this com_sqlfield component](./_assets/com_sqlfield.zip) as an example to follow.
+
+Go onto your Joomla instance back-end, display the article categories and find the id of your `Uncategorised` category.
+
+If it's not 2 then edit the com_sqlfield site/forms/example_form.xml and set the `sql_default_catid` to whatever id it is.
+
+Install the com_sqlfield component and run the form by navigating to your Joomla instance's site page index.php?option=com_sqlfield
+
+The component will display an HTML select field with the article categories available on your instance, and in the next field, 
+the titles of the articles associated with the selected category.
+
+If you select a different category then the component will send the form data to the server in an HTTP POST request, 
+with the task parameter set to "sqlfield.reload" which will cause the `SqlfieldController::reload()` function to be called.
+This function stores the existing form values in the user state, and arranges for the form to be redisplayed. 
+
+When the component redisplays the form it injects the existing form values into the Joomla `Form` structure,
+(so that when the form is redisplayed the user sees the values he/she previously entered).
+The SQL Field can then obtain the category from this `Form` structure, 
+and perform a SQL query to obtain the articles associated with the selected category. 
+These article ids and titles will be set as options in the field, and will be shown when the form is re-presented. 
+
+When you press `Select` then the selected category and article will be sent to the server in the HTTP POST request,
+together with the task set to "sqlfield.submit", 
+and the component code then displays the selected ids in the associated HTTP POST response. 
 
 ## See also
 

docs/general-concepts/mail.md

@@ -238,7 +238,7 @@ It demonstrates sending emails both using the `Mail` class and the `MailTemplate
 As part of its installation `com_sendmail` creates a MailTemplate with a key of 'com_sendmail.example',
 which you can then view and edit via the administrator Mail Templates functionality.
 
-To run the component you should navigate to `<your domain>/index.php/component/sendmail`.
+To run the component you should navigate to `<your domain>/index.php?option=com_sendmail`.
 
 The component will display a form which will:
 - let you select whether you want to send the email using `Mail` or `MailTemplate`, and,

versioned_docs/version-4.4/building-extensions/components/component-examples/ajaxdemo.md

@@ -15,7 +15,7 @@ simply change the url in media/js/divide.js to point to com_ajax instead of com_
 
 Once you have downloaded the source, zip up the com_ajaxdemo directory and install the component.
 
-Then go to `<your domain>/index.php/component/ajaxdemo` to run it on your Joomla instance.
+Then go to `<your domain>/index.php?option=com_ajaxdemo` to run it on your Joomla instance.
 
 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.
@@ -41,7 +41,7 @@ Based on this the default Dispatcher will instantiate this component's AjaxContr
 
 Path: components/com_ajaxdemo/src/Controller/DisplayController.php
 
-This controller's display method is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/ajaxdemo`).
+This controller's display method is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_ajaxdemo`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

versioned_docs/version-4.4/building-extensions/components/component-examples/example-form-component.md

@@ -10,7 +10,7 @@ This is an example component which you can download from [com_exampleform](https
 
 Once you have downloaded the source, zip up the com_exampleform directory and install the component.
 
-Then go to `<your domain>/index.php/component/exampleform` to run it on your Joomla instance.
+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:
 
@@ -38,7 +38,7 @@ From this file Joomla instantiates default [Extension and Dispatcher classes](..
 
 Path: components/com_exampleform/src/Controller/DisplayController.php
 
-This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/exampleform`).
+This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_exampleform`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

versioned_docs/version-4.4/general-concepts/forms-fields/standard-fields/sql.md

@@ -215,6 +215,11 @@ can be expressed as:
 
 ## Linked Fields as Filters
 
+:::tip
+  The description below is quite complex and you may find it helpful to install
+  the [example sqlfield component](./sql.md#example-component) and use it to help you in your understanding.
+:::
+
 One advantage to using the alternative syntax above is that it allows the use of linked
 fields as filters. For example, suppose you have a form containing two
 select lists, one called *groups* and the other called *subgroups*. The
@@ -427,8 +432,29 @@ To **redisplay the form** you can either send the form as an HTTP response to th
 
 or use the Post/Request/Get pattern to redirect to the DisplayController.
 
-You can download [this com_sqlfield component](./_assets/com_sqlfield.zip) as an example to follow (you may need to change the sql_default_catid attribute). 
-Once you have installed the com_sqlfield component you can run the form by navigating to your Joomla instance's site page index.php/component/sqlfield/
+### Example Component
+
+You can download [this com_sqlfield component](./_assets/com_sqlfield.zip) as an example to follow.
+
+Go onto your Joomla instance back-end, display the article categories and find the id of your `Uncategorised` category.
+
+If it's not 2 then edit the com_sqlfield site/forms/example_form.xml and set the `sql_default_catid` to whatever id it is.
+
+Install the com_sqlfield component and run the form by navigating to your Joomla instance's site page index.php?option=com_sqlfield
+
+The component will display an HTML select field with the article categories available on your instance, and in the next field, 
+the titles of the articles associated with the selected category.
+
+If you select a different category then the component will send the form data to the server in an HTTP POST request, 
+with the task parameter set to "sqlfield.reload" which will cause the `SqlfieldController::reload()` function to be called.
+
+The SQL Field will obtain the category from the user state, 
+and perform a SQL query to obtain the articles associated with the selected category. 
+These article ids and titles will be set in the field, and will be shown when the form is re-presented. 
+
+When you press `Select` then the selected category and article will be sent to the server in the HTTP POST request,
+together with the task set to "sqlfield.submit", 
+and the component code then displays the selected ids in the associated HTTP POST response. 
 
 ## See also
 

versioned_docs/version-4.4/general-concepts/mail.md

@@ -238,7 +238,7 @@ It demonstrates sending emails both using the `Mail` class and the `MailTemplate
 As part of its installation `com_sendmail` creates a MailTemplate with a key of 'com_sendmail.example',
 which you can then view and edit via the administrator Mail Templates functionality.
 
-To run the component you should navigate to `<your domain>/index.php/component/sendmail`.
+To run the component you should navigate to `<your domain>/index.php?option=com_sendmail`.
 
 The component will display a form which will:
 - let you select whether you want to send the email using `Mail` or `MailTemplate`, and,

versioned_docs/version-5.0/building-extensions/components/component-examples/example-form-component.md

@@ -10,7 +10,7 @@ This is an example component which you can download from [com_exampleform](https
 
 Once you have downloaded the source, zip up the com_exampleform directory and install the component.
 
-Then go to `<your domain>/index.php/component/exampleform` to run it on your Joomla instance.
+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:
 
@@ -38,7 +38,7 @@ From this file Joomla instantiates default [Extension and Dispatcher classes](..
 
 Path: components/com_exampleform/src/Controller/DisplayController.php
 
-This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/exampleform`).
+This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_exampleform`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

versioned_docs/version-5.0/general-concepts/forms-fields/standard-fields/sql.md

@@ -428,7 +428,7 @@ To **redisplay the form** you can either send the form as an HTTP response to th
 or use the Post/Request/Get pattern to redirect to the DisplayController.
 
 You can download [this com_sqlfield component](./_assets/com_sqlfield.zip) as an example to follow (you may need to change the sql_default_catid attribute). 
-Once you have installed the com_sqlfield component you can run the form by navigating to your Joomla instance's site page index.php/component/sqlfield/
+Once you have installed the com_sqlfield component you can run the form by navigating to your Joomla instance's site page index.php?option=com_sqlfield
 
 ## See also
 

versioned_docs/version-5.1/building-extensions/components/component-examples/ajaxdemo.md

@@ -15,7 +15,7 @@ simply change the url in media/js/divide.js to point to com_ajax instead of com_
 
 Once you have downloaded the source, zip up the com_ajaxdemo directory and install the component.
 
-Then go to `<your domain>/index.php/component/ajaxdemo` to run it on your Joomla instance.
+Then go to `<your domain>/index.php?option=com_ajaxdemo` to run it on your Joomla instance.
 
 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.
@@ -41,7 +41,7 @@ Based on this the default Dispatcher will instantiate this component's AjaxContr
 
 Path: components/com_ajaxdemo/src/Controller/DisplayController.php
 
-This controller's display method is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/ajaxdemo`).
+This controller's display method is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_ajaxdemo`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

versioned_docs/version-5.1/building-extensions/components/component-examples/example-form-component.md

@@ -10,7 +10,7 @@ This is an example component which you can download from [com_exampleform](https
 
 Once you have downloaded the source, zip up the com_exampleform directory and install the component.
 
-Then go to `<your domain>/index.php/component/exampleform` to run it on your Joomla instance.
+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:
 
@@ -38,7 +38,7 @@ From this file Joomla instantiates default [Extension and Dispatcher classes](..
 
 Path: components/com_exampleform/src/Controller/DisplayController.php
 
-This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php/component/exampleform`).
+This is what is run when you go to your site page which displays the form (ie navigate to the URL `.../index.php?option=com_exampleform`).
 
 It gets the associated Model and View classes, and calls display() on the View instance.
 

versioned_docs/version-5.1/general-concepts/forms-fields/standard-fields/sql.md

@@ -428,7 +428,7 @@ To **redisplay the form** you can either send the form as an HTTP response to th
 or use the Post/Request/Get pattern to redirect to the DisplayController.
 
 You can download [this com_sqlfield component](./_assets/com_sqlfield.zip) as an example to follow (you may need to change the sql_default_catid attribute). 
-Once you have installed the com_sqlfield component you can run the form by navigating to your Joomla instance's site page index.php/component/sqlfield/
+Once you have installed the com_sqlfield component you can run the form by navigating to your Joomla instance's site page index.php?option=com_sqlfield
 
 ## See also
 

versioned_docs/version-5.1/general-concepts/mail.md

@@ -238,7 +238,7 @@ It demonstrates sending emails both using the `Mail` class and the `MailTemplate
 As part of its installation `com_sendmail` creates a MailTemplate with a key of 'com_sendmail.example',
 which you can then view and edit via the administrator Mail Templates functionality.
 
-To run the component you should navigate to `<your domain>/index.php/component/sendmail`.
+To run the component you should navigate to `<your domain>/index.php?option=com_sendmail`.
 
 The component will display a form which will:
 - let you select whether you want to send the email using `Mail` or `MailTemplate`, and,