Wikipedia iOS

https://github.com/wikimedia/wikipedia-ios
Admin
The official Wikipedia iOS app that provides access to Wikipedia content on Apple's iOS devices with...
Tokens:37,700
Snippets:204
Trust Score:9.1
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Xcode Command Line Tools

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/fastlane/README.md

Installs the necessary Xcode command line tools. This is a prerequisite for using fastlane and other development tools on macOS.

```shell
xcode-select --install
```

--------------------------------

### Configure snapshot settings in Snapfile

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/WikipediaUITests/README.md

The Snapfile is used to configure snapshotting parameters, including languages, simulators, and other options. It's recommended to temporarily comment out all but one language and simulator for initial setup and debugging.

```ruby
# Example configuration in /fastlane/snapfile
# Uncomment and set specific languages and devices as needed.
# languages [
#   "en",
#   "de"
# ]
# devices [
#   "iPhone 5s",
#   "iPhone 6"
# ]
```

--------------------------------

### Perform GET Request and Handle JSON Response using Swift Session

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

This snippet demonstrates how to perform a GET request to the Wikipedia API and parse the JSON response. It initializes a `Session` object, creates a `URLRequest`, and uses `jsonDictionaryTask` to fetch and process the data. Error handling and response validation are included. Dependencies: Foundation, Wikipedia's `Session` class.

```swift
import Foundation

// Initialize session (typically done through MWKDataStore)
let config = Configuration.current
let session = Session(configuration: config)

// Perform a GET request with JSON response
let url = URL(string: "https://en.wikipedia.org/api/rest_v1/page/summary/Swift_(programming_language)")!
var request = URLRequest(url: url)
request.httpMethod = "GET"

let task = session.jsonDictionaryTask(with: request) { (result, response, error) in
    if let error = error {
        print("Request failed: (error.localizedDescription)")
        return
    }

    guard let json = result,
          let title = json["title"] as? String,
          let extract = json["extract"] as? String else {
        print("Invalid response format")
        return
    }

    print("Article: (title)")
    print("Summary: (extract)")
}
task?.resume()
```

--------------------------------

### Swift Fetcher Class: MediaWiki API Interactions

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

Demonstrates the usage of the `Fetcher` class in Swift for interacting with the MediaWiki API. It covers requesting CSRF tokens, performing GET requests for search queries, executing tokenized POST requests for edits, and cancelling tasks. This class is essential for any network operations related to the MediaWiki API within the app.

```swift
import Foundation

// Create a fetcher (typically use specialized subclasses)
let dataStore = MWKDataStore.shared()
let fetcher = Fetcher(session: dataStore.session, configuration: dataStore.configuration)

// Request a CSRF token for authenticated operations
let wikiURL = URL(string: "https://en.wikipedia.org/wiki/Main_Page")!
fetcher.requestMediaWikiAPIAuthToken(for: wikiURL, type: .csrf) { result in
    switch result {
    case .success(let token):
        print("CSRF Token: (token.value)")
        // Use token for edit operations
    case .failure(let error):
        print("Token request failed: (error.localizedDescription)")
    }
}

// Perform a MediaWiki API GET request
let searchParams: [String: Any] = [
    "action": "query",
    "list": "search",
    "srsearch": "iOS development",
    "srlimit": 10,
    "format": "json"
]

let cancellationKey = UUID().uuidString
let task = fetcher.performMediaWikiAPIGET(for: wikiURL, with: searchParams, cancellationKey: cancellationKey) { (result, response, error) in
    if let error = error {
        print("Search failed: (error.localizedDescription)")
        return
    }

    guard let result = result,
          let query = result["query"] as? [String: Any],
          let searchResults = query["search"] as? [[String: Any]] else {
        print("Invalid response format")
        return
    }

    for searchItem in searchResults {
        if let title = searchItem["title"] as? String,
           let snippet = searchItem["snippet"] as? String {
            print("\(title): \(snippet)")
        }
    }
}

// Perform a tokenized POST (automatically fetches token and includes it)
let editParams = [
    "action": "edit",
    "title": "User:Example/Sandbox",
    "text": "Hello from Wikipedia iOS!",
    "summary": "Test edit from iOS app",
    "format": "json"
]

fetcher.performTokenizedMediaWikiAPIPOST(tokenType: .csrf, to: wikiURL, with: editParams, cancellationKey: nil) { (result, response, error) in
    if let error = error {
        print("Edit failed: (error.localizedDescription)")
        return
    }

    guard let result = result,
          let edit = result["edit"] as? [String: Any],
          let editResult = edit["result"] as? String else {
        print("Invalid edit response")
        return
    }

    if editResult == "Success" {
        print("Edit saved successfully")
    } else {
        print("Edit failed: \(editResult)")
    }
}

// Cancel a tracked request
fetcher.cancelTask(for: cancellationKey)

```

