Skip to content

Commit f8b8ed0

Browse files
gonzalezrealgonzalezreal
committed
Update docs
1 parent 8570ba0 commit f8b8ed0

File tree

2 files changed

+69
-134
lines changed

2 files changed

+69
-134
lines changed

‎README.md‎

Lines changed: 40 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@
44
[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fgonzalezreal%2FNetworkImage%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/gonzalezreal/NetworkImage)
55
[![contact: @gonzalezreal](https://img.shields.io/badge/contact-@gonzalezreal-blue.svg?style=flat)](https://twitter.com/gonzalezreal)
66

7-
NetworkImage is a Swift package that provides image downloading, caching, and displaying for your SwiftUI apps. It leverages the foundation URLCache, providing persistent and in-memory caches.
7+
NetworkImage is a Swift package that provides image downloading, caching, and displaying for your
8+
SwiftUI apps. It leverages the foundation URLCache, providing persistent and in-memory caches.
89

9-
You can explore all the capabilities of this package in the [companion demo project](Examples/NetworkImageDemo).
10+
You can explore all the capabilities of this package in the
11+
[companion demo project](Examples/NetworkImageDemo).
1012

1113
## Supported Platforms
1214

@@ -18,73 +20,59 @@ You can use `NetworkImage` in the following platforms:
1820
* watchOS 6.0+
1921

2022
## Usage
21-
A network image downloads and displays an image from a given URL; the download is asynchronous, and the result is cached both in disk and memory.
23+
A network image downloads and displays an image from a given URL; the download is asynchronous,
24+
and the result is cached both in disk and memory.
2225

2326
You create a network image, in its simplest form, by providing the image URL.
2427

2528
```swift
2629
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
27-
.scaledToFit()
30+
.frame(width: 300, height: 200)
2831
```
2932

30-
You can also provide the name of a placeholder image that the view will display while the image is loading or, as a fallback, if an error occurs or the URL is `nil`.
33+
To manipulate the loaded image, use the `content` parameter.
3134

3235
```swift
33-
NetworkImage(
34-
url: URL(string: "https://picsum.photos/id/237/300/200"),
35-
placeholderSystemImage: "photo.fill"
36-
)
37-
.scaledToFit()
38-
```
39-
40-
If you want, you can only provide a fallback image. A network image view only displays this image if an error occurs or when the URL is `nil`.
41-
42-
```swift
43-
NetworkImage(
44-
url: URL(string: "https://picsum.photos/id/237/300/200"),
45-
fallbackSystemImage: "photo.fill"
46-
)
47-
.scaledToFit()
36+
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200")) { image in
37+
image.resizable().scaledToFill()
38+
}
39+
.frame(width: 150, height: 150)
40+
.clipped()
4841
```
4942

50-
It is also possible to create network images using views to compose the network image's placeholders programmatically.
43+
The view displays a standard placeholder that fills the available space until the image loads. You
44+
can specify a custom placeholder by using the `placeholder` parameter.
5145

5246
```swift
53-
NetworkImage(url: movie.posterURL) {
54-
ProgressView()
55-
} fallback: {
56-
Text(movie.title)
57-
.padding()
47+
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200")) { image in
48+
image.resizable().scaledToFill()
49+
} placeholder: {
50+
Color.yellow // Shown while the image is loaded or an error occurs
5851
}
59-
.scaledToFit()
52+
.frame(width: 150, height: 150)
53+
.clipped()
6054
```
6155

62-
### Styling Network Images
63-
You can customize the appearance of network images by creating styles that conform to the `NetworkImageStyle` protocol. To set a specific style for all network images within a view, use the `networkImageStyle(_:)` modifier. In the following example, a custom style adds a grayscale effect to all the network image views within the enclosing `VStack`:
56+
It is also possible to specify a custom fallback placeholder that the view will display if there is
57+
an error or the URL is `nil`.
6458

6559
```swift
66-
struct ContentView: View {
67-
var body: some View {
68-
VStack {
69-
NetworkImage(url: URL(string: "https://picsum.photos/id/1025/300/200"))
70-
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
71-
}
72-
.networkImageStyle(GrayscaleNetworkImageStyle())
73-
}
74-
}
75-
76-
struct GrayscaleNetworkImageStyle: NetworkImageStyle {
77-
func makeBody(configuration: Configuration) -> some View {
78-
configuration.image
79-
.resizable()
80-
.scaledToFit()
81-
.grayscale(0.99)
82-
}
60+
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200")) { image in
61+
image.resizable().scaledToFill()
62+
} placeholder: {
63+
ProgressView() // Shown while the image is loaded
64+
} fallback: {
65+
Image(systemName: "photo") // Shown when an error occurs or the URL is nil
8366
}
67+
.frame(width: 150, height: 150)
68+
.clipped()
69+
.background(Color.yellow)
8470
```
8571

8672
### Using NetworkImageLoader
87-
For other use cases outside the scope of SwiftUI, you can download images directly using the shared `NetworkImageLoader`. In the following example, a view controller downloads an image and applies a transformation to it:
73+
For other use cases outside the scope of SwiftUI, you can download images directly using the
74+
shared `NetworkImageLoader`. In the following example, a view controller downloads an image
75+
and applies a transformation to it.
8876

8977
```swift
9078
class MyViewController: UIViewController {
@@ -132,7 +120,10 @@ For other use cases outside the scope of SwiftUI, you can download images direct
132120
```
133121

134122
### NetworkImage and Testing
135-
NetworkImage is implemented with testing in mind and provides view modifiers to stub image responses and replace the scheduler that drives the view state changes. This allows you to write synchronous tests, avoiding the use of expectations or waits. The following example shows how to use this feature with Point-Free's [SnapshotTesting](https://github.com/pointfreeco/swift-snapshot-testing) library.
123+
NetworkImage is implemented with testing in mind and provides view modifiers to stub image
124+
responses. This allows you to write synchronous tests, avoiding the use of expectations or waits.
125+
The following example shows how to use this feature with Point-Free's
126+
[SnapshotTesting](https://github.com/pointfreeco/swift-snapshot-testing) library.
136127

137128
```swift
138129
final class MyTests: XCTestCase {
@@ -145,43 +136,12 @@ final class MyTests: XCTestCase {
145136
.networkImageLoader(
146137
.mock(response: Fail(error: URLError(.badServerResponse) as Error))
147138
)
148-
// Disable animations
149-
.networkImageScheduler(UIScheduler.shared)
150-
151-
assertSnapshot(matching: view, as: .image(layout: .device(config: .iPhoneSe)))
152-
}
153-
}
154-
```
155139

156-
### Animations
157-
NetworkImage performs an explicit `.default` animation when its state changes, using a [Combine Scheduler](https://developer.apple.com/documentation/combine/scheduler). You can override this scheduler and adjust the animation with the `networkImageScheduler(_:)` view modifier.
158-
159-
```swift
160-
struct ContentView: View {
161-
var body: some View {
162-
VStack {
163-
NetworkImage(url: URL(string: "https://picsum.photos/id/1025/300/200"))
164-
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
165-
}
166-
.networkImageScheduler(UIScheduler.shared.animation(.easeIn(duration: 0.25)))
140+
assertSnapshot(matching: view, as: .image(layout: .device(config: .iPhoneSe)))
167141
}
168142
}
169143
```
170144

171-
If you want to disable animations in NetworkImage, simply pass `UIScheduler.shared` to the `.networkImageScheduler` view modifier.
172-
173-
```swift
174-
struct ContentView: View {
175-
var body: some View {
176-
VStack {
177-
NetworkImage(url: URL(string: "https://picsum.photos/id/1025/300/200"))
178-
NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
179-
}
180-
.networkImageScheduler(UIScheduler.shared)
181-
}
182-
}
183-
```
184-
185145
## Installation
186146
You can add NetworkImage to an Xcode project by adding it as a package dependency.
187147
1. From the **File** menu, select **Swift Packages › Add Package Dependency…**

‎Sources/NetworkImage/SwiftUI/NetworkImage.swift‎

Lines changed: 29 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -9,67 +9,42 @@ import SwiftUI
99
///
1010
/// You create a network image, in its simplest form, by providing the image URL.
1111
///
12-
/// ```swift
13-
/// NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
14-
/// ```
12+
/// NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
13+
/// .frame(width: 300, height: 200)
1514
///
16-
/// You can also provide the name of a placeholder image that the view will display while the image is loading or, as
17-
/// a fallback, if an error occurs or the URL is `nil`.
15+
/// To manipulate the loaded image, use the `content` parameter.
1816
///
19-
/// ```swift
20-
/// NetworkImage(
21-
/// url: URL(string: "https://picsum.photos/id/237/300/200"),
22-
/// placeholderSystemImage: "photo.fill"
23-
/// )
24-
/// ```
25-
///
26-
/// If you want, you can only provide a fallback image. A network image view only displays this image if an error occurs
27-
/// or when the URL is `nil`.
28-
///
29-
/// ```swift
30-
/// NetworkImage(
31-
/// url: URL(string: "https://picsum.photos/id/237/300/200"),
32-
/// fallbackSystemImage: "photo.fill"
33-
/// )
34-
/// ```
35-
///
36-
/// It is also possible to create network images using views to compose the network image's placeholders
37-
/// programmatically.
17+
/// NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200")) { image in
18+
/// image.resizable().scaledToFill()
19+
/// }
20+
/// .frame(width: 150, height: 150)
21+
/// .clipped()
3822
///
39-
/// ```swift
40-
/// NetworkImage(url: movie.posterURL) {
41-
/// ProgressView()
42-
/// } fallback: {
43-
/// Text(movie.title)
44-
/// .padding()
45-
/// }
46-
/// ```
23+
/// The view displays a standard placeholder that fills the available space until the image loads. You can
24+
/// specify a custom placeholder by using the `placeholder` parameter.
4725
///
48-
/// ### Styling Network Images
26+
/// NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200")) { image in
27+
/// image.resizable().scaledToFill()
28+
/// } placeholder: {
29+
/// Color.yellow // Shown while the image is loaded or an error occurs
30+
/// }
31+
/// .frame(width: 150, height: 150)
32+
/// .clipped()
4933
///
50-
/// You can customize the appearance of network images by creating styles that conform to the
51-
/// `NetworkImageStyle` protocol. To set a specific style for all network images within a view, use
52-
/// the `networkImageStyle(_:)` modifier. In the following example, a custom style adds a grayscale
53-
/// effect to all the network image views within the enclosing `VStack`:
34+
/// It is also possible to specify a custom fallback placeholder that the view will display if there is an
35+
/// error or the URL is `nil`.
5436
///
55-
/// ```swift
56-
/// struct ContentView: View {
57-
/// var body: some View {
58-
/// VStack {
59-
/// NetworkImage(url: URL(string: "https://picsum.photos/id/1025/300/200"))
60-
/// NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200"))
37+
/// NetworkImage(url: URL(string: "https://picsum.photos/id/237/300/200")) { image in
38+
/// image.resizable().scaledToFill()
39+
/// } placeholder: {
40+
/// ProgressView() // Shown while the image is loaded
41+
/// } fallback: {
42+
/// Image(systemName: "photo") // Shown when an error occurs or the URL is nil
6143
/// }
62-
/// .networkImageStyle(GrayscaleNetworkImageStyle())
63-
/// }
64-
/// }
65-
/// struct GrayscaleNetworkImageStyle: NetworkImageStyle {
66-
/// func makeBody(configuration: Configuration) -> some View {
67-
/// configuration.image
68-
/// .resizable()
69-
/// .grayscale(0.99)
70-
/// }
71-
/// }
72-
/// ```
44+
/// .frame(width: 150, height: 150)
45+
/// .clipped()
46+
/// .background(Color.yellow)
47+
///
7348
public struct NetworkImage<Content>: View where Content: View {
7449
private enum ViewState: Equatable {
7550
case empty

0 commit comments

Comments
 (0)