DEV Community: William Kennedy

Video: Up and Running with Turbo Android

William Kennedy — Fri, 18 Aug 2023 00:00:00 +0000

Video: Up and Running with Turbo Android - Part 2

William Kennedy — Fri, 18 Aug 2023 00:00:00 +0000

Tidy Up Your Views with Request Variants

William Kennedy — Wed, 02 Aug 2023 00:00:00 +0000

When I gave my recent Turbo Native talk for Ruby Ireland, one of the questions that came up repeatedly was about duplicating views for both native and Rails. I got many questions asking if I have “if-else” logic in my views to accommodate mobile.

This was an understandable question because many teams use Rails to serve JSON over the network instead of HTML. Turbo Native is a whole new world because it accommodates HTML. I use request variants to make my views easier to understand for mobile-specific reasons.

What is a Request Variant

A variant tells Rails to look for template variations of the same format. For example, let’s say we have a file called app/views/books/index.html.erb.

When we navigate to /books, it will render the default file. However, let’s say we create the same file but with a variation at the end of the name called app/views/books/index.html+phone.erb

Now if we do the following in our controller, it will render the +phone template instead of the template with no variation:

def index
  request.variant = :phone
end

In the Real World

For those lucky enough to be Jumpstart Pro users, this is built in.

I use variants to hide partials from the mobile app for my workout builder app, Smart Strength. For example, the footer appears on the website but disappears on the mobile app.

I have two files, footer.html.erb, which you see on the Smart Strength website, and footer.html+native.erb, which is a blank file.

This allows me to avoid having lots of logic in my views.

Using Request Variants with Existing Apps

Since Hotwire arrived, many companies with existing Rails apps have wanted to build a native app the Basecamp way but do not have the Turbo JS library installed.

Existing apps may also have the following challenges:

Existing JavaScript doesn’t work with Turbo(or requires a lot of work)
Few tests(more common than I would like)
- Lack a budget for a full-native app
- committed to certain patterns

Request variants can bypass many of these issues when we create a variant for our layouts.

Simply creating an application.layout.html+phone.erballows us to add turbo.js to that layout only and build from there. This means we could have Turbo.js exist side-by-side without worrying about interfering with the existing Rails app.

This approach is how I converted a recent application to use Turbo Native.

Debugging Request Variants

One of the problems that can arise with request variants is debugging. If your team has a designer and they would like to design the mobile views for your native app, then you will have to teach them how to trigger request variants. If you are using Chrome:

Open Inspect Element > Three Dots > More Tools and Change User Agent to Turbo Native.

When you refresh the browser, this will trigger the requested variant.

This is how I help teams get involved early on to show how they contribute to the mobile app. This helps break down barriers between mobile, design, and development teams.

Turbo Native - Native Authentication Part 3 - Android Client

William Kennedy — Mon, 17 Jul 2023 00:00:00 +0000

In this series’s previous two blog posts, we covered setting up a Rails app and an iOS app. In this article, we’re going to do the same for Android. The code can be seen here.

The approach for the Turbo Android app is the same as the Turbo iOS app.

When a user is unauthenticated, we return a 401 status code. We intercept that error and display a native sign-in flow in our iOS app.

Initial Setup

First, we can set up our app as per this blog post. However, instead of setting up No Activity, set up an Empty Activity, which will install all the Jetpack compose libraries.

We then add our Turbo library and the okhttp3 library in the Gradle file.

// hotwire
implementation "dev.hotwire:turbo:7.0.0-rc18"

// okhttp3
implementation("com.squareup.okhttp3:okhttp:4.10.0")

After that, press the sync button to install all our dependencies.

Create a SignInFragment

With everything set up, we next need to trigger a native flow every time a user visits /sign_in or a page that returns a 401 unauthorised status.

The first thing we will do is create our SignInFragment.

private const val AUTH_TOKEN_KEY = "auth_token"
private const val SHARED_PREFS_NAME = "turbo_native_auth"

@TurboNavGraphDestination(uri = "turbo://fragment/sign_in")
class SignInFragment : TurboFragment(), TurboNavDestination {

  override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
    return ComposeView(requireContext()).apply {
      setContent {
        AppTheme {
          SignInForm()
        }
      }
    }
  }

  @OptIn(ExperimentalMaterial3Api::class)
    @Composable
    fun SignInForm() {
      var email by remember { mutableStateOf("") }
      var password by remember { mutableStateOf("") }

      val context = LocalContext.current

        Column(
            modifier = Modifier
            .padding(16.dp)
            .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.Center
            ) {
          TextField(
              value = email,
              onValueChange = { newText ->
              email = newText.trimEnd()
              },
              label = { Text("Email") },
              modifier = Modifier.fillMaxWidth()
              )
            Spacer(modifier = Modifier.height(8.dp))
            TextField(
                value = password,
                onValueChange = { password = it },
                label = { Text("Password") },
                visualTransformation = PasswordVisualTransformation(),
                modifier = Modifier.fillMaxWidth()
                )
            Spacer(modifier = Modifier.height(16.dp))
            Button(
                onClick = { performSignIn(context, email, password) },
                modifier = Modifier.align(Alignment.End)
                ) {
              Text("Sign In")
            }
        }
    }
}

We then add this to our list of registered fragments in our MainSessionNavHost.

val BASE_URL = "http://10.0.2.2:3005"
val SIGN_IN_URL = "${BASE_URL}/sign_in"
val PATH_CONFIGURATION_URL = "${BASE_URL}/turbo/android/path_configuration"
val API_SIGN_IN_URL = "${BASE_URL}/api/v1/sessions"

class MainSessionNavHost : TurboSessionNavHostFragment() {
  override var sessionName = "main"
    override var startLocation = BASE_URL

    override val registeredFragments: List<KClass<out Fragment>>
    get() = listOf(
        WebFragment::class,
        WebModalFragment::class,
        SignInFragment::class
        )

    override val registeredActivities: List<KClass<out AppCompatActivity>>
    get() = listOf()

    override val pathConfigurationLocation: TurboPathConfiguration.Location
    get() = TurboPathConfiguration.Location(
        assetFilePath = "json/path_configuration.json",
        remoteFileUrl = PATH_CONFIGURATION_URL
        )
}

Update Path Configuration

Now, we update our path_configuration file so our native fragment gets displayed. Just like turbo-ios, turbo-android relies heavily on path configuration. We can get a file from the server and save one locally. For this project, our path configuration file looks like the following:

{
  "settings": {
    "screenshot_enabled": true
  },
    "rules": [
    {
      "patterns": [
        ".*"
      ],
      "properties": {
        "context": "default",
        "uri": "turbo://fragment/web",
        "pull_refresh_enabled": true
      }
    },
    {
      "patterns": [
        "/new$",
      "/edit$"
      ],
      "properties": {
        "context": "modal",
        "uri": "turbo://fragment/web/modal/sheet",
        "pull_to_refresh_enabled": false
      }
    },
    {
      "patterns": [
        "/sign_in$"
      ],
      "properties": {
        "context": "default",
        "uri": "turbo://fragment/sign_in",
        "pull_refresh_enabled": false
      }
    }
  ]
}

Just like that, every time we navigate to sign_in, we display a native sign-in form. However, it doesn’t do much yet. We still need to be able to send requests and save the cookies and auth token.

Native Sign in

For our iOS application, we saved our authentication token to the keychain to be held securely and retrieved in other parts of the application via a getter method.

For the Android application, we will use the Shared Preferences api.

private fun getAuthToken(context: Context): String? {
  val sharedPreferences = context.getSharedPreferences(SHARED_PREFS_NAME, Context.MODE_PRIVATE)
    return sharedPreferences.getString(AUTH_TOKEN_KEY, null)
}

This method retrieves the AuthToken if we need to make an API request.

We also need to be able to write the token to our shared preferences.

private fun saveAuthToken(context: Context, authToken: String?) {
  val sharedPreferences = context.getSharedPreferences(SHARED_PREFS_NAME, Context.MODE_PRIVATE)
    sharedPreferences.edit().putString(AUTH_TOKEN_KEY, authToken).apply()
}

