Added explanation of the fetch module.

src/concepts/services/fetch.md

@@ -0,0 +1,180 @@
+# The Fetch Service
+## Introduction
+The fetch module can be used to make requests to a server. This allows a Yew application to connect 
+to a backend server and provide interactive functionality. 
+
+## Making requests
+### Building requests
+Yew has a struct `Request` (which comes from the `http` crate) that is used to 'build' requests 
+before they can be dispatched to a server. The body type of the request must have the trait `Into<Text>`.
+```rust
+use yew::services::fetch::Request;
+use yew::format::Nothing;
+let get_request = Request::get("https://example.com/api/v1/get/something").body(Nothing).expect("Could not build that request");
+```
+```rust
+use yew::services::fetch::Request;
+use yew::format::Json;
+use serde_json::json;
+let post_request = Request::post("https://example.com/api/v1/post/something").header("Content-Type", "application/json").body(Json(&json!({"key": "value"}))).expect("Could not build that request.");
+```
+### Dispatching requests
+The `FetchService` provides a binding to the browser's `fetch` API. Requests can be sent using either 
+`FetchService::fetch` or `FetchService::fetch_with_options` (`fetch_with_options` should be used 
+where cookies need to 
+be sent in a request).
+
+`FetchService::fetch` accepts two parameters: a `Request` object and a `Callback`. The closure with 
+which the callback is constructed must take a single parameter of type `Response`. `Response` accepts
+a type argument – the type must implement `From<Text>`.
+
+It's important that the `FetchTask` returned is kept alive until the request has finished – i.e. it 
+should not be dropped until the request has finsihed and a response has been obtained. If the 
+`FetchTask` is dropped then the request will be cancelled.
+
+{% hint style="info" %}
+If you keep getting an error saying that "the operation was aborted" or "Error 408" this might be 
+because the [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) of the website 
+you are trying to access are not set correctly.
+{% endhint %}
+
+```rust 
+use yew::prelude::*;
+use yew::services::fetch::{FetchService, FetchTask};
+use serde::Deserialize;
+
+#[derive(Debug, Clone)]
+struct FetchServiceExample {
+ ft: Option<FetchTask>,
+ iss: Option<ISS>,
+ link: ComponentLink<Self>,
+ error: Option<String>
+}
+
+impl FetchServiceExample {
+ fn view_iss_location(&self) -> Html {
+ match self.iss {
+ Some(space_station) => html! {
+ <p>{"The ISS is at:"}</p>
+ <p>{format!("Latitude: {}", space_station.iss_location.latitude)}</p>
+ <p>{format!("Longitude: {}", space_station.iss_location.longitude)}</p>
+ }
+ None => html! {
+ <button onclick=self.link.callback(|_| {<Self as Component>::Message::GetLocation})>
+ {"Where is the ISS?"}
+ </button>
+ }
+ }
+ }
+ fn is_fetching(&self) -> Html {
+ if self.fetching {
+ html! {<p>{"Fetching data..."}</p>}
+ } else {
+ html! {<p></p>}
+ }
+ }
+}
+
+#[derive(Deserialize, Debug, Clone)]
+struct ISSPosition {
+ latitude: String,
+ longitude: String
+}
+
+#[derive(Deserialize, Debug, Clone)]
+struct ISS {
+ message: String,
+ timestamp: i32,
+ iss_position: ISSPosition,
+ fetching: bool
+}
+
+#[derive(Debug, Clone)]
+enum Msg {
+ GetLocation,
+ Noop,
+ ReceiveLocation(ISS),
+ FetchError(String)
+}
+
+impl Component for FetchServiceExample {
+ type Message = Msg;
+ type Properties = ();
+ fn create(_: Self::Properties, link: ComponentLink<Self>) -> Self {
+ Self {
+ ft: None,
+ iss: None,
+ link,
+ fetching: false
+ }
+ }
+ fn change(&mut self, _: Self::Properties) -> bool {
+ false
+ }
+ fn update(&mut self, msg: Self::Message) -> bool {
+ match msg {
+ GetLocation => {
+ // 1. build the request
+ let request = Request::get("http://api.open-notify.org/iss-now.json")
+ .body(Nothing)
+ .expect("Could not build request.");
+ // 2. construct a callback
+ let callback = self.link.callback(|response: Response<Json<Result<ISS, anyhow::Error>>>| {
+ // split up the response into the HTTP data about the request result and data from the request
+ // Json(data) has type `Json<Result<ISS, anyhow::Error>>`
+ let (meta, Json(Ok(data))) = response.into_parts(); 
+ if meta.status.is_success() && data.message == "success" {
+ Self::Message::ReceiveLocation(match data {
+ Ok(d) => d,
+ // handle errors more properly than this
+ Err(_) => panic!("Could not handle this error")
+ })
+ } else {
+ Self::Message::FetchError(data.message)
+ }
+ });
+ // 3. pass the request and callback to the fetch service 
+ FetchService::fetch(request, callback);
+ self.fetching = true;
+ // we want to redraw so that the page displays a 'fetching...' message to the user so return 'true'
+ true
+ }
+ ReceiveLocation(location) => {
+ self.iss = location;
+ self.fetching = false;
+ // we want to redraw so that the page displays the location of the ISS instead of 'fetching...'
+ true
+ }
+ FetchError(error) => {
+ self.error = error; 
+ }
+ _ => false
+ }
+ }
+ fn view(&self) -> Html {
+ html! {
+ <>
+ {self.is_fetching()}
+ {self.view_iss_location()}
+ {
+ if let Some(error) = self.error {
+ <p>{error.clone()}</p>
+ }
+ }
+ </>
+ }
+ }
+}
+```
+
+## Debugging the `FetchService`
+
+Most browsers' developer tools have a "network" pane which can be used to inspect and view requests 
+browsers have made, including data such as request headers and the contents of responses. This can be
+a useful way to gain an insight into what requests are being made, the data being sent to the server
+as well as the return data from the server.
+
+## Further reading
+* [The API documentation](https://docs.rs/yew/0.14.3/yew/services/fetch/index.html)
+* The [dashboard](https://github.com/yewstack/yew/tree/master/examples/dashboard) and 
+[npm_and_rest](https://github.com/yewstack/yew/tree/master/examples/web_sys/npm_and_rest) examples.