Instructions for iOS

Configuring the library and rendering the first DivView

Setting up dependencies

Add a DivKit dependency to the project using one of the managers:

SPM: See the Package.swift file.

cocoapods: Add the following line to Podfile:

source 'https://github.com/divkit/divkit-ios.git'

You can find the latest library version on the releases page.

Creating DivKitComponents

Before creating a DivView, you need to set up its DivKitComponents dependencies. By default, you don't need to pass any parameters. You can find a list of parameters in the DivKitComponents.swift file. As a simplified example, let's take DivKitComponents by default.

let divkitComponents = DivKitComponents()

Preparing data before displaying in DivView

The layout in DivKit consists of two main blocks: templates and the card itself. They can come either separately or in a single JSON file.
For example, let's output a short piece of text to the screen:

let cardText = """
{
    "card": {
        "log_id": "text",
        "states": [
            {
                "state_id": 0,
                "div": {
                    "type": "text",
                    "text": "Hello, DivKit!"
                }
            }
        ]
    }
}
"""

You can use a dictionary ([String: Any]), a byte buffer (Data), or a root structure (DivData) as data sources for the card. DivView will subsequently convert these types to DivData. For simplicity, let's use Data.

private let jsonData: Data = """
  {
      "card": {
          "log_id": "text",
          "states": [
              {
                  "state_id": 0,
                  "div": {
                      "type": "text",
                      "text": "Hello, DivKit!"
                  }
              }
          ]
      }
  }
""".data(using: .utf8)!

Initializing DivView

let divView = DivView(divKitComponents: divkitComponents)
divView.setSource(DivViewSource(kind: .data(jsonData), cardId: "ExampleCard"))

cardId is a unique card ID that DivKit uses to group internal entities. It must be unique for each card.

To find out the expected size of the card when placing it, request the cardSize parameter from DivView.

divView.cardSize?.sizeFor(parentViewSize: parentViewSize)

If you've done everything correctly, you'll see "Hello, DivKit!" on the screen.

View an interactive example

To make the interface interactive, add action handling. For example, let's turn a text into an interactive button that will display a tooltip on tap.

JSON modification

DivKit deliberately doesn't have high-level entities, such as "product card" or "button". Any element can be a button. Let's change the "Hello, DivKit!" appearance and add a tap action:

View an interactive example

In the example, we changed the element's appearance: we added rounded corners and margins, changed the background and text color, added a tap animation, and changed the text position inside the View. And most importantly, we added a tap action:

    "actions": [
        {
            "log_id": "button_pressed",
            "url": "notification://show-toast?text=Hello%2C%20DivKit%21"
        }
    ]

Support for news actions at the code level on iOS

To handle new types of actions, you need to use your own DivUrlHandler implementation and add it to DivKitComponents.

class NotificationUrlHandler: DivUrlHandler {
  private let presentingViewController: UIViewController

  init(presentingViewController: UIViewController) {
    self.presentingViewController = presentingViewController
  }

  func handle(_ url: URL, sender: AnyObject?) {
    guard url.scheme == "notification", 
    let alertText = url.queryParamValue(forName: "text") else { return }
    let alert = UIAlertController(title: alertText, message: nil,
                                   preferredStyle: .alert)

    presentingViewController.present(alert, animated: true)
  }
}

Now you need to add NotificationUrlHandler to DivKitComponents:

    let urlHandler = NotificationUrlHandler(presentingViewController: self)
    let divkitComponents = DivKitComponents(urlHandler: urlHandler)

This is the way you can influence not only the state of the card itself, but also the entire app from the JSON layout.

Learn more

Follow DivKit news in the Telegram channel: http://t.me/divkit_news

You can also discuss topics of interest in the DivKit user community in Telegram: https://t.me/divkit_community_ru

DivKit Repository