Finally, we have to save our cookies.

private fun saveCookies(cookies: List<String>) {
  val cookieManager = CookieManager.getInstance()

    for (cookie in cookies) {
      parse(API_SIGN_IN_URL.toHttpUrlOrNull()!!, cookie)?.let {
        cookieManager.setCookie(API_SIGN_IN_URL, it.toString())
      }
    }
}

Now we can add all call all these methods from our performSignIn method in the SignInFragment:

private fun performSignIn(context: Context, email: String, password: String) {
  val client = OkHttpClient()

    val requestBody = FormBody.Builder()
    .add("email", email)
    .add("password", password)
    .build()

    val request = Request.Builder()
    .url(API_SIGN_IN_URL)
    .post(requestBody)
    .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
        // Handle network failure or API error
        }

        override fun onResponse(call: Call, response: Response) {
        if (response.isSuccessful) {
        val authToken = response.header("X-Session-Token")
        val cookies = response.headers("Set-Cookie")

        saveAuthToken(context, authToken)
        saveCookies(cookies)

        // execute on the main thread
        requireActivity().runOnUiThread {
        navigateUp()
        sessionNavHostFragment.reset()
        }

        } else {
        // Raise error
        }
        }
    })
}

Since this is an async request, you must ask Turbo Android to navigate back to the previous page.

// execute on the main thread
requireActivity().runOnUiThread {
  navigateUp()
    sessionNavHostFragment.reset()
}

Handling a 401 error.

So now we should be able to spin up our Android app and sign in and out.

The next thing we need to do is handle the 401 unauthorised errors.

In our WebFragment, we can override the onVisitErrorReceived method and navigate to our sign-in fragment.

override fun onVisitErrorReceived(location: String, errorCode: Int) {
  when (errorCode) {
    401 -> navigate(SIGN_IN_URL, TurboVisitOptions(action = REPLACE))
      else -> super.onVisitErrorReceived(location, errorCode)
  }
}

Unauthorised modal

In our example app, when we navigate to /new, a WebModalFragment is displayed. I could not figure out how to dismiss it and then navigate to the SignInFragment, so I handled the case where there was a 401 error.

By overriding the createErrorView, we can inject our own.

@TurboNavGraphDestination(uri = "turbo://fragment/web/modal/sheet")
class WebModalFragment: TurboWebBottomSheetDialogFragment(), TurboNavDestination {

  @SuppressLint("InflateParams")
    override fun createErrorView(statusCode: Int): View {
      when (statusCode) {
        401 -> return layoutInflater.inflate(R.layout.turbo_auth_error, null)
          else -> return super.createErrorView(statusCode)
      }
    }
}

The customer error layout informs the user that they are not logged in, so they can dismiss and log in. Not a perfect flow, but it works for now.

Turbo Android is an excellent library for quickly building hybrid apps. As you can see, utilising native for specific scenarios is straightforward. It’s simply a matter of creating and adding the fragment to our list of registered fragments.

Conquering iOS, Android and Web with Hotwire

William Kennedy — Wed, 12 Jul 2023 00:00:00 +0000

Turbo Native Authentication Part 2 - IOS Client

William Kennedy — Mon, 03 Jul 2023 00:00:00 +0000

The source code can be found here.

Now that we have our Rails backend, we can start working on our Turbo Native apps. First up is iOS. This post will touch on different parts of building a typical iOS app. We will use an established iOS design pattern called the Coordinator pattern to navigate between screens. First, we’ll get our App up and running, then implement native authentication, and finally, we’ll wrap up with some bonus content.

Intro

We are going to set up our App using the Coordinator pattern. This pattern encapsulates our navigation behaviour. It works by keeping a stack of child coordinators, and depending on the logic in the App, we push or pop a coordinator.

It won’t be my favourite pattern, but doing everything using UIViewControllers quickly became a mess, and this is recommended way in iOS. I’ve written about setting coordinators up previously in this blog post about rendering a native screen with turbo-ios, but it would be good to run through everything here as well.

Set up packages

Open Xcode and create a new app.

For the template, choose App; for the Interface, select Storyboard.

Ensure you have the turbo-ios and KeychainAccess packages.

These can be added via File > Add Package > Enter Package name.

Keychain access makes encrypting sensitive information on the user’s keychain easier.

Set up our Parent Coordinator

Create a new group called Coordinators, then create a new file named Coordinator.swift.

import UIKit

class Coordinator: NSObject, UINavigationControllerDelegate {

  var didFinish: ((Coordinator) -> Void)?

  var childCoordinators: [Coordinator] = []

  // MARK: - Methods

  func start() {}

  func navigationController(_ navigationController: UINavigationController, willShow viewController: UIViewController, animated: Bool) {}

  func pushCoordinator(_ coordinator: Coordinator) {
    // Install Handler
    coordinator.didFinish = { [weak self] (Coordinator) in
      self?.popCoordinator(coordinator)
    }

    // Start Coordinator
    coordinator.start()

    // Append to Child Coordinators
    childCoordinators.append(coordinator)
  }

  func popCoordinator(_ coordinator: Coordinator) {
    // Remove Coordinator From Child Coordinators
    if let index = childCoordinators.firstIndex(where: { $0 === coordinator }) {
      childCoordinators.remove(at: index)
    }
  }

  func isPresentingModal(viewController: UIViewController) -> Bool {
      return viewController.presentedViewController != nil
  }

}

This is the parent Coordinator, and every subsequent Coordinator inherits from this.

Set up our Turbo Coordinator

Next, create a coordinator to handle our Sessions object. Session are how turbo-ios handles navigation within the webview.

If you are copying/pasting, note that my baseURL is localhost:3005, not 3000.

import Foundation
import Turbo
import UIKit
import SafariServices
import WebKit

class TurboSessionCoordinator: Coordinator {
    var didAuthenticate: (() -> Void)?
    let baseURL = URL(string: "http://localhost:3005/")!
    var rootViewController: UIViewController {
        return navigationController
    }

    var resetApp: (() -> Void)?

    override func start() {
        visit(url: baseURL)
    }

    private let navigationController = UINavigationController()
    private lazy var session = makeSession()
    private lazy var modalSession = makeSession()

    private func makeSession() -> Session {
        let session = Session()
        session.webView.customUserAgent = "My App (Turbo Native) / 1.0"
        session.delegate = self
        let pathConfiguration = PathConfiguration(sources: [
            .file(Bundle.main.url(forResource: "path_configuration", withExtension: "json")!),
            .server(baseURL.appending(path: "/turbo/ios/path_configuration"))
        ])
        session.pathConfiguration = pathConfiguration
        return session
    }

    private func visit(url: URL, action: VisitAction = .advance, properties: PathProperties = [:]) {
        let viewController = makeViewController(for: url, from: properties)
        let modal = properties["presentation"] as? String == "modal"
        let action: VisitAction = url == session.topmostVisitable?.visitableURL ? .replace : action
        navigate(to: viewController, via: action, asModal: modal)
        visit(viewController, as: modal)
    }

    private func makeViewController(for url: URL, from properties: PathProperties) -> UIViewController {
        return VisitableViewController(url: url)
    }

    private func navigate(to viewController: UIViewController, via action: VisitAction, asModal modal: Bool) {
        if modal {
            navigationController.present(viewController, animated: true)
        } else if action == .advance {
            navigationController.pushViewController(viewController, animated: true)
        } else if action == .replace {
            navigationController.dismiss(animated: true)
            navigationController.viewControllers = Array(navigationController.viewControllers.dropLast()) + [viewController]
        } else {
            navigationController.viewControllers = Array(navigationController.viewControllers.dropLast()) + [viewController]
        }
    }

    private func visit(_ viewController: UIViewController, as modal: Bool) {
        guard let visitable = viewController as? Visitable else { return }
        let session = modal ? modalSession : self.session
        session.visit(visitable)
    }
}

extension TurboSessionCoordinator: SessionDelegate {
    func session(_ session: Session, didProposeVisit proposal: VisitProposal) {
        visit(url: proposal.url, action: proposal.options.action, properties: proposal.properties)
    }