--------------------------------

### Swift Configuration Management for Wikimedia Services

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

Demonstrates how to use the `Configuration` class in Swift to manage environment-specific settings for the Wikipedia iOS application. This includes building URLs for MediaWiki APIs, Page Content Service, Commons API, and handling custom staging configurations. It also shows how to check if a host should be routed to an in-app web view.

```swift
import Foundation

// Placeholder for the Configuration class definition
class Configuration {
    static let current: Configuration = Configuration()
    static func staging(options: [StagingOption] = []) -> Configuration { return Configuration() }
    func mediaWikiAPIURLForURL(_ siteURL: URL, with params: [String: String]) -> URL? { return URL(string: "https://example.com/api.php") }
    func pageContentServiceAPIURLForURL(_ articleURL: URL, appending pathComponents: [String]) -> URL? { return URL(string: "https://example.com/page/mobile-html") }
    func pageContentServiceHeaders(for url: URL) -> [String: String] { return [:] }
    func hostCanRouteToInAppWebView(_ host: String) -> Bool { return false }
    func commonsAPIURLComponents(with params: [String: String]) -> URLComponents { return URLComponents() }
}

enum StagingOption {
    case betaCluster
}

// Access the current configuration (automatically set based on build scheme)
let config = Configuration.current

// Build a MediaWiki API URL for a specific wiki
let queryParams = [
    "action": "query",
    "list": "search",
    "srsearch": "iOS development",
    "format": "json"
]
let siteURL = URL(string: "https://en.wikipedia.org")!
let apiURL = config.mediaWikiAPIURLForURL(siteURL, with: queryParams)
print("MediaWiki API URL: \(apiURL?.absoluteString ?? "nil")")

// Build a Page Content Service URL for article content
let articleURL = URL(string: "https://en.wikipedia.org/wiki/Swift_(programming_language)")!
let pcsURL = config.pageContentServiceAPIURLForURL(articleURL, appending: ["page", "mobile-html", "Swift_(programming_language)"])
print("Page Content Service URL: \(pcsURL?.absoluteString ?? "nil")")

// Get appropriate headers for PCS requests
let headers = config.pageContentServiceHeaders(for: articleURL)
print("PCS Headers: \(headers)")

// Check if a host should route to in-app web view
if config.hostCanRouteToInAppWebView("meta.wikimedia.org") {
    print("Routing to in-app web view.")
} else {
    print("Opening in Safari.")
}

// Create custom staging configuration
let stagingConfig = Configuration.staging(options: [.betaCluster])
let betaURL = stagingConfig.mediaWikiAPIURLForURL(URL(string: "https://en.wikipedia.beta.wmcloud.org")!, with: queryParams)
print("Beta Cluster MediaWiki API URL: \(betaURL?.absoluteString ?? "nil")")

// Build Commons API URL for image uploads
let commonsParams = [
    "action": "query",
    "titles": "File:Example.jpg",
    "prop": "imageinfo",
    "format": "json"
]
let commonsURL = config.commonsAPIURLComponents(with: commonsParams).url
print("Commons API URL: \(commonsURL?.absoluteString ?? "nil")")

```

--------------------------------

### Build MediaWiki API URLs with Swift

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

Constructs URLs for the MediaWiki API. This is useful for accessing general Wikipedia data beyond the RESTBase services. It takes query parameters as a dictionary.

```swift
import Foundation

// Build MediaWiki API URLs
let mediaWikiBuilder = APIURLComponentsBuilder.MediaWiki.BuilderType.production.builder(withWikiHost: "en.wikipedia.org")
let apiParams: [String: Any] = [
    "action": "parse",
    "page": "Main_Page",
    "prop": "text",
    "format": "json"
]
let mediaWikiComponents = mediaWikiBuilder.components(queryParameters: apiParams)
let mediaWikiURL = mediaWikiComponents.url
// Returns: https://en.wikipedia.org/w/api.php?action=parse&page=Main_Page&prop=text&format=json
```

--------------------------------

### Upload App Store Metadata (iOS)

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/fastlane/README.md

Uploads metadata for the iOS application to the App Store using fastlane. This command requires fastlane to be installed and configured. The `bundle exec` prefix is optional and used when managing dependencies with Bundler.

```shell
[bundle exec] fastlane ios upload_app_store_metadata
```