    func session(_ session: Session, didFailRequestForVisitable visitable: Visitable, error: Error) {
    // tackle this later
    }

    func sessionWebViewProcessDidTerminate(_ session: Session) {
        session.reload()
    }
}

Set up our Application Coordinator

This is the most essential part of our application because it starts all the child coordinators.

import Foundation
import UIKit

class ApplicationCoordinator: Coordinator {

    var rootViewController: UIViewController {
        return turboSessionCoordinatior.rootViewController
    }

    let turboSessionCoordinatior = TurboSessionCoordinator()

    override init() {
        super.init()

        childCoordinators.append(turboSessionCoordinatior)

    }

    override func start() {
        childCoordinators.forEach { (childCoordinator) in
            childCoordinator.start()
        }
    }

}

Next, in our SceneDelegate, we need to start our ApplicationCoordinator.

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?
    private let coordinator = ApplicationCoordinator()

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        // Use this method to configure and attach the UIWindow `window` to the provided UIWindowScene `scene` optionally.
        // If using a storyboard, the `window` property will automatically be initialized and attached to the scene.
        // This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession` instead).
        guard let windowScene = (scene as? UIWindowScene) else { return }
        let window = UIWindow(windowScene: windowScene)
        window.rootViewController = coordinator.rootViewController
        window.makeKeyAndVisible()
        self.window = window
        coordinator.start()
    }
 ....

Before we can press the run button, we need to set up a local path_configuration.json file, which can exist in the root of your iOS project. It can be the same as the one we created in the previous blog post.

{"rules":[
  {"patterns":["/new$","/edit$"],
  "properties": 
  {"presentation":"modal"}}
]}

If you press the run button right now, you will see that the App runs like that, and we have our beautiful Rails app inside.

It’s that magic that gets me every time.

A brief tour

Now, everything is up and running. However, let’s try and access a logged-in page.

Our server is returning a 401 unauthorised response. When navigating, our TurboSessionCoordinator is triggering the didFailRequestForVisitable.

Now we can work around this in several ways. For example, we can log in using a web form. However, we still get that white screen when we navigate to posts/new as a guest user.

The UX is less than ideal, and we can do much better by reacting to the 401 status code and pushing a new coordinator onto the stack. As a bonus, we can also retrieve an API token which will make it easier to render native views later on.

Setting up Native Authentication

Another coordinator handles native authentication. We plan to react to the 401 status and push the login view onto the stack.

Let’s start by creating our AuthCoordinator.

import Foundation
import UIKit
import SwiftUI

class AuthCoordinator: Coordinator {
    var didAuthenticate: (() -> Void)?

    private let navigationController: UINavigationController
    private let authViewController: UIHostingController<SignInView>
    private let viewModel: SignInViewModel

    init(navigationController: UINavigationController) {
        self.navigationController = navigationController
        self.viewModel = SignInViewModel()
        let newView = SignInView(viewModel: viewModel)
        self.authViewController = UIHostingController(rootView: newView)

    }

    override func start() {
        viewModel.didFinish = authenticate
        // Dismiss the current modal view controller

        if isPresentingModal(viewController: navigationController) {
            navigationController.dismiss(animated: false) {
                // Present the new view controller
                self.navigationController.present(self.authViewController, animated: true, completion: nil)
            }
        } else {
            navigationController.present(authViewController, animated: true)
        }

    }

    func authenticate() {
        didAuthenticate?()
        navigationController.dismiss(animated: true)
    }
}

Let’s run through this code a bit because it might be new if you are coming from a Ruby background.

var didAuthenticate: (() -> Void)?

The didAuthenticate closure or callback allows other parts of the code to be notified or informed when authentication has been completed. This closure can be assigned a value or function executed when authentication occurs. Invoking this closure can trigger any desired actions or code execution in response to the authentication event.

private let navigationController: UINavigationController
private let authViewController: UIHostingController<SignInView>

Our navigation controller is our main controller that controls what views or logic are rendered on the screen in UIKit. Our TurboSession coordinator’s root view controller is a navigation controller(you may have noticed already).

Next, we are diving into a UIHostingController<SignInView>, a simple way to allow us to drop into SwiftUI.

Finally, you’ll notice that we check for a modal that is being presented and dismiss any existing modal if they’re. This is because posts/new happens to be presented as a modal as configured by our PathConfiguration. UIKit does not allow multiple modals in this scenario.

Next, we must create a SignInView and a SignInViewModel to handle our auth flow.

Let’s create our SignInViewModel first.

import SwiftUI
import Foundation
import WebKit
import KeychainAccess

class SignInViewModel: ObservableObject {
    @Published var email: String = ""
    @Published var password: String = ""

    var didFinish: (() -> Void)?

    @MainActor
    func signIn() async {
        let url = URL(string: "http://localhost:3005/api/v1/sessions.json")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        let parameters = ["email": email, "password": password]
        request.httpBody = try? JSONSerialization.data(withJSONObject: parameters)

        let session = URLSession.shared
        let task = session.dataTask(with: request) { data, response, error in
            if let error = error {
                print("Error: \(error)")
                return
            }

            if let httpResponse = response as? HTTPURLResponse {
                if let cookies = HTTPCookieStorage.shared.cookies(for: url) {
                    HTTPCookieStorage.shared.setCookies(cookies, for: url, mainDocumentURL: nil)
                    self.saveCookies(cookies)
                }
                if let authToken = httpResponse.allHeaderFields["X-Session-Token"] as? String {
                    if let bundleIdentifier = Bundle.main.bundleIdentifier {
                        print("Bundle Identifier: \(bundleIdentifier)")
                        let keychain = Keychain(service: "\(bundleIdentifier).keychain")
                        keychain[string: "token"] = authToken
                        print("Token Headers: \(authToken)")
                    }
                    // Save token to keychain
                }
            }
        }
        didFinish?()
        task.resume()
    }

    private

    func saveCookies(_ cookies: [HTTPCookie]) {
        cookies.forEach { cookie in
            DispatchQueue.main.async {
                WKWebsiteDataStore.default().httpCookieStore.setCookie(cookie)
            }
        }
    }
}

The signIn method sends a web request and if successful, does two things. It saves cookies, and it saves an auth token to the keychain.

Finally, we’ll create our SignInView.

import SwiftUI

struct SignInView: View {
    @ObservedObject var viewModel: SignInViewModel

    var body: some View {
        Form {
            TextField("name@example.com", text: $viewModel.email)
                .textContentType(.username)
                .keyboardType(.emailAddress)
                .autocapitalization(.none)

            SecureField("password", text: $viewModel.password)
                .textContentType(.password)

            Button("Sign in") {
                Task {
                    await viewModel.signIn()
                }
            }
        }
    }
}

struct SignInView_Previews: PreviewProvider {
    static var previews: some View {
        SignInView(viewModel: SignInViewModel())
    }
}

Connect it to our TurboSessionCoordinator

Now that we have the AuthCoordinator setup let’s handle the earlier error we encountered.

In our didFailReuestForVisitable method found in the TurboSessionCoordinator extension, we add the following:

extension TurboSessionCoordinator: SessionDelegate {
    func session(_ session: Session, didProposeVisit proposal: VisitProposal) {
        visit(url: proposal.url, action: proposal.options.action, properties: proposal.properties)
    }

    func session(_ session: Session, didFailRequestForVisitable visitable: Visitable, error: Error) {
        if let turboError = error as? TurboError, case let .http(statusCode) = turboError, statusCode == 401 {

            let authCoordinator = AuthCoordinator(navigationController: navigationController)
            authCoordinator.didAuthenticate = didAuthenticate
            pushCoordinator(authCoordinator)
        } else {
            let alert = UIAlertController(title: "Visit failed!", message: error.localizedDescription, preferredStyle: .alert)
            alert.addAction(UIAlertAction(title: "OK", style: .default, handler: nil))
            navigationController.present(alert, animated: true)
        }
    }

    func sessionWebViewProcessDidTerminate(_ session: Session) {
        session.reload()
    }
}

When you rerun the App, you’ll see that before you visit /posts/new, you’ll be intercepted and have the chance to log in with the native login functionality.

There is still one last problem when we click the sign-in button; we display the web login and not the native login. Let’s change that quickly by first updating our path configuration file.

{
  "rules": [
    {
      "patterns": [
        "/new$",
        "/edit$"
      ],
      "properties": {
        "presentation": "modal"
      }
    },
    {
      "patterns": [
        "/sign_in$"
      ],
      "properties": {
        "presentation": "authentication"
      }
    }
  ]
}

Next, let’s capture this flow in our TurboCoordinator session. We update our visit function.

private func visit(url: URL, action: VisitAction = .advance, properties: PathProperties = [:]) {
        let viewController = makeViewController(for: url, from: properties)
        let modal = properties["presentation"] as? String == "modal"
        let action: VisitAction = url == session.topmostVisitable?.visitableURL ? .replace : action
        let auth = properties["presentation"] as? String == "authentication"
        if auth {
            let authCoordinator = AuthCoordinator(navigationController: navigationController)
            authCoordinator.didAuthenticate = didAuthenticate
            pushCoordinator(authCoordinator)
        } else {
            navigate(to: viewController, via: action, asModal: modal)
            visit(viewController, as: modal)
        }
    }

Conclusion

So there you have it. An approach to native authentication with Turbo IOS using the Coordinator pattern. There are other approaches, but I find something like this works for my needs.

The next blog post will tackle native authentication with Turbo Android.

Bonus - API endpoint

To access our API endpoint and render native screens, we can copy what we have done with our AuthCoordinator. We update our PathConfiguration to check for a ‘native’ flow and then push the new Coordinator onto the stack.

import UIKit
import SwiftUI

class PostCoordinator: Coordinator {
    var didAuthenticate: (() -> Void)?

    private let navigationController: UINavigationController
    private let postViewController: UIHostingController<PostView>
    private let viewModel: PostViewModel

    init(navigationController: UINavigationController) {
        self.navigationController = navigationController
        self.viewModel = PostViewModel()
        let view = PostView(viewModel: viewModel)
        self.postViewController = UIHostingController(rootView: view)
    }

    override func start() {
        navigationController.pushViewController(postViewController, animated: true)
    }

}


import Foundation
import SwiftUI
import Combine
import KeychainAccess

class PostViewModel: ObservableObject {
    @Published var isUpdating = false
    @Published var posts: [Post] = []

    var didFinish: (() -> Void)?

    @MainActor
    func fetchPosts() async {
        isUpdating = true
        var token = ""
        let url = URL(string: "http://localhost:3005/posts.json")!
        if let bundleIdentifier = Bundle.main.bundleIdentifier {
            print("Bundle Identifier: \(bundleIdentifier)")
            let keychain = Keychain(service: "\(bundleIdentifier).keychain")
            token = keychain[string: "token"] ?? ""
        } else {
            return
        }
        let config = URLSessionConfiguration.default
        config.waitsForConnectivity = true
        config.timeoutIntervalForResource = 60
        config.httpAdditionalHeaders = [
            "Authorization": "Bearer \(token)"
        ]
        print(token)

        var request = URLRequest(url: url)
        request.httpMethod = "GET"
        request.addValue("application/json", forHTTPHeaderField: "Content-Type")
        request.addValue("application/json", forHTTPHeaderField: "Accept")

        URLSession(configuration: config).dataTask(with: request) { data, response, error in
            if let error = error {
                print(error.localizedDescription)
            }

            if let data = data {
                let decoder = JSONDecoder()
                decoder.keyDecodingStrategy = .convertFromSnakeCase

                do {
                    let posts = try decoder.decode([Post].self, from: data)
                    DispatchQueue.main.async {
                        self.posts = posts
                        print(self.posts)
                        self.objectWillChange.send()
                    }
                } catch {
                    print(error)
                }
            }
        }.resume()

        isUpdating = false
    }

}


import SwiftUI

struct PostView: View {
    @ObservedObject var viewModel: PostViewModel

    var body: some View {
        NavigationStack {
            List {
                ForEach(viewModel.posts, id: \.id) { post in
                    Text(post.title)
                }
            }
        }
        .task {
                await viewModel.fetchPosts()
        }
    }

}

struct PostView_Previews: PreviewProvider {
    static var previews: some View {
        PostView(viewModel: PostViewModel())
    }
}

There are two more steps to implement the native screen, but I’ll leave that as an exercise for the reader ;).

Turbo Native Authentication Part 1 - Rails Backend

William Kennedy — Sun, 02 Jul 2023 00:00:00 +0000

In this Turbo Native series, we’re going to build native auth. Part 1 will cover the server side. Part 2 will cover Turbo iOS, and then we’ll end with Android.

Authentication is complicated. Not because it’s hard but because it’s scary.

The Rails app is just an example of getting up and running, but you may need to adjust for your security needs if you wish to run it on production.

The source code can be found here, and it exists as a template so you can clone it into your app. With some tweaks, the app builds off the authentication-zero gem, so we have API authentication and ordinary sign-in.

Initial Confusion

One of the parts I found confusing about authentication was this line in the docs.

For HEY, we have a slightly different approach. We get the cookies back along with our initial OAuth request and set those cookies directly to the web view and global cookie stores

This is not something I encountered before when using SPAs. When you are building a Rails backend with a SPA, I have only had experience with token-based authentication or cookie-based authentication. I have never done both.

With further ado, let’s dive in.

Rails Scaffold

First, we start with the traditional Rails scaffold.

rails new turbo_auth_rails --javascript=esbuild --css=tailwind --database=postgresql

Next, we add the gem authentication-zero to our Gemfile

Authentication Zero

bundle add authentication-zero

I then ran the following:

rails g authentication --pwned --passwordless --omniauthable && rake db:migrate

For the next part, I wanted to implement token based authentication.

class Api::V1::SessionsController < Api::ApplicationController
  skip_before_action :authenticate, only: :create

  before_action :set_session, only: %i[show destroy]

  def index
    render json: Current.user.sessions.order(created_at: :desc)
  end

  def show
    render json: @session
  end

  def create
    user = User.find_by(email: params[:email])

    if user && user.authenticate(params[:password])
      @session = user.sessions.create!
      response.set_header "X-Session-Token", @session.signed_id
      cookies.signed.permanent[:session_token] = { value: @session.id, httponly: true }

      render json: @session, status: :created
    else
      render json: { error: "That email or password is incorrect" }, status: :unauthorized
    end
  end

  def destroy
    @session.destroy
  end

  private
  def set_session
    @session = Current.user.sessions.find(params[:id])
  end
end

The controller exists in app/controllers/api/v1/sessions_controller.rb. The corresponding routes look like this.

namespace :api do
  namespace :v1 do
    resources :sessions, only: [:index, :create, :show, :destroy] 
  end
end

There are no views since everything renders JSON.

We set the response header in the controller and assign the cookies with the session id.

 response.set_header "X-Session-Token", @session.signed_id
 cookies.signed.permanent[:session_token] = { value: @session.id, httponly: true }

I then modified the API application controller generated by authentication-zero to the following:

class Api::ApplicationController < ActionController::API
  include ActionController::HttpAuthentication::Token::ControllerMethods
  include ActionController::Cookies

  before_action :set_current_request_details
  before_action :authenticate

  private
  def authenticate
    if session_record = authenticate_with_http_token { |token, _| Session.find_signed(token) }
      Current.session = session_record
    else
      request_http_token_authentication
    end
  end

  def set_current_request_details
    Current.user_agent = request.user_agent
    Current.ip_address = request.ip
  end
end

I also modified the main application controller:

class ApplicationController < ActionController::Base
  before_action :set_current_request_details
  before_action :authenticate

  def authenticate
    if authenticate_with_token || authenticate_with_cookies
      # Great! You're in
    elsif !performed?
      request_api_authentication || request_cookie_authentication
    end
  end

  def authenticate_with_token
    if session = authenticate_with_http_token { |token, _| Session.find_signed(token) }
      Current.session = session
    end
  end

  def authenticate_with_cookies
    if session = Session.find_by_id(cookies.signed[:session_token])
      Current.session = session
    end
  end

  def user_signed_in?
    authenticate_with_cookies || authenticate_with_token
  end

  helper_method :user_signed_in?


  def request_api_authentication
    request_http_token_authentication if request.format.json?
  end

  def request_cookie_authentication
    session[:return_path] = request.fullpath
    render 'sessions/new', status: :unauthorized, notice: "You need to sign in"
  end

  def set_current_request_details
    Current.user_agent = request.user_agent
    Current.ip_address = request.ip
  end