--------------------------------

### Initialize and Access MWKDataStore and Related Components

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

This snippet shows how to access the shared MWKDataStore instance and its associated networking components like session and configuration. It also demonstrates fetching an article from Core Data and creating or fetching an article, updating its properties, and saving changes.

```swift
import Foundation
import CoreData

// Access shared data store
let dataStore = MWKDataStore.shared()

// Access networking components
let session = dataStore.session
let configuration = dataStore.configuration

// Fetch article from Core Data
if let article = dataStore.fetchArticleWithURL(URL(string: "https://en.wikipedia.org/wiki/iPhone")!) {
    print("Article title: (article.displayTitle ?? "")")
    print("Saved: (article.isSaved)")
    print("View count: (article.viewedDate != nil ? "viewed" : "not viewed")")
} else {
    print("Article not in database")
}

// Create or fetch article
let articleURL = URL(string: "https://en.wikipedia.org/wiki/Swift_(programming_language)")!
if let article = dataStore.fetchOrCreateArticleWithURL(articleURL) {
    article.displayTitle = "Swift (programming language)"
    article.viewedDate = Date()

    // Save changes
    do {
        try dataStore.save()
        print("Article saved successfully")
    } catch {
        print("Failed to save: (error.localizedDescription)")
    }
}
```

--------------------------------

### Localize String in Objective-C - Wikipedia iOS

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/docs/localization.md

This Objective-C function `WMFLocalizedStringWithDefaultValue` is used for localizing strings, similar to `NSLocalizedStringWithDefaultValue`. It allows specifying an optional `siteURL` to localize the string to the language of the Wikipedia site associated with the URL. Bundle should always be nil. Used for getting strings localized to the user's system default locale or a specific site's language.

```objc
WMFLocalizedStringWithDefaultValue(
	@"article-about-title",
	nil,
	nil,
	@"About this article",
	@"The text that is displayed before the 'about' section at the bottom of an article"
);
```

```objc
WMFLocalizedStringWithDefaultValue(
	@"article-about-title",
	siteURL,
	nil,
	@"About this article",
	@"The text that is displayed before the 'about' section at the bottom of an article"
);
```

```objc
[NSString localizedStringWithFormat:
	WMFLocalizedStringWithDefaultValue(
		@"places-filter-saved-articles-count",
		nil,
		nil,
		@"{{PLURAL:%1$d|0=No saved places|%1$d place|%1$d places}} found",
		@"Describes how many saved articles are found in the saved articles filter - %1$d is replaced with the number of articles"
	),
	savedCount
]
```

--------------------------------

### Create Symlink for Objective-C Header in WMFComponentsObjC

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/WMFComponents/Sources/WMFComponentsObjC/README.md

This command creates a symbolic link (symlink) to an Objective-C header file within the WMFComponentsObjC directory. This is a crucial step to make the header file accessible from the include directory, enabling its use in Swift. Ensure you are in the correct directory before executing this command.

```bash
cd WMFComponentsObjC
ln -s ../WMFSourceEditorFormatterBoldItalic.h include/WMFSourceEditorFormatterBoldItalic.h
```

--------------------------------

### Build RESTBase API URLs with Swift

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

Constructs URLs for RESTBase API endpoints such as page summaries and mobile HTML. It allows specifying the environment (production, staging, local) and the wiki host. The builder can append path components or use query parameters.

```swift
import Foundation

// Build RESTBase API URLs (Page Content Service, Wikifeeds)
let restBaseBuilder = APIURLComponentsBuilder.RESTBase.BuilderType.production.builder(withWikiHost: "en.wikipedia.org")

// Build article summary endpoint URL
let summaryComponents = restBaseBuilder.components(byAppending: ["page", "summary", "Swift_(programming_language)"])
let summaryURL = summaryComponents.url
// Returns: https://en.wikipedia.org/api/rest_v1/page/summary/Swift_(programming_language)

// Build mobile-html endpoint URL
let mobileHTMLComponents = restBaseBuilder.components(byAppending: ["page", "mobile-html", "iPhone"])
let mobileHTMLURL = mobileHTMLComponents.url
// Returns: https://en.wikipedia.org/api/rest_v1/page/mobile-html/iPhone

// Build feed content endpoint URL
let feedComponents = restBaseBuilder.components(byAppending: ["feed", "featured", "2024", "01", "15"])
let feedURL = feedComponents.url
// Returns: https://en.wikipedia.org/api/rest_v1/feed/featured/2024/01/15

// Staging environment for Apps Labs
let stagingBuilder = APIURLComponentsBuilder.RESTBase.BuilderType.stagingAppsLabsPCS.builder(withWikiHost: "en.wikipedia.org")
let stagingComponents = stagingBuilder.components(byAppending: ["page", "summary", "Test"])
let stagingURL = stagingComponents.url
// Returns: https://mobileapps.wmflabs.org/en.wikipedia.org/v1/page/summary/Test

// Local development environment
let localBuilder = APIURLComponentsBuilder.RESTBase.BuilderType.localPCS.builder(withWikiHost: "en.wikipedia.org")
let localComponents = localBuilder.components(byAppending: ["page", "mobile-html", "Test"])
let localURL = localComponents.url
// Returns: http://localhost:8888/en.wikipedia.org/v1/page/mobile-html/Test

// Build URL with JSON payload in query string
let payload: NSDictionary = [
    "titles": ["Article_1", "Article_2", "Article_3"],
    "format": "json"
]
do {
    let payloadComponents = try restBaseBuilder.components(byAssigningPayloadToPercentEncodedQuery: payload)
    let payloadURL = payloadComponents.url
    print("Payload URL: \(payloadURL?.absoluteString ?? \"")")
} catch {
    print("Failed to encode payload: \(error.localizedDescription)")
}
```

--------------------------------

### Fetch Wikipedia Article Data with ArticleFetcher in Swift

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

Demonstrates how to initialize and use the ArticleFetcher class to retrieve different types of content for a Wikipedia article. It covers fetching summaries, mobile HTML for offline reading, media lists, offline resources, and references, including error handling for common issues like non-existent articles.

```swift
import Foundation

// Initialize article fetcher
let dataStore = MWKDataStore.shared()
let articleFetcher = ArticleFetcher(session: dataStore.session, configuration: dataStore.configuration)

// Fetch article summary
let articleURL = URL(string: "https://en.wikipedia.org/wiki/Swift_(programming_language)")!
let summaryRequest = articleFetcher.urlRequestForEndpoint(.summary, articleURL: articleURL)

articleFetcher.fetchArticleSummary(with: summaryRequest) { result in
    switch result {
    case .success(let summary):
        print("Title: (summary.displayTitle ?? "")")
        print("Extract: (summary.extract ?? "")")
        print("Thumbnail URL: (summary.thumbnailURL?.absoluteString ?? "none")")
        print("Coordinates: (summary.coordinate?.latitude ?? 0), (summary.coordinate?.longitude ?? 0)")
    case .failure(let error):
        if case ArticleFetcherError.doesNotExist = error {
            print("Article does not exist")
        } else {
            print("Fetch failed: (error.localizedDescription)")
        }
    }
}

// Fetch mobile HTML for offline reading
let mobileHTMLRequest = articleFetcher.urlRequestForEndpoint(.mobileHTML, articleURL: articleURL)
articleFetcher.fetchMobileHTML(with: mobileHTMLRequest, type: .contentAndReferences) { result in
    switch result {
    case .success(let htmlData):
        if let htmlString = String(data: htmlData, encoding: .utf8) {
            print("Received HTML content, size: (htmlData.count) bytes")
            // Process HTML for display in web view
        }
    case .failure(let error):
        print("HTML fetch failed: (error.localizedDescription)")
    }
}

// Fetch article media list (images, videos)
let mediaListRequest = articleFetcher.urlRequestForEndpoint(.mediaList, articleURL: articleURL)
articleFetcher.fetchMediaListURLs(with: mediaListRequest) { result in
    switch result {
    case .success(let mediaItems):
        print("Found (mediaItems.count) media items")
        for item in mediaItems {
            print("Image: (item.imageTitle)")
            print("URL: (item.imageURL.absoluteString)")
        }
    case .failure(let error):
        print("Media list fetch failed: (error.localizedDescription)")
    }
}

// Fetch offline resources for an article
let offlineRequest = articleFetcher.urlRequestForEndpoint(.mobileHtmlOfflineResources, articleURL: articleURL)
articleFetcher.fetchOfflineResources(with: offlineRequest) { result in
    switch result {
    case .success(let resources):
        print("Received offline resources: (resources)")
        // Save resources for offline access
    case .failure(let error):
        print("Offline resources fetch failed: (error.localizedDescription)")
    }
}

// Fetch article references
let referencesRequest = articleFetcher.urlRequestForEndpoint(.references, articleURL: articleURL)
articleFetcher.fetchReferences(with: referencesRequest) { result in
    switch result {
    case .success(let references):
        print("Found (references.count) references")
        for (index, reference) in references.enumerated() {
            print("[\(index + 1)] (reference)")
        }
    case .failure(let error):
        print("References fetch failed: (error.localizedDescription)")
    }
}

```

--------------------------------

### MediaWiki API URLs

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

Constructs URLs for the MediaWiki API, allowing for complex query parameters.

```APIDOC
## Building MediaWiki API URLs

### Description
This section explains how to generate URLs for the MediaWiki API, including specifying query parameters.

### Method
`APIURLComponentsBuilder.MediaWiki.BuilderType.production.builder(withWikiHost: String).components(queryParameters: [String: Any]).url`

### Endpoint
Constructs URLs like `https://<wiki_host>/w/api.php?key1=value1&key2=value2`

### Parameters
- `wikiHost` (String) - Required - The hostname of the Wikipedia wiki (e.g., "en.wikipedia.org").
- `queryParameters` ([String: Any]) - Required - A dictionary of key-value pairs representing the MediaWiki API query parameters.

### Request Example
```swift
let mediaWikiBuilder = APIURLComponentsBuilder.MediaWiki.BuilderType.production.builder(withWikiHost: "en.wikipedia.org")
let apiParams: [String: Any] = [
    "action": "parse",
    "page": "Main_Page",
    "prop": "text",
    "format": "json"
]
let mediaWikiComponents = mediaWikiBuilder.components(queryParameters: apiParams)
let mediaWikiURL = mediaWikiComponents.url
// Returns: https://en.wikipedia.org/w/api.php?action=parse&page=Main_Page&prop=text&format=json
```

### Response
#### Success Response (200)
- `url` (URL?) - The constructed URL object.

#### Response Example
```
https://en.wikipedia.org/w/api.php?action=parse&page=Main_Page&prop=text&format=json
```
```

--------------------------------

### POST Form Data for Login and Manage Authentication Cookies using Swift Session

Source: https://context7.com/wikimedia/wikipedia-ios/llms.txt

This snippet shows how to log in to Wikipedia's API using a POST request with form-encoded data and manage authentication cookies. It includes sending login credentials, checking for successful login, cloning CentralAuth cookies for cross-wiki access, verifying user login status, and clearing all cookies for logout. Dependencies: Foundation, Wikipedia's `Session` class.

```swift
import Foundation

// Assume session is already initialized as shown in the GET example
let config = Configuration.current
let session = Session(configuration: config)

// POST form data to MediaWiki API
let loginURL = URL(string: "https://en.wikipedia.org/w/api.php")!
let bodyParams = [
    "action": "login",
    "lgname": "username",
    "lgpassword": "password",
    "lgtoken": "token_value",
    "format": "json"
]

session.postFormEncodedBodyParametersToURL(to: loginURL, bodyParameters: bodyParams, reattemptLoginOn401Response: false) { (result, response, error) in
    if let result = result,
       let login = result["login"] as? [String: Any],
       let resultStatus = login["result"] as? String {
        if resultStatus == "Success" {
            // Clone CentralAuth cookies to other wiki domains
            session.cloneCentralAuthCookies()
            print("Login successful")
        } else {
            print("Login failed: (resultStatus)")
        }
    }
}

// Check authentication status
if session.hasCentralAuthUserCookie() {
    let username = session.getCentralAuthUserCookie()
    print("Logged in as: (username ?? "unknown")")
}

// Validate cookies for a specific domain
let hasValidCookies = session.hasValidCentralAuthCookies(for: ".wikipedia.org")
if hasValidCookies {
    print("User has valid authentication cookies")
}

// Clear all cookies (logout)
session.removeAllCookies()
```

--------------------------------

### Run fastlane snapshot command

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/WikipediaUITests/README.md

This command initiates the screenshot-taking process using fastlane's snapshot action. It can be configured with specific languages and devices via command-line arguments. Debugging may sometimes require re-running this command.

```bash
bundle exec fastlane snapshot
bundle exec fastlane snapshot --skip_open_summary --languages "en,de" --devices "iPhone 5s,iPhone 6"
```

--------------------------------

### Debugging screenshot issues

Source: https://github.com/wikimedia/wikipedia-ios/blob/main/WikipediaUITests/README.md

Tips for debugging include setting breakpoints in tests, using `expr print(XCUIApplication().debugDescription)` to inspect the UI hierarchy, and utilizing the Accessibility Inspector. Disabling the 'main thread checker' may also resolve issues.

```swift
// When debugging, you can add sleep calls to pause execution
sleep(5) // Pauses for 5 seconds

// In Xcode console, after hitting a breakpoint:
// expr print(XCUIApplication().debugDescription)
```
Tokens:
Raw