end

This checks if we either have a token or a cookie. We also return a 401 status code if a user is not logged in or needs to be authenticated.

Posts Scaffold

Let’s now build a scaffold.

rails g scaffold Post title:string content:rich_text && rails db:migrate

Not all styling is in the repo if you wish to copy and paste. You will need to copy the layout/application.html.erb file, the posts folder, and the sessions/new folder.

Finally, in our posts controller, we added the following:

class PostsController < ApplicationController
  before_action :authenticate, except: [:index, :show]

This will trigger a 401 status whenever a user tries to log in. This will be used to start a login on our Turbo iOS app in the next blog post.

Finally, let’s add a path_configuration route.

class Turbo::Ios::PathConfigurationsController < ApplicationController
  skip_before_action :authenticate

  def show
    render json: {
      rules: [
        {
          patterns: ["/new$", "/edit$"],
          properties: {
            presentation: "modal"
          }
        },
        {
          patterns: ["/sign_in$"],
          properties: {
            presentation: 'authentication'
          }
        }
      ]
    }
  end
end

Then we update our routes.rb file.

  namespace :turbo do
    namespace :ios do
      resource :path_configuration, only: [:show]
    end
  end

3 Useful Tricks When Working With Turbo Android

William Kennedy — Fri, 02 Jun 2023 00:00:00 +0000

Thanks for following along with my Turbo Android series. I’m going to finish up with some general tips.

1. Debugging the WebView

Sometimes you will want to debug via the webview. To do this, do the following:

Open Chrome and type in chrome://inspect in the URL bar

This URL will display every Chrome process allowing you to use the Chrome Development tools on your Turbo Native webview.

2. Keep 99% on the Server

Delegate to your server-side app as much as possible. It might be tempting to build many native screens, but only go native if necessary. By serving HTML over the wire, you can keep your app simply because you only have to make changes in one place.

You also benefit from making changes over the wire when you need without having to get your app approved by Apple.

Scenarios, where native performance is superior include maps and offline functionality. For example, Smart Strength’s workout builder is native because I want users to use swipe to delete/copy, SwiftUI Context Menu and more.

3. Variants

If you have a legacy app, you can use variants to render different pages for the same request.

In Rails, you can set the requested variant with the following code:

# application_controller.rb
before_action do
  request.variant = :native if turbo_native_app?
end

If you look at the turbo_native_app method in the source code, it just checks to see if there is a user agent string in called Turbo Native.

When you do that, you can create the same view but append html+native.erb

When you request, Rails will evaluate the agent string to decide what variant to display.

Let’s say you visit /posts

For normal web browsing, Rails will render index.html.erb, but if you are navigating from a Turbo Native app, it will render index.html+native.erb. If there is no variant, it falls back to the standard view. This means you can avoid lots of if turbo_native_app? statements in your views.

Bonus Trick: 4. Use Jumpstart Pro

If you can afford it, I would buy a Jumpstart Pro Android and iOS licence. This will save you a lot of development time, plus it comes with documentation and access to the GoRails Discord, where you ask questions. You will also learn a lot from the codebase.

Downsides

Every choice has trade-offs, and Turbo Native is no different.

You need to get comfortable with Turbo.js. It has garnered some fans and praise, but some don’t like it. Turbo Native hinges on the fact that you are going to use Turbo. If you plan to include lots of JS libraries in your project, write a small Stimulus/JQuery wrapper for each one and get used to listening for the custom Turbo events. However, the trade-off has proved worthwhile, especially compared to the previous approach.

How to Get Up and Running With Turbo Android Turbo Android Part 3 - How to Access Native Android Features with the JavaScript...

William Kennedy — Tue, 23 May 2023 00:00:00 +0000

Continuing from my previous post about accessing native screens from your hybrid web app, today, we’re going to talk about the Javascript bridge which is my favourite feature within the whole Turbo native ecosystem.

Why?

We can write the javascript we already know(and love/hate) to call native code. In previous projects, I’ve used this to delete native tokens, access permissions, and access a native SDK and in an earlier post, we’ve accessed the phone’s contacts database. In today’s post, we’ll be doing precisely that to demonstrate the power of Turbo Native.

Backend application

We will use the same backend application we’ve used for the last two articles, which you can find here. We’ve added some Javascript.

Here we’ve set up a JavaScript bridge to post messages to the Android client and send messages back.

// Entry point for the build script in your package.json
import "@hotwired/turbo-rails"
import "./controllers"

class Bridge {

  // Sends a message to the native app, if active.
  static postMessage(name, data = {}) {
    // iOS
    window.webkit?.messageHandlers?.nativeApp?.postMessage({name, ...data})

    // Android
    window.nativeApp?.postMessage(JSON.stringify({name, ...data}))
  }

  static importingContacts(name) {
    fetch('/contacts.json', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        "Accept": "application/json",
      },
      body: JSON.stringify({contact: { name } })
    }).then((response) => response.json())
      .then((data) => {
        console.log("Success:", data);
        var btn = document.querySelector('button')
        btn.textContent = `"Imported ${name}"`
      })
      .catch((error) => {
        console.error("Error:", error);
      });
  }
}

// Expose this on the window object so TurboNative can interact with it
window.Bridge = Bridge
export default Bridge

We’ve also created a stimulus controller that attaches to a button that posts that particular method.

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  import() {
    window.Bridge.postMessage("contacts", {name: "contacts"})
  }
}

Finally, in our view, we’ve connected the Stimulus controller to the button that will import the contacts.

<p style="color: green"><%= notice %></p>

<div class="mt-8 px-4 flex items-center justify-between">
  <div class="min-w-0 flex-1">
    <h1 class='h1'>Import Contacts</h1>
  </div>
</div>

<div data-controller='contacts' class='overflow-hidden rounded-md bg-white shadow mt-4 p-2'>

  <div class="text-center">
    <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
      <path vector-effect="non-scaling-stroke" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 13h6m-3-3v6m-9 1V7a2 2 0 012-2h6l2 2h6a2 2 0 012 2v8a2 2 0 01-2 2H5a2 2 0 01-2-2z" />
    </svg>
    <h3 class="mt-2 text-sm font-semibold text-gray-900">No contacts imported</h3>
    <p class="mt-1 text-sm text-gray-500">Get started by creating a new project.</p>
    <div class="mt-6">
      <button data-action='contacts#import' type="button" class="inline-flex items-center rounded-md bg-indigo-600 px-3 py-2 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600">
        <svg class="-ml-0.5 mr-1.5 h-5 w-5" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
          <path d="M10.75 4.75a.75.75 0 00-1.5 0v4.5h-4.5a.75.75 0 000 1.5h4.5v4.5a.75.75 0 001.5 0v-4.5h4.5a.75.75 0 000-1.5h-4.5v-4.5z" />
        </svg>
        Import Contacts
      </button>
    </div>
  </div>

  <ul class='divide-y divide-gray-200' id="contacts">
  </ul>
</div>

Pretty straightforward so far. Now let’s look and see what we’ve to do on the client side.

The Native Bridge

First, we create a new class that will act as our javascript interface and allow us to post javascript messages.

const val CONTACTS = "contacts"

class NativeJavaScriptInterface {

  var onContacts: () -> Unit = {}

  @Suppress("unused")
    @JavascriptInterface
    fun postMessage(jsonData: String) {
      if (jsonData == null) {
        Log.d(ContentValues.TAG, "postMessage: ${jsonData}")
      } else {
        val json = JSONObject(jsonData)
          when (val command = json.optString("name")) {
            CONTACTS -> contacts()
              else -> Log.d(ContentValues.TAG, "No function: $command. Add function in ${this::class.simpleName}")
          }
      }
    }

  private fun contacts() = onContacts()
}

The native bridge is connected to our MainSessionNavHostFragment, which we created in the first post in this series.

class MainSessionNavHostFragment : TurboSessionNavHostFragment() {

  ....

    var nativeAppJavaScriptInterface: NativeJavaScriptInterface = NativeJavaScriptInterface()
    ....

    override fun onCreateWebView(context: Context): TurboWebView {
      val turboWebView = super.onCreateWebView(context)
        bindNativeBridge(turboWebView, context = context)
        return turboWebView
    }

  private fun bindNativeBridge(webView: TurboWebView, context: Context) {
    nativeAppJavaScriptInterface.onContacts = {
      Handler(Looper.getMainLooper()).post {

        val permissions = arrayOf(
            Manifest.permission.READ_CONTACTS,
            Manifest.permission.QUERY_ALL_PACKAGES
            )

          val requestCode = 123 // This can be any integer value

          if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            if (context.checkSelfPermission(permissions[0]) == PackageManager.PERMISSION_GRANTED &&
                context.checkSelfPermission(permissions[1]) == PackageManager.PERMISSION_GRANTED) {
              // Permissions already granted
              // Do the contact reading operation here
            } else {
              // Permissions not granted
              requestPermissions(permissions, requestCode)
            }
          } else {
            // Permissions not needed in older versions of Android
            // Do the contact reading operation here
          }

        val contactsList: MutableList<String> = mutableListOf()
          val cursor = context.contentResolver.query(
              ContactsContract.Contacts.CONTENT_URI,
              null,
              null,
              null,
              null
              )

          if (cursor?.count ?: 0 > 0) {
            while (cursor != null && cursor.moveToNext()) {
              val name =
                cursor.getString(cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME))
                contactsList.add(name)
            }
          }

        cursor?.close()

          for (contact in contactsList) {
            Log.d("Contact", contact)
              val script = "Bridge.importingContacts('${contact}')"
              session.webView.evaluateJavascript(script, null)
          }
        Log.d(ContentValues.TAG, "bindNativeBridge onImportContacts")
      }
    }

    webView.addJavascriptInterface(nativeAppJavaScriptInterface, "nativeApp")

    webView.loadData("", "text/html", null)
  }
}

In our AndroidManifest file, we have to add the following:

<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"

Adding these lines ensures we can access the phone’s contacts.

Now everything is hooked up; when we run our app, we should see that we can import the user’s contacts. Using the JavaScript bridge is another powerful tool that Hotwire gives us, opening up a whole new world with a fraction of the code.

Conclusion

So far, we’ve covered getting up and running, utilising modals to feel more native, and accessing native screens, and today we covered the Javascript bridge. In the following article, we will talk about debugging, structuring your Android project, and external libraries that are useful in the Android ecosystem without going overboard.

Till next time.

How to Get up and Running with Turbo Android Part 2 - Feel More Native

William Kennedy — Fri, 19 May 2023 00:00:00 +0000

So far, we’ve covered getting up and running with Turbo Android. Now we can move on to the fun part of Turbo Android, which is about making it feel more native. Compared to Turbo-ios, Turbo Android has a lot built into the framework and can easily route different endpoints.

Getting Setup with Modals

You may have noticed that the Android app doesn’t feel very native. Instead, it feels like a webpage inside an app’s skin. Luckily, we can add some quick changes utilising Turbo Fragments found in the Turbo-Android library. By inheriting from these and updating out Path Configuration, we have routes display different Turbo Fragments.

For now, we will update our codebase so that every route that ends with new and edit will result in a modal popup like the one shown in this gif.

Update PathConfiguration

We created a path configuration file under assets/json in the previous tutorial. Let’s edit that and add a new rule.

{
  "patterns": [
    "/new$",
    "/edit$"
  ],
  "properties": {
    "context": "modal",
    "uri": "turbo://fragment/web/modal/sheet",
    "pull_to_refresh_enabled": false
  }
}

This is telling our Turbo Android app to use the class that’s annotated with @TurboNavGraphDestination(uri = "turbo://fragment/web/modal/sheet") for any route that ends in new or edit.

Create the Fragment and add it

Now we need to create the fragment. Add a new Kotlin class and call it WebBottomSheetFragment and make sure to inherit from TurboWebBottomSheetDialogFragment()


import dev.hotwire.turbo.fragments.TurboWebBottomSheetDialogFragment
import dev.hotwire.turbo.nav.TurboNavGraphDestination

@TurboNavGraphDestination(uri = "turbo://fragment/web/modal/sheet")
class WebBottomSheetFragment : TurboWebBottomSheetDialogFragment() {}

We’re not done yet. We’ve to add it to the list of registered fragments in our MainSessionNavHost

class MainSessionNavHost : TurboSessionNavHostFragment() {
  ...

    override val registeredFragments: List<KClass<out Fragment>>
    get() = listOf(
        WebFragment::class,
        WebBottomSheetFragment::class,
        )
    ...
}

When we run the app and navigate to any route that ends in new or edit, we display a modal.

Rendering a Native Screen

The exact process that we used to add a modal we can also use it to navigate to a native screen. Let’s navigate to a simple Hello World screen written with Jetpack Compose. Jetpack Compose is Google’s modern UI tool and is similar to SwiftUI.

There is a little setup involved if we use the modern approach to building Android tools. So let’s dive in step by step.

Update build.gradle

We have to add the compose libraries to our app and ensure that it will compile Jetpack Compose.

android {
  ...
    buildFeatures {
      compose true
    }
  ...
}

dependencies {

  implementation 'androidx.compose.ui:ui:1.4.2'
    implementation 'androidx.compose.material:material:1.2.0'
    def composeBom = platform("androidx.compose:compose-bom:2023.03.00")
    implementation(composeBom)
    ....
}

Make sure to sync your changes.

Next, we update our Path Configuration to render specific routes with a native screen.

{
  "patterns": [
    "/hello_world"
  ],
  "properties": {
    "context": "default",
    "uri": "turbo://fragment/hello_world"
  }
},

Now we create the HelloWorldFragment, which inherits from TurboFragment

  @TurboNavGraphDestination(uri = "turbo://fragment/hello_world")
  class HelloWorldFragment : TurboFragment() {
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
      return ComposeView(requireContext()).apply {
        setContent {
          Hello()
        }
      }
    }

    @Composable
      fun Hello() {
        Column(
            verticalArrangement = Arrangement.Center,
            horizontalAlignment = Alignment.CenterHorizontally
            ) {
          Text("Hello World")
        }
      }
  }

Finally, we add this fragment to the list of registered fragments:

class MainSessionNavHost : TurboSessionNavHostFragment() {
  ...

    override val registeredFragments: List<KClass<out Fragment>>
    get() = listOf(
        WebFragment::class,
        WebBottomSheetFragment::class,
        HelloWorldFragment::class 
        )
    ...
}

*NOTE: You may have to change your Kotlin version to 1.7.0 to compile. This can be changed in build.grade(project)

Once we’ve run the app, we should be able to navigate to the /hello\_world route and voila:

It’s pretty basic, but it’s enough to build on. In the next blog post, we will talk about the JavaScript bridge, and then we will talk about little improvements we can make to our Turbo app to make it even better.

Up and Running With Turbo Android Part 1

William Kennedy — Wed, 10 May 2023 00:00:00 +0000

Photo by Tyler Lastovich on Unsplash

Turbo Android - Part 1 Getting Setup

In previous blog posts, I’ve covered getting set up with Turbo iOS and implementing native functionality.

However, Android is a massive part of the mobile market, and there are too few resources on getting up and running with Turbo Android.

This post aims to rectify that.

You will need Android Studio for this tutorial.

The Basics

First of all, we will assume you have a Turbo-enabled app. I’ll be using this app for a talk I’m giving.

The app is called CRM ME. It’s a simple CRM app. You can add, delete and update contacts—all your basic functionality.

You can create your own using the following Rails command.

rails new crm_me -j esbuild

Note that we’re using esbuild. This is because import maps are not supported on the Android browser yet.

With your Rails app installed, you can run rails g scaffold Contacts name:string followed by rails db:migrate, and you’re good to go.

Let’s run your app on the following port.

bin/dev -p 3000

Setting up Turbo Android and Installing the Library

Open up Android Studio, click New Project, then click ‘No Activity’.

On the next screen, you can name the app whatever you want and click Finish.

To get Turbo up and running, we first need the Hotwire library.

Open up build.gradle(Module:app)

At the bottom of this file, you’ll see the following:

dependencies {

    implementation 'androidx.core:core-ktx:1.8.0'
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.material:material:1.8.0'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
}

Add in the Turbo Android library.

dependencies {

    implementation 'androidx.core:core-ktx:1.8.0'
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.material:material:1.8.0'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'

    implementation "dev.hotwire:turbo:7.0.0-rc18" 
}

You will be asked to sync your Gradle file. Ensure that you do as this installs all the dependencies.

Now, we need to get our boilerplate up and running.

Creating the MainActivity and MainSessionNavHost

Android is made up of activities. An activity is a single screen with a user interface. We will then add this activity to the Android Manifest file.

Let’s dive into the code:

First, create a kotlin file called MainActivity under the java/com.example.yourappname

Enter the following code:

package com.example.yourappname
 
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import dev.hotwire.turbo.activities.TurboActivity
import dev.hotwire.turbo.delegates.TurboActivityDelegate

class MainActivity : AppCompatActivity(), TurboActivity {
    override lateinit var delegate: TurboActivityDelegate

    override fun onCreate(savedInstanceState: Bundle?) {

        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        delegate = TurboActivityDelegate(this, R.id.main_nav_host)
    }
}

You’ll notice that activity_main and main_nav_host are currently red. We’ll rectify that soon.

We must first create our MainSessionNavHost, the main class that handles the flow of our application.

Create a kotlin file called MainSessionNavHost under java/com.example.yourappname

Enter the following:

import androidx.appcompat.app.AppCompatActivity
import androidx.fragment.app.Fragment
import dev.hotwire.turbo.config.TurboPathConfiguration
import dev.hotwire.turbo.session.TurboSessionNavHostFragment
import kotlin.reflect.KClass

class MainSessionNavHost : TurboSessionNavHostFragment() {
    override var sessionName = "main"
    override var startLocation = "http://10.0.2.2:3000"

    override val registeredFragments: List<KClass<out Fragment>>
    get() = listOf()

    override val registeredActivities: List<KClass<out AppCompatActivity>>
    get() = listOf()

    override val pathConfigurationLocation: TurboPathConfiguration.Location
    get() = TurboPathConfiguration.Location( assetFilePath = "json/configuration.json")

}

Now we have three more files to create; a small change to our Android manifest file, and we should be up and running. We need to make three resource files, a json/configuration.json asset file, a main_activity layout and a WebFragment.

Let’s start with our JSON file.

Right-click on the app and go to New > Folder > Assets Folder.

Next, right-click on the assets directory, New > Directory and create the JSON directory.

Finally, right-click on the json directory and add a file called configuration.json.

Add the following to the file.

{
  "settings": {
    "screenshots_enabled": true
  },
  "rules": [
    {
      "patterns": [
        ".*"
      ],
      "properties": {
        "context": "default",
        "uri": "turbo://fragment/web",
        "pull_to_refresh_enabled": true
      }
    }
  ]
}

This is the most important file as it determines the navigation on your Turbo-enabled app. We will cover Path Configuration in a future article, but I highly recommend reading this documentation.

Next, we will create a WebFragment file.

Place this in the same directory as your MainActivity

It will have the following:

import dev.hotwire.turbo.fragments.TurboWebFragment
import dev.hotwire.turbo.nav.TurboNavDestination
import dev.hotwire.turbo.nav.TurboNavGraphDestination

@TurboNavGraphDestination(uri = "turbo://fragment/web")
open class WebFragment : TurboWebFragment(), TurboNavDestination {}

We add this to the list of registered fragments in our MainSessionNavHost

override val registeredFragments: List<KClass<out Fragment>>
    get() = listOf(
        WebFragment::class
    )

We are so close to getting up and running. There are just three little things to do.

First, we create our layout_main file.

Click Resource Manager > Layout > + Icon > Layout Resource File

Mine looks like this:

 <?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/main_nav_host"
        android:name="com.example.thirdturbo.MainSessionNavHost"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:defaultNavHost="false" />

</androidx.constraintlayout.widget.ConstraintLayout>

Finally, we have to edit our Android Manifest(found in the top-level directory) file to ensure we can access the internet and localhost.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.INTERNET"/>

    <application
        android:usesCleartextTraffic="true"
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.ThirdTurbo"
        tools:targetApi="31">
    <activity
        android:name=".MainActivity"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />

            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

</manifest>

Now you should be able to click the Run button and watch it build your app.

Congratulations, you now have a Turbo-enabled Android app.

In the next part, we’ll take the app further by adding more Turbo-enabled fragments, such as modals and native screens.

Turbo Native - How to Access Native iOS features with the JavaScript bridge

William Kennedy — Sun, 13 Nov 2022 00:00:00 +0000

Photo by Tyler Lastovich on Unsplash

Turbo Native - How to Access Native iOS features with the JavaScript bridge

Turbo Native is described by Basecamp as allowing you to build “high-fidelity” cross-platform apps. What exactly does this mean? To me, it’s the ability to build cross-platform apps that allow you to access the native functionality without the caveat of building the same functionality across the many different platforms. In this article, we’ll cover how we can access native functionality by writing just a tiny bit of Swift but mostly, just sticking to Rails.

In my last article, I covered navigating to a native screen via tabs. You can also navigate to native screens via the Path Configuration. In this article, we’re going to touch on the JavaScript bridge by building two features. One that sends an event to the iOS app via JavaScript and another that sends an event to the browser via the iOS app.

For this, we’re going to access the phone’s contacts. This was a feature I was asked about recently. Here’s what it looks like.

For this, you’re going to have to build off my last post.

This post is aimed at being step-by-step so you can get an idea of the link between Turbo Native and your Rails app. If you get stuck following along, feel free to email me and let me know.

The code can be found here and here.

1. Set up the JavaScript bridge

Sending messages to the iOS app is our first port of call. We do this by implementing a JavaScript bridge. In the Rails app that we created in the previous post, add the following to our app/javascript/application.js.


class Bridge {

  // Sends a message to the native app, if active.
  static postMessage(name, data = {}) {
    // iOS
    window.webkit?.messageHandlers?.nativeApp?.postMessage({name, ...data})
  }
}

// Expose this on the window object so TurboNative can interact with it
window.Bridge = Bridge
export default Bridge

Next, we’ll create a simple stimulus controller for a proof of concept. We just want to see if we can send a message to our iOS app and react to it. In app/javascript/controllers/hello_controller.js, change the following:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    window.Bridge.postMessage("hello")
  }
}

Now connect the controller to the DOM. In app/views/posts/index.html.erb

<div data-controller='hello' id="posts">
  <% @posts.each do |post| %>
    <%= render post %>
    <p><%= link_to "Show this post", post %></p>
  <% end %>
</div>

Now for the final step, we need to open up our iOS codebase and add a handler for our scripts.

In our iOS codebase, add a new folder called Models and then add a new file called ScriptMessageHandler.swift

import WebKit

class ScriptMessageHandler: NSObject, WKScriptMessageHandler {
  func userContentController(
      _ userContentController: WKUserContentController,
      didReceive message: WKScriptMessage
      ) {
    print("JavaScript message received", message.body)
  }
}

Now, we just have to adjust our Turbo Coordinator to allow us to react to JavaScript messages. In TurboCoordinator.swift, add the following:

...
import SafariServices
import WebKit

class TurboCoordinator: Coordinator {
  ...
  private func makeSession() -> Session {
    let configuration = WKWebViewConfiguration()
    let scriptMessageHandler = ScriptMessageHandler()
    configuration.userContentController.add(scriptMessageHandler, name: "nativeApp")
    let session = Session(webViewConfiguration: configuration)
    session.delegate = self
    session.pathConfiguration = PathConfiguration(sources: [
        .file(Bundle.main.url(forResource: "PathConfiguration", withExtension: "json")!),
    ])
    return session
  }
  ...
}

Now build and run the app and take a look at our output in Xcode.

You should see something like the following:

JavaScript message received {
  name = "Hello from Rails";
}

You will notice that you’ll actually receive it when the app loads up the first time. This is because the tab connects to the DOM straight away.

If we open the tab with the Rails app, you will see navigating between posts will log in XCode.

Even though we only got to Hello World, we have laid the foundation to go a bit further and extend on what we are doing.

React to JavaScript Messages

Now we have set the stage to react to JavaScript messages. Let’s do something bit more interesting than “Hello World”. Let’s go back to our original goal of retrieving the contacts from the iPhone.

First, we need to expand on our ScriptMessageHandler to make it a bit smarter.

import WebKit

class ScriptMessageHandler: NSObject, WKScriptMessageHandler {
  func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage ) {
      guard
        let body = message.body as? [String: Any],
        let msg = body["name"] as? String
          else {
            print("No call")
              return
          }
          handleMessage(ScriptMessageHandler.MessageTypes(rawValue: msg) ?? ScriptMessageHandler.MessageTypes.none)
    }

      private func handleMessage(_ messageType: MessageTypes) -> String? {
        switch messageType {
          case .hello:
            print("hello world")
              return nil
          case .contacts:
              print("contacts")
                return nil
          case .none:
                print("No message")
                  return nil
        }
      }

      enum MessageTypes: String {
        case hello = "hello"
        case contacts = "contacts"
        case none = "none"
      }
    }

Now rerun and build the app again. You should still see Hello World in the terminal but this time, we added a enum that allows us to start expanding our functionality.

Let’s see can we print off the contacts from the local Address book.

To keep things simple for the tutorial, we’ll keep everything in the ScriptMessageHandler.

First off, we import the contacts library.

import Contacts

Then, we add a method that will simply print off the contacts.

func fetchContacts() {
  let store = CNContactStore()
    var contacts = [CNContact]()
    let keys = [CNContactFormatter.descriptorForRequiredKeys(for: .fullName)]
    let request = CNContactFetchRequest(keysToFetch: keys)

    do {
      try store.enumerateContacts(with: request) { (contact, stop) in
        contacts.append(contact)
      }
    } catch {
      print(error.localizedDescription)
    }
  for contact in contacts {
    print(contact.givenName, contact.familyName)
  }
}

Finally, we update our handleMessage function:

private func handleMessage(_ messageType: MessageTypes) -> String? {
  switch messageType {
    case .hello:
      print("hello world")
        return nil
    case .contacts:
        fetchContacts()
          return nil
    case .none:
          print("No message")
            return nil
  }
}

Now in our Rails app, we do the following in app/javascript/controllers/hello_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    window.Bridge.postMessage("contacts", {name: "hello"})
  }
}

Now rebuild our iOS app and see it crash.

The reason for the crash is because we need to get add permission to our native app for contacts information. In our Info.plist, we have to add NSContactsUsageDescription.

Once that is added, then rebuild the app.

You will only have to grant permission once. When permission is granted, you should see the output printed in Xcode.

Kate Bell
Daniel Higgins
John Appleseed
Anna Haro
Hank Zakroff
David Taylor

So for, so good. Now let’s send that information to our Rails app.

Send Information to the Rails app

So we’re printing to the Xcode console but now let’s send it back to the Rails app. For this, we’re going to print the names with JavaScript via console.log.

Here we’re going to introduce a concept that Ruby programmers might not be familiar with and that is delegates.

Delegates in swift are classes that do work for other classes. They have 3 parts.

A protocol with the methods, a class(or delegatee class) and the class that is delegating.

It took me some time to get them so if this is a new concept, then feel free to reach out.

In our ScriptMessageHandler, we start by adding a protocol.

protocol ScriptMessageDelegate: AnyObject {
  func evaluate(_ name: String)
}

Then in the ScriptMessageHandler itself, we do the following:

class ScriptMessageHandler: NSObject, WKScriptMessageHandler {
  weak var delegate: ScriptMessageDelegate?

Finally, we move back to our TurboCoordinator and add an extension.

extension TurboCoordinator: ScriptMessageDelegate {
  func evaluate(_ name: String) {
    session.webView.evaluateJavaScript("console.log('\(name)')")
  }
}

Now we are ready to assign the scriptMessageHandler delegate to the TurboCoordinator.

We do this in the TurboCoordinator’s makeSession() method.

private func makeSession() -> Session {
  let configuration = WKWebViewConfiguration()
  let scriptMessageHandler = ScriptMessageHandler()
  scriptMessageHandler.delegate = self
  ...
}

Now, you can rebuild the app and navigate to the tab. Navigating back and forth, you’ll see logs in both Xcode and if you open Safari > Develop > Simulator, you’ll see JavaScript being printed to the console.

Now that we’ve covered the two way communication without having to integrate an API, let’s finish off our project.

Generate a Contacts Scaffold

Let’s generate a Rails scaffold called contacts.

rails g scaffold Contacts name:string

Now migrate your database:

rails db:migrate

Now, we just need to make it easy to navigate to our contacts page. In our posts/index.html.erb, change it to the following:

<%= link_to "New post", new_post_path %>
<%= link_to "Contacts", contacts_path %>

Let’s add a stimulus controller for triggering the importing of contacts from iOS then add it to our contacts/index.html.erb

Let’s create a file called app/javascript/controllers/contacts_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  import() {
    window.Bridge.postMessage("contacts", {name: "contacts"})
  }
}

Next, we add it to our app/views/contacts/index.html.erb

<p style="color: green"><%= notice %></p>

<h1>Contacts</h1>

<button data-controller='contacts' data-action='contacts#import'>Import</button>

<%= turbo_stream_from :contacts %>

Next, we broadcast over a turbo stream when a new contact is created, in app/models/contacts.rb

class Contact < ApplicationRecord
  after_create_commit { broadcast_append_to :contacts, target: :contacts }
end

Now there is only two more changes left:

In app/javascript/application.js, add the following method:

// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
import "@hotwired/turbo-rails"
import "controllers"
import "trix"
import "@rails/actiontext"

class Bridge {

  // Sends a message to the native app, if active.
  static postMessage(name, data = {}) {
    // iOS
    window.webkit?.messageHandlers?.nativeApp?.postMessage({name, ...data})
  }

  static importingContacts(name) {
    const csrfToken = document.getElementsByName("csrf-token")[0].content;
    fetch('/contacts.json', {
          method: 'POST',
          headers: {
          "X-CSRF-Token": csrfToken,
          'Content-Type': 'application/json',
          "Accept": "application/json",
          },
          body: JSON.stringify({contact: { name } })
          }).then((response) => response.json())
          .then((data) => {
              console.log("Success:", data);
              })
          .catch((error) => {
              console.error("Error:", error);
      });
  }
}

// Expose this on the window object so TurboNative can interact with it
window.Bridge = Bridge

Then back in our Swift codebase, change the following in TurboCoordinator,

extension TurboCoordinator: ScriptMessageDelegate {
  func evaluate(_ name: String) {
    session.webView.evaluateJavaScript("Bridge.importingContacts('\(name)')")
  }
}

Now, rebuild the app for the final time. Navigate to contacts and press the Import button.

You should see the names instantly appear thanks to Turbo Streams.

This feels like magic and opens up a whole world of possibilities for web developers. In the famous words of DHH, “look at all the stuff I’m not doing.”

We’re not building a new native screen. We are just building one screen. We are not creating a new API endpoint, we’re simply using the endpoint provided by the scaffold. In a time where business efficiency will become more and more important, small teams that go down this road will be able to pack a big punch.

This is just the tip of the iceberg as well. My latest project interacts with MapKit. You can interact with the Haptic engine, the Audio Player and more.

I just want to give a massive shout out to Joe Masilotti who provided technical and editing feedback on this article. His Turbo Native posts are the best in the business. I also recommend checking out the Jumpstart iOS Pro template by Joe alongside Chris Oliver of GoRails fame if you are looking to jumpstart your Turbo iOS app.

Happy Hacking.