Hello everyone! In this article we are going to learn how to use UISearchController in iOS Apps.

What are we going to build?

We are going to build a movie search application which uses the TMDB API to fetch movie info and display it using a UICollectionView based on a user's search query.

Project Setup

Open up Xcode and create a new blank iOS App project – make sure you select UIKit and not SwiftUI.

In this app we are going to use the MVC Pattern so organise the project by creating the following groups and Swift files:

Now close your Xcode project. Open up the terminal and move to your project directory. Here we need to add SD WebImage Cocoa Pods to asynchronously download and cache the movie poster images.

Type the following command in the terminal:

pod init

Now when you list the contents of the directory, you can see that there is a new Podfile. Open the file using any text editor (here I've used Vim). Edit your Podfile so that it looks similar to the below image. Save and close the Podfile.

Now that we have specified the SD WebImage, we can install the dependencies by running the below command:

pod install

As you can see, we have successfully added the SD WebImage pod in our iOS project. Now run the below command to open our project in Xcode.

open PROJECT_NAME.xcworkspace

After opening Xcode, make sure you build your project by hitting Command+B.

How to Design the User Interface using UIKit and Programmatic UI

Our app needs three UIElements navigation bars to hold the search bar, UISearchBarController for actual search, and a UICollectionView to display the search results.

Open up your Scenedelegate.swift file and add the following code inside it which will connect to the session method:

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let scene = (scene as? UIWindowScene) else { return }
        window = UIWindow(windowScene: scene)       window?.rootViewController=UINavigationController(rootViewController:HomeVC())
        window?.makeKeyAndVisible()
    }

Since we are using a programatic UI, first we need to mention our Root View controller – that is, the first screen which will be displayed when the user launches the app.

Here in this app we're using only one View Controller, so we wrap it inside a UINavigationController. This provides a navigation bar where we can place our UISearchController.

Open up the HomeVC.swift file and add the following properties:

 private var SearchBar: UISearchController = {
        let sb = UISearchController()
        sb.searchBar.placeholder = "Enter the movie name"
        sb.searchBar.searchBarStyle = .minimal
        return sb
    }()

    private var MovieCollectionView: UICollectionView = {
        let layout = UICollectionViewFlowLayout()
        layout.scrollDirection = .vertical
        layout.itemSize = CGSize(width: UIScreen.main.bounds.width/3 - 10, height: 200)
        let cv = UICollectionView(frame: .zero, collectionViewLayout: layout)
        cv.register(MovieCell.self, forCellWithReuseIdentifier: MovieCell.ID)
        return cv
    }()

First we create our UISearchController and configure its properties such as placeholder text and style.

Then we create a UICollectionView and specify the type of layout our collection view should use. In this case it is UICollectionViewFlowLayout and other properties such as scroll direction, item size, and specifying a custom CollectionView cell class which we will create later in our project.

Inside the HomeVC class create a new function and add the following code to configure auto-layout constraints programmatically for our UICollectionView:

    //MARK: - HELPERS
    func configureUI(){
        MovieCollectionView.translatesAutoresizingMaskIntoConstraints = false
        MovieCollectionView.topAnchor.constraint(equalTo: view.topAnchor).isActive = true
        MovieCollectionView.bottomAnchor.constraint(equalTo: view.bottomAnchor).isActive = true
        MovieCollectionView.leftAnchor.constraint(equalTo: view.leftAnchor).isActive = true
        MovieCollectionView.rightAnchor.constraint(equalTo: view.rightAnchor).isActive = true
    }

First we say that we don't need to convert the auto resizing mask into the constraints. Then we pin our collection view to all four sides of our View Controller.

Inside the viewDidLoad() method add the following lines of code:

  override func viewDidLoad() {
        super.viewDidLoad()

        navigationItem.title  = "Movie Search"
        view.backgroundColor = .systemBackground
        SearchBar.searchResultsUpdater = self
        navigationItem.searchController = SearchBar
        view.addSubview(MovieCollectionView)
        MovieCollectionView.delegate = self
        MovieCollectionView.dataSource = self
        configureUI()
    }

Here we first specify the title for our ViewController followed by the background color which is the systemBackground color. If the device is in light mode it shows a white background. If it is in dark mode, then it shows a dark background.

Then we set current the view controller as the search result updater, then add our SearchController to the navigation bar, add the UICollectionView to the ViewController, and setup delegate and datasource. Finally we pin the UICollectionView by using auto-layout.

Create an extension for HomeVC and implement the UISearchResultsUpdating protocol and its stub method updateSearchResults.

extension HomeVC: UISearchResultsUpdating{

    func updateSearchResults(for searchController: UISearchController) {
        guard let query = searchController.searchBar.text else{return}

        }

    }


}

The updateSearchResults() method will be called whenever the text entered in the search bar changes or when the user taps the search button on their keyboard.

Next we need to create that custom UICollectionView cell. Inside the MovieCell.swift file, add the following code:

import Foundation
import UIKit
import SDWebImage

class MovieCell: UICollectionViewCell{

    static let ID = "MovieCell"
    private var MoviePosterImageView: UIImageView = {
        let imageView = UIImageView()
        imageView.contentMode = .scaleAspectFit
      //  imageView.image = UIImage(systemName: "house")
        return imageView
    }()

    override init(frame: CGRect) {
        super.init(frame: frame)
        addSubview(MoviePosterImageView)
        configureUI()
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

}

extension MovieCell{
    func configureUI(){
        MoviePosterImageView.translatesAutoresizingMaskIntoConstraints = false
        MoviePosterImageView.topAnchor.constraint(equalTo: topAnchor).isActive = true
        MoviePosterImageView.bottomAnchor.constraint(equalTo: bottomAnchor).isActive = true
        MoviePosterImageView.leftAnchor.constraint(equalTo: leftAnchor).isActive = true
        MoviePosterImageView.rightAnchor.constraint(equalTo: rightAnchor).isActive = true
    }
    func updateCell(posterURL: String?){
        if let posterURL = posterURL {
            guard let CompleteURL = URL(string: "https://image.tmdb.org/t/p/w500/\(posterURL)") else {return}
            self.MoviePosterImageView.sd_setImage(with: CompleteURL)
        }

    }
}

Here we create our custom collection view cell by sub-classing the UICollectionView class and implementing the init() functions.

We create a UIImageView to display the movie poster image and setup auto-layout constraints for it. Then we create a user defined function which takes the Movie poster URL string a parameter and downloads it asynchronously without affecting the UI Thread/Main thread. It does this by using the SD WebImage CocoaPod which we added earlier.

How to Set Up Our API

Before moving on, you'll need to get your API key for the TMDB API by creating an account (it's free). We are going to use the Movie Search end point of the API which takes the API Key and movie name as parameters.

https://api.themoviedb.org/3/search/movie?api_key=API_KEY_HERE&query=batman

You can examine the API response by running it in Postman.

How to Create a Model for the API Response

Now we get a JSON response from the API. We need to decode them to Swift which we can do by creating a model struct that implements the Codable protocol.

WE can generate the model struct for our JSON response easily by using JSON to Swift websites. Here is the model code for the API response – you can just copy and paste it inside the Model.swift file:

import Foundation

struct TrendingTitleResponse: Codable {
    let results: [Title]
}

struct Title: Codable {
    let id: Int
    let media_type: String?
    let original_name: String?
    let original_title: String?
    let poster_path: String?
    let overview: String?
    let vote_count: Int
    let release_date: String?
    let vote_average: Double
}

struct YoutubeSearchResponse: Codable {
    let items: [VideoElement]
}


struct VideoElement: Codable {
    let id: IdVideoElement
}


struct IdVideoElement: Codable {
    let kind: String
    let videoId: String
}

How to Perform HTTP Requests Using Swift

Now we need to write some Swift code to perform HTTP GET requests which return the JSON response of the API.

Swift provides a URLSession class which makes it easier to write networking code without needing any third party libraries like AFNetworking, AlamoFire, and so on.

Open APIService.swift and add the following code:

import Foundation

class APIService{
    static var shared = APIService()
    let session = URLSession(configuration: .default)

    func getMovies(for Query: String,completion:@escaping([Title]?,Error?)->Void){
        guard let FormatedQuery = Query.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)  else{return}

        guard let  SEARCH_URL = URL(string: "https://api.themoviedb.org/3/search/movie?api_key=API_KEY_HERE&query=\(FormatedQuery)") else {print("INVALID")
            return}



        let task = session.dataTask(with: SEARCH_URL) { data, response, error in
            if let error = error {
                print(error.localizedDescription)
                completion(nil,error)
            }
            if let data = data {
                do{
                    let decodedData = try JSONDecoder().decode(TrendingTitleResponse.self, from: data)
                 //   print(decodedData)
                    completion(decodedData.results,nil)
                }
                catch{
                    print(error)
                }
            }
        }
        task.resume()
    }
}

Here we created a class named API Service with the singleton pattern so we need an instance for this class as a static member of the class. Then we created a session for our networking task with the default configuration, followed by a user defined method getMovies().

Then we created our networking task – in this case we need to perform HTTP GET requests which can be performed using the dataTask() method of the URLSession class. It takes the URL as a parameter and gives a completion handler which contains data returned from the API, error data if any error has occurred, and a response which has HTTP Response information such as status codes and their corresponding messages.

If there is any error, then we escape out of this function with error data. If not, then we decode our JSON data based on our Swift Model and escape out of this function with the decoded data.

How to Display the Search Results on the UICollectionView

In HomeVC.swift, create a private property which is an array of Title objects. These will hold each movie's info returned by the API.

private var Movies = [Title]()

In HomeVC.swift create an extension for the HomeVC class and implement the UIColletionViewDelegate and UICollectionViewDatasource protocols. Then implement numberOfItemsInSection (which is equal to the number of movies returned by the API) and cellForItemAt (which actually populates the cell with API responses, like download and set the poster image).

 func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
        return Movies.count
    }
    func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        if let cell = collectionView.dequeueReusableCell(withReuseIdentifier: MovieCell.ID, for: indexPath) as? MovieCell{
           // cell.backgroundColor = .systemBackground

            cell.updateCell(posterURL: Movies[indexPath.row].poster_path)
            return cell
        }
        return UICollectionViewCell()

    }

Finally we need to make actual API call which we do inside the updateSearchResults() delegate method which we have implemented previously. Inside that method add the following code:

    func updateSearchResults(for searchController: UISearchController) {
        guard let query = searchController.searchBar.text else{return}
        APIService.shared.getMovies(for:query.trimmingCharacters(in: .whitespaces)) { titles, error in
            if let titles = titles {
                self.Movies = titles
                DispatchQueue.main.async {
                    self.MovieCollectionView.reloadData()
                }

            }
        }

    }

Here, whenever the user types in the search bar or presses the search button, we make an HTTP GET request to fetch a movie (based on the name entered in the search bar). Then we reload the CollectionView which updates the collection view cells with the movie poster.

Note that we need to do this in the Main Thread/UI Thread, because by default iOS automatically makes HTTP request in background thread. This means that we need to use UI/Main Thread to update our UI elements.

Now run your app in the simulator to see the result:

Congratulations! You have learned to use UISearchController in iOS apps.

Apple provides a complete development environment for programmers named Xcode. If you are developing software for macOS, iOS, tvOS, and watchOS, you must install the full Xcode application.

It's not pre-installed, but you can install it from the Apple developer website or the App Store on your Mac.

What are Xcode Command Line Tools?

If you're not developing software for an Apple device, you won't need the full Xcode application (it requires over 40GB of disk space!).

Instead, you'll install Xcode Command Line Tools. It's a smaller package for software developers with tools that run on the command line, that is, in the Terminal application.

Programmers have used these tools on Unix operating systems since computing's beginnings, and they serve as the foundation of almost all software development.

Luckily, the Xcode Command Line Tools package only requires 1.2GB of space on your disk.

You have three choices to install Xcode Command Line Tools on a Mac:

• install the full Xcode package
• install Xcode Command Line Tools when triggered by a command
• install Xcode Command Line Tools as part of a Homebrew installation.

I don't recommend installing the full Xcode package unless you're developing software for an Apple device. The download will take too long and it will consume unnecessary disk space. Instead, try either of two faster methods.

How to Install Xcode Command Line Tools from a Command Prompt

Apple has made it easy to install Xcode Command Line Tools because certain commands will prompt you to begin installation.

Here are examples of commands that will trigger a prompt to install Xcode Command Line Tools:

• clang – a compiler that turns source code into an executable program
• gcc – the GNU compiler
• git – the save-as-you-go version control system

Running any of these commands in the terminal will bring up a prompt to install Xcode Command Line Tools. I've written elsewhere about How to Open Terminal on MacOS – just click the Spotlight icon in the menu bar and type “terminal.”

You can also enter the command xcode-select --install in the terminal to begin the installation process. You'll see a panel that asks you to install Xcode Command Line Tools.

Click 'Install' to begin the download and installation process.

Installation takes 8 minutes on a 2021 Mac M1 Mini, with a 100Mbps Internet connection. It's significantly slower on Mac Intel over a slow Internet connection.

You'll see a confirmation message when installation is complete.

Verify that you've successfully installed Xcode Command Line Tools:

$ xcode-select -p

You should see the following:

/Library/Developer/CommandLineTools

How to Use Homebrew to Install Xcode Command Line Tools

As easy as it is to use the command prompt to install Xcode Command Line Tools, I recommend an even easier method: using Homebrew.

This option was only recently added to Homebrew, so many developers are not aware of it.

Homebrew is the popular Mac package manager. Most developers need programming languages and utilities that don't come installed on macOS and are not included in the Xcode Command Line Tools package. Homebrew can install almost any open-source tool for developers.

Since you'll probably need Homebrew, you might as well let Homebrew install Xcode Command Line Tools for you.

First, check if Homebrew is already installed.

$ brew

If Homebrew is not installed, you will see:

zsh: command not found: brew

Homebrew provides an installation script you can run with a single command (check that it hasn't changed at the Homebrew site).

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The Homebrew installation script will ask you to enter your Mac user password. This is the password you use to sign in to your Mac.

Password:

You won't see the characters as you type. Press enter when you are done.

If you haven't already installed Xcode Command Line Tools, you'll see a message that "The Xcode Command Line Tools will be installed." Press return to continue when prompted by the Homebrew installation script.

You’ll see diagnostic and progress messages. Homebrew installation takes 2 to 15 minutes on a 2021 Mac M1 Mini, with a 100Mbps Internet connection. It's significantly slower on Mac Intel over a slow Internet connection.

On Mac Intel machines, that's all you need to do – Homebrew is ready to use. On Mac Intel, Homebrew installs itself into the /usr/local/bin directory, which is already configured for access by the shell with the macOS default $PATH.

On Apple Silicon machines, there's one more step. Homebrew files are installed into the /opt/homebrew folder. But the folder is not part of the default $PATH. Follow Homebrew's advice and create a ~/.zprofile file that contains a command which sets up Homebrew. Homebrew shows instructions at the end of the installation process:

- Add Homebrew to your PATH in ~/.zprofile:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

After you've installed Homebrew, check that Homebrew is installed properly.

$ brew doctor

You should see this:

Your system is ready to brew.

If Homebrew is successfully installed, there will be Homebrew files in /usr/local (for macOS Intel) or /opt/homebrew (for Apple Silicon).

Now you have both Xcode Command Line Tools and Homebrew installed. If you want to learn more about adding Homebrew packages to set up your development environment, see Install a Homebrew Package.

More information

I've written an in-depth guide to Install Xcode Command Line Tools that goes beyond these basics.

In the guide, I explain how to check if Xcode Command Line Tools Are Already Installed. I go into more detail about how to Install Xcode Command Line Tools with Homebrew. Finally, I explain how to Uninstall Xcode Command Line Tools, Reinstall Xcode Command Line Tools, and provide a List of Xcode Command Line Tools that you can use.

There's also a complete guide to Install Homebrew for Mac that explains how to Update Homebrew, Uninstall Homebrew, and keep up with other Housekeeping for Homebrew.

Your development environment

MacOS is the most popular platform for software development because the operating system is based on Unix, the longtime standard for software development.

With Xcode Command Line Tools installed, you'll have a solid foundation for adding almost any open source development tool.

Add Homebrew and you have a package manager that can install version managers, programming languages, and almost any other tool you may need.

Combined with a text editor and terminal application, you'll be prepared for any tutorial you'll find on freeCodeCamp.

In this post we will try to re-create the Spotify home screen layout in Swift programmatically. Why programmatically? I think it's always good to know how to build things in different ways, and I like to write code to do things programmatically. These skills are especially helpful if you are working with team or using version control.

This is the actual home screen of Spotify's mobile app. So to achieve this kind of layout, we will be using UICollectionView, and we may use TabBarController as well to create the tab navigator.

Basic requirement : First make sure you have Xcode +10 installed and swift +4.

Let's start by creating a new Xcode project using Xcode:

And the first thing we need to do in ViewController.swift is change the superClass to UICollectionViewController instead of UIViewController because our class will be based on collectionView.

//
//  ViewController.swift
//  spotifyAutoLayout
//
//  Created by admin on 10/31/19.
//  Copyright © 2019 Said Hayani. All rights reserved.
//

import UIKit

class ViewController: UICollectionViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        collectionView.backgroundColor = .purple
        // Do any additional setup after loading the view.
    }


}

If you try to run the app the build will fail. We need to add some code to the AppDelegate.swift file within the didFinishLaunchingWithOptions function past this piece of code before the return statement:

  let layout = UICollectionViewFlowLayout()
        window = UIWindow()
        window?.rootViewController = ViewController(collectionViewLayout: layout)

And the code should look like this:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        let layout = UICollectionViewFlowLayout()
        window = UIWindow()
        window?.rootViewController = ViewController(collectionViewLayout: layout)
        return true
    }

Now you should be able to run the app and see the backgroundColor changed to purple:

The next step is to distribute the layout and divide the space equally between the sections.

Let's define the methods of our CollectionView.

The steps:

• Register a reusable cell with unique identifier
• Define the number of the items in the section
• Use the the registered cell

To use some of CollectionView methods we need to always conform to UICollectionViewDelegateFlowLayout as a superClass and to get the autoComplete of the methods. So let's start with registering the CollectionViewCell.

Inside View.DidLoad() we call the collectionView.register() method to register the reusable cell:

  collectionView.register(UICollectionViewCell.self, forCellWithReuseIdentifier: cellId)

Then we define the number of cells we will have inside the collectionView using numberOfItemsInSection. For now we just need to make it 5 items:

 override func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
        return 5
    }

The next step is to define the reusable cell using cellForItemAt that should return UICollectionViewCell and have a unique id called cellId. The code looks like this:

 override func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath)
        cell.backgroundColor = .red
        return cell
    }

The full code should look like this:

import UIKit

class ViewController: UICollectionViewController, UICollectionViewDelegateFlowLayout {
    let cellId : String = "cellId"

    override func viewDidLoad() {
        super.viewDidLoad()
        collectionView.backgroundColor = .purple
        collectionView.register(UICollectionViewCell.self, forCellWithReuseIdentifier: cellId)

    }


    override func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
        return 5
    }
    override func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath)
        cell.backgroundColor = .red
        return cell
    }

}

You should be able to see 5 items with red backgrounds on the screen:

Add a custom width and height to the cells

Now we need to place the cells in the correct order and give them a width and height. Each cell will take the width of the screen as width.

We are lucky to have sizeForItemAt method so we can give the cells a custom width and height. It's a method that should return a CGSize type:

 func collectionView(_ collectionView: UICollectionView, layout collectionViewLayout: UICollectionViewLayout, sizeForItemAt indexPath: IndexPath) -> CGSize {
        let width = view.frame.width
        let height = CGFloat(200)

        return CGSize(width: width, height: height)
    }

So we made the Cell take the width of the screen by using view.frame.width and a custom height with is a CGFloat type.

Now you can see the result below in your Simulator :

Everything looks good so far. This time let's create a custom cell that can be reusable. Create a new Swift file named CustomCell:

CustomCell.swift should look like this below:

import UIKit

class CustomCell: UICollectionViewCell {
    override init(frame: CGRect) {
        super.init(frame: frame)

    }

    required init?(coder aDecoder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}

Now the next things we have to do is to modify two methods to support the reusable cell, collectionView.register and cellForItemAt. Let's first modify the register method. Replace UICollectionViewCell.**self** with CustomCell:

 collectionView.register(UICollectionViewCell.self, forCellWithReuseIdentifier: cellId)

Next we need to cast cellForItemAt to conform to CustomCell like below:

  let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath) as! CustomCell

If you run the app probably you won't notice any change, so give the CustomCell a backgroundColor backgroundColor = .yellow. Don't forget to remove the line cell.backgroundColor = .red in cellForItemAt. You should see the background color changed to yellow ?

Now it's time to put some salt into CutomCell :D

If you look at the Spotify home screen, each section which is a CustomCell in our example contains a section title, sub cells, and is horizontal:

Add a section title

Let's add a title label to the cell. Create the titleLabel element inside the CutomCell class:

let titleLabel: UILabel = {
        let lb  = UILabel()
        lb.text = "Section Title"
        lb.font = UIFont.boldSystemFont(ofSize: 14)
        lb.font = UIFont.boldSystemFont(ofSize: 14)

        return lb
    }()

Then add the element to the view inside init() block:

addSubview(titleLabel)

If you run the app you won't see any changes, and that's because we didn't put any constraint to the element yet. So let's add some constraints – add this property lb.translatesAutoresizingMaskIntoConstraints = **false** to titleLabel to be able to apply constraints to the element:

After we add titleLabel to the view, we define the constraints:

 addSubview(titleLabel)
titleLabel.topAnchor.constraint(equalTo: topAnchor, constant: 8).isActive = truetitleLabel.leftAnchor.constraint(equalTo: leftAnchor,constant: 8 ).isActive = true

Always make sure to add .isActive = true property – without it the constraint won't work!

Before we move on to the next part, let's first change the background color of the screen to black and also remove the yellow color for the cells:

Now comes the big part: putting sub cells into each cell. To achieve that we are going to add a CollectionView inside CustomCell.

To add a CollectionView inside UICollectionViewCell we need to add properties UICollectionViewDelegate, UICollectionViewDelegateFlowLayout, and UICollectionViewDataSource as superClass to CustomCell.

Let's create the collectionView element as any simple view:

    let collectionView : UICollectionView = {
        // init the layout
        let layout = UICollectionViewFlowLayout()
        // set the direction to be horizontal
        layout.scrollDirection = .horizontal

        // the instance of collectionView

        let cv = UICollectionView(frame: .zero, collectionViewLayout: layout)

        // Activate constaints

        cv.translatesAutoresizingMaskIntoConstraints = false

        return cv

    }()

Notice that we add layout to the collectionView as layer in the initializer as we did the first time with the viewController.swift. Here we also specify the direction of the FlowLayout to be .horizontal.

Let's add the collectionView element to the view as subView.

We gonna make a function that do that for us to make the code a little bit cleaner.

    fileprivate  func setupSubCells(){
        // add collectionView to the view
        addSubview(collectionView)

        collectionView.dataSource = self
        collectionView.delegate = self
        // setup constrainst
        // make it fit all the space of the CustomCell
        collectionView.topAnchor.constraint(equalTo: titleLabel.bottomAnchor).isActive = true
        collectionView.leftAnchor.constraint(equalTo: leftAnchor).isActive = true
        collectionView.bottomAnchor.constraint(equalTo: bottomAnchor).isActive = true
        collectionView.rightAnchor.constraint(equalTo: rightAnchor).isActive = true
    }

Make sure to set delegate to self for the collectionView and the dataSource as well:

collectionView.dataSource = self

collectionView.delegate = self

Then call the function within init block.

Xcode will display some errors if you trying to build the app because we are not conforming to UICollectionViewDelegate and UICollectionViewDelegateFlowLayout protocols. To fix that we need first to register the sub cell as a reusable cell.

Create a variable at the top of the class and give it a name of cellId so we can use it when we need the cell identifier:

let cellId : String = "subCellID"

collectionView.register(UICollectionViewCell.self, forCellWithReuseIdentifier: cellId)

Now we're missing two more methods to make the errors go away: numberOfItemsInSection that define the number of cells in the section and cellForItemAt that define the reusable cell. These methods are necessary for collectionView to work properly:

 // number of cells
func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
       return  4
    }

    // reusable Cell
     func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: cellId, for: indexPath)
         cell.backgroundColor = .yellow

        return cell
    }

The results should look like this:

As you can see, the collectionView are in purple as background and sub cells are yellow.

The last things we can do before ending this article is make subCells have the height of the section and as width. Again we are using sizeForItemAt to define the height and the width of the cell .

 func collectionView(_ collectionView: UICollectionView, layout collectionViewLayout: UICollectionViewLayout, sizeForItemAt indexPath: IndexPath) -> CGSize {

        let width = frame.height
        let height = frame.height

        return CGSize(width: width, height: height)

    }

And here we are ?:

NICE! I'm gonna stop at this point so this post isn't too long. I'll make a second part where we are going to add some mocked pictures and fill it with some data.

Full source code ? here

Please please if you have any additions, questions, or corrections, post it in the comments below ? or hit me up on Twitter.

Subscribe to my email list to be notified when the second part of this tutorial is published

To use images in Xcode, you need to upload them to Assets.xcassets, located in the Supporting Files folder. There are two options you can go with: bitmaps (aka .png files) or vectors (aka .pdf files). The first step is deciding which file type you’d like to use.

The difference between bitmaps and vector assets

Most tutorials online use bitmap assets, which are .png files. This requires you to drag over 3 copies of the image into Xcode.

Drag and drop the three copies of your .png images here

However there is a school of thought that believes vector assets are superior. This article has a great explanation of why that’s the case. Vector assets are .svg files (or .pdf for Xcode). If you choose to use vectors assets, you only need to upload one version of the image to Xcode.

Drag and drop your .pdf file here

Here’s what I’ve heard from those much wiser then I–Android phones use algorithms from the vector asset to generate the image in any size required. Makes sense given the wide breadth of devices and screen sizes for Android.

However vector assets in iPhones don’t actually scale with algorithms (apparently). So you don’t get higher quality images by using vectors over bitmaps. Instead what you get is the same quality as bitmap. The iPhone simply takes the “vector” asset and converts it to the same three bitmap sizes.

Aside from the algorithm logic above, there are a few more objective benefits of using vector assets for iPhones.

1. Reduces likelihood of human error. Right now there are three bitmap sizes (1x, 2x ,3x). That means you need to upload three images to your assets. That’s three opportunities to accidentally drag and drop the wrong image. When you use vector assets (which come up as universal in Xcode), you only need to upload one image instead of three. There’s less chance of uploading the incorrect size or image.
2. Speed. Same reason as #1. If you are using a lot of images in your app, then using vector assets reduces the number of images you need to upload by a third.
3. Future proofing. The iPhone currently only uses three image sizes (1x, 2x, 3x). This is to do with the increased retina quality of the screens. When Apple introduced the high retina screens a few years ago, the number of pixels per point increased for a sharper image.
   It seems extremely likely that similar technological increases will continue to occur. In the future, we may need to upload 4x, 5x and 6x images. If we use a vector asset, the app will scale the image for us. This saves us from dropping in the new sizes of the bitmap asset.
   Although I have to admit I’m a bit confused about this, given that iPhone vector assets don’t seem to actually work on algorithms. So I’m not sure how they will automatically scale to larger sizes. But my wise mentor explained this and I trust him!

The one big downside for using vector assets in Xcode is that most places don’t provide the .pdf file. You need to convert it from .svg yourself.

Update on 18 June 2017: Apple have announced in WWDC that iOS is now supporting true scalar images! Or at least, that’s what I think they announced. Now there is even more reason to use to use a single scale.

How to upload a vector asset

Options to upload a vector asset

Head to the attributes menu. Change the scales to “single scale”, and check the resizing box to “preserve vector data”. This will change the upload option to “all” instead of 1x, 2x, 3x.

Drag and drop your .pdf file here

Next you drag and drop your .pdf file into the one slot. I’m not too sure how to convert .svg to .pdf yet, but I assume it’s fairly easy with Preview.

How to upload .png files

If you decide to go ahead with .png, you’ll need to upload three versions of your file. This is to cover the varying screen resolutions of the different iPhones.

Options for bitmap assets

First, ensure the “scales” option in the attributes menu is set to “individual scales”. This is the default option, and it will show you three slots that you should fill:

Drag and drop your three copies of your image here

Second, find an image that you want to use in your app. Let’s assume it’s this icon:

Icons of a tower of three stones and a candle

Wow that’s big. It’s because I downloaded the 512 pixel version from the site. However I only want the image to be 20 x 20 pixels in my app. To convert the image to 20 pixels, I’ll resize it in Preview.

Make three copies of the original image. The names of your image should look something like this: zen.png, zen@2x.png, zen@3x.png. The important part is that the files all have the same name (here I’m using zen), and two of them end with @2x and @3x. When you use this naming convention, Xcode will be able to automatically find the correct size based on the device type.

Next, open the image in Preview and go to Tools > Adjust size to bring up the menu below. Specify 20 x 20 pixels. Press ok and save the change. This is your base image, zen.png.

Do the same thing for zen@2x.png. Only this should be 40 x 40 pixels. One more time for zen@3x.png. This will be 60 x 60 pixels.

Now you can drag and drop the images into the correct boxes in Xcode. Done!

Xcode is an indispensable IDE for iOS and macOS developers. From the early days, the ability to build and install custom plugins had given us a huge boost in productivity. It was not long before Apple introduced Xcode extension due to privacy concerns.

I have built a few Xcode plugins and extensions like XcodeWay, XcodeColorSense, XcodeColorSense2, and Xmas. It was a rewarding experience. I learned a lot, and the productivity I gained was considerable. In this post I walkthrough how I converted my Xcode plugins to extensions, and the experience I had in doing so.

My first Xcode plugin: XcodeWay

I choose a lazy person to do a hard job. Because a lazy person will find an easy way to do it

I really like the above quote from Bill Gates. I try to avoid repetitive and boring tasks. Whenever I find myself doing the same tasks again, I write scripts and tools to automate that. Doing this takes some time, but I will be a bit lazier in the near future.

Besides the interest in building open source frameworks and tools, I like to extend the IDE I’m using — mostly Xcode.

I first started iOS development in 2014. I wanted a quick way to navigate to many places right from Xcode with the context of the current project. There are many times we want to:

• open the current project folder in “Finder” to change some files
• open Terminal to run some commands
• open the current file in GitHub to quickly give the link to a workmate
• or to open other folders like themes, plugins, code snippets, device logs.

Every little bit of time we save each day counts.

I thought it would be cool idea to write an Xcode plugin that we can do all above things right inside Xcode. Instead of waiting for other people to do it, I pulled up my sleeve and wrote my first Xcode plugin — XcodeWay— and shared it as open source.

XcodeWay works by creating a menu under Editor with lots of options to navigate to other places right from Xcode. It looks simple but there was some hard work required.

What are Xcode plugins?

Xcode plugins are not officially supported by Xcode or recommended by Apple. There are no documents about them. The best places we can learn about them are via existing plugins’ source code and a few tutorials.

An Xcode plugin is just a bundle of type xcplugin and is placed at ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins . Xcode, when starting, will load any Xcode plugins present in this folder. Plugins are run in the same process as Xcode, so could do anything as Xcode. A bug in any plugin can cause Xcode to crash.

To make an Xcode plugin, create a macOS Bundle with one class that extends from NSObject , and have an initialiser that accepts NSBundle , for example in Xmas:

class Xmas: NSObject {

  var bundle: NSBundle

  init(bundle: NSBundle) {    self.bundle = bundle    super.init()  }}

Inside Info.plist, we need to:

• declare this class as the main entry class for the plugin, and
• that this bundle has no UI, because we create UI controls and add to the Xcode interface during runtime

<key>NSPrincipalClass</key><string>Xmas</string><key>XCPluginHasUI</key><false/>

Another problem with Xcode plugins is that we have to continuously update DVTPluginCompatibilityUUIDs . This changes every time a new version of Xcode comes out. Without updating, Xcode will refuse to load the plugin.

What Xcode plugins can do

Many developers build Xcode plugins because they miss specific features found in other IDEs like Sublime Text, AppCode, or Atom.

Since Xcode plugins are loaded in the same process as Xcode, they can do everything that Xcode can. The only limit is our imagination. We can leverage Objective C Runtime to discover private frameworks and functions. Then LLDB and Symbolic breakpoint can be used further to inspect running code and alter their behaviors. We can also use swizzling to change implementation of any running code. Writing Xcode plugins is hard — lots of guessing, and sometimes a good knowledge of assembly is required.

In the golden age of plugins, there was a popular plugin manager, which itself was a plugin, called Alcatraz. It could install other plugins, which basically just downloads the xcplugin file and moves this to the Plug Ins folder.

To get a sense of what plugins can do, let’s take a look at some popular plugins.

Xvim

First in the list is Xvim, which adds Vim keybindings right inside Xcode. It supports mostly all of the keybindings that we used to have in Terminal.

SCXcodeMiniMap

If you miss MiniMap mode in Sublime Text, you can use SCXcodeMiniMap to add a right map panel inside Xcode editor.

FuzzyAutocompletePlugin

Before version 9, Xcode didn’t have proper auto completion — it was just based on prefix. That was where FuzzyAutocompletePlugin shone. It performs fuzzy auto completion based on the hidden IDEOpenQuicklyPattern feature in Xcode.

KSImageNamed-Xcode

To display a bundle image inside UIImageView, we often use the imageNamed method. But remembering exactly the name of the image file is hard. KSImageNamed-Xcode is here to help. You will get a list of auto-suggested image names when you begin to type.

ColorSense-for-Xcode

Another itch during development is to work with UIColor , which uses RGBA color space. We don’t get a visual indicator of the color that we specify, and manually performing checking can be time consuming. Luckily there is ColorSense-for-Xcode which shows the color being used and the color picker panel to easily select the right color.

LinkedConsole

In AppCode, we can jump to a specific line in the file that is logged inside the console. If you miss this feature in Xcode, you can use LinkedConsole. This enables clickable links inside Xcode console so we can jump to that file instantly.

The hard work behind Xcode plugins

Making an Xcode plugin is not easy. Not only do we need to know macOS programming, but we also need to dive deep into Xcode view hierarchy. We need to explore private frameworks and APIs in order to inject the feature we want.

There are very few tutorials on how to make plugins but, luckily, most plugins are open source so we can understand how they work. Since I have made a few plugins, I can give some technical details about them.

Xcode plugins are done usually with two private frameworks: DVTKit and IDEKit . System frameworks are at /System/Library/PrivateFrameworks but the frameworks that Xcode uses exclusively are under /Applications/Xcode.app/Contents/ , there you can find Frameworks , OtherFrameworks and SharedFrameworks.

There is a tool class-dump that can generate headers from the Xcode app bundle. With the class names and methods, you can call NSClassFromString to get the class from the name.

Swizzling DVTBezelAlertPanel framework in Xmas

Christmas has always given me a special feeling, so I decided to make Xmas, which shows a random Christmas picture instead of the default alert view. The class used to render that view is DVTBezelAlertPanel inside the DVTKit framework. My article on building that plugin is here.

With Objective C Runtime, there is a technique called swizzling, which can change and switch implementation and method signature of any running classes and methods.

Here, in order to change the content of that alert view, we need to swap the initialiser initWithIcon:message:parentWindow:duration: with our own method. We do that early by listening to NSApplicationDidFinishLaunchingNotification which is notified when a macOS plugin, in this case Xcode, launches.

class func swizzleMethods() {    guard let originalClass = NSClassFromString("DVTBezelAlertPanel") as? NSObject.Type else {        return    }

do {        try originalClass.jr_swizzleMethod("initWithIcon:message:parentWindow:duration:",            withMethod: "xmas_initWithIcon:message:parentWindow:duration:")    }    catch {        Swift.print("Swizzling failed")    }}

I initially liked to do everything in Swift. But it’s tricky to use the swizzle init method in Swift, so the quickest way is to do that in Objective C. Then we simply traverse the view hierarchy to find the NSVisualEffectView inside NSPanel to update the image.

Interacting with DVTSourceTextView in XcodeColorSense

I work mostly with hex colors and I want a quick way to see the color. So I built XcodeColorSense — it supports hex color, RGBA, and named color.

The idea is simple. Parse the string to see if the user is typing something related to UIColor, and show a small overlay view with that color as background. The text view that Xcode uses is of type DVTSourceTextView in DVTKit framework. We also need to listen to NSTextViewDidChangeSelectionNotification which is triggered whenever any NSTextView content is changed.

func listenNotification() {  NSNotificationCenter.defaultCenter().addObserver(self, selector: #selector(handleSelectionChange(_:)), name: NSTextViewDidChangeSelectionNotification, object: nil)}

func handleSelectionChange(note: NSNotification) {  guard let DVTSourceTextView = NSClassFromString("DVTSourceTextView") as? NSObject.Type,    object = note.object where object.isKindOfClass(DVTSourceTextView.self),    let textView = object as? NSTextView  else { return }

self.textView = textView}

I had a Matcher architecture so we can detect different kinds of UIColor constructions — for example [HexMatcher](https://github.com/onmyway133/XcodeColorSense/blob/master/XcodeColorSense/Matcher/HexMatcher.swift) .

public struct HexMatcher: Matcher {

func check(line: String, selectedText: String) -> (color: NSColor, range: NSRange)? {    let pattern1 = "\"#?[A-Fa-f0-9]{6}\""    let pattern2 = "0x[A-Fa-f0-9]{6}"

let ranges = [pattern1, pattern2].flatMap {      return Regex.check(line, pattern: $0)    }

guard let range = ranges.first      else { return nil }

let text = (line as NSString).substringWithRange(range).replace("0x", with: "").replace("\"", with: "")    let color = NSColor.hex(text)

return (color: color, range: range)  }}

To render the overlay, we use NSColorWell which is good for showing a view with background. The position is determined by calling firstRectForCharacterRange and some point conversions with convertRectFromScreen and convertRect .

Using NSTask and IDEWorkspaceWindowController in XcodeWay

Finally, my beloved XcodeWay.

I found myself needing to go to different places from Xcode with the context of the current project. So I built XcodeWay as a plugin that adds lots of handy menu options under Window.

Since the plugin runs in the same Xcode process, it has access to the main menu NSApp.mainMenu?.itemWithTitle(“Window”) . There we can alter the menu. XcodeWay is designed to easily extend functionalities through its Navigator protocol.

@objc protocol Navigator: NSObjectProtocol {  func navigate()  var title: String { get }}

For folders with a static path like Provisioning Profile ~/Library/MobileDevice/Provisioning Profiles or User data Developer/Xcode/UserData , we can just construct the URL and call NSWorkspace.sharedWorkspace().openURL . For dynamic folders that vary depending on the current project, more work needs to be done.

How do we open the folder for the current project in Finder? The information for the current project path is kept inside IDEWorkspaceWindowController . This is a class that manages workspace windows in Xcode. Take a look at EnvironmentManager where we use objc_getClass to get the class definition from a string.

self.IDEWorkspaceWindowControllerClass = objc_getClass("IDEWorkspaceWindowController");

NSArray *workspaceWindowControllers = [self.IDEWorkspaceWindowControllerClass valueForKey:@"workspaceWindowControllers"];

id workSpace = nil;

for (id controller in workspaceWindowControllers) {  if ([[controller valueForKey:@"window"] isEqual:[NSApp keyWindow]]) {    workSpace = [controller valueForKey:@"_workspace"];  }}

NSString * path = [[workSpace valueForKey:@"representingFilePath"] valueForKey:@"_pathString"];

Finally, we can utilise valueForKey to get the value for any property that we think exists. This way not only do we get the project path, we also get the path to the opening file. So we can call activateFileViewerSelectingURLs on NSWorkspace to open Finder with that file selected. This is handy as users don’t need to look for that file in Finder.

Many times we want to execute some Terminal commands on the current project folder. To achieve that, we can use NSTask with launch pad /usr/bin/open and arguments [@”-a”, @”Terminal”, projectFolderPath] . iTerm, if configured probably, will open this in a new tab.

The documents for iOS 7 apps are placed in the fixed location iPhone Simulator inside Application Support. But, from iOS 8, every app has a unique UUID and their document folders are hard to predict.

~/Library/Developer/CoreSimulator/Devices/1A2FF360-B0A6-8127-95F3-68A6AB0BCC78/data/Container/Data/Application/

We can build a map and perform tracking to find the generated ID for the current project, or to check the plist inside each folder to compare the bundle identifier.

The quick solution that I came up with was to search for the most recent updated folder. Every time we build the project, or make changes inside the app, their document folder is updated. That is where we can make use of NSFileModificationDate to find the folder for the current project.

There are many hacks when working with Xcode plugins, but the results are rewarding. Every few minutes we save each day end up saving a lot of time overall.

Security and freedom

With great power comes great responsibility. The fact that plugins can do whatever they want rings an alert to security. In late 2015, there was a malware attack by distributing a modified version of Xcode, called XcodeGhost, which injects malicious code into any apps built with Xcode Ghost. The malware is believed to use the plugin mechanism among other things.

Like the iOS apps we download from the Appstore, macOS apps like Xcode are signed by Apple when we download them from the Mac Appstore or through official Apple download links.

Code signing your app assures users that it is from a known source and the app hasn’t been modified since it was last signed. Before your app can integrate app services, be installed on a device, or be submitted to the App Store, it must be signed with a certificate issued by Apple

To avoid potential malware like this, at WWDC 2016 Apple announced the Xcode Source Editor Extension as the only way to load third party extensions into Xcode. This means that, from Xcode 8, plugins can’t be loaded.

Source Editor Extension

Extension is the recommended approach to safely add functionalities in restricted ways.

App extensions give users access to your app’s functionality and content throughout iOS and macOS. For example, your app can now appear as a widget on the Today screen, add new buttons in the Action sheet, offer photo filters within the Photos app, or display a new system-wide custom keyboard.

For now, the only extension to Xcode is Source Editor, which allows us to read and modify contents of a source file, as well as read and modify the current text selection within the editor.

Extension is a new target and runs in a different process than Xcode. This is good in that it can’t alter Xcode in any ways other than conforming to XCSourceEditorCommand to modify the current document content.

protocol XCSourceEditorCommand {

  func perform(with invocation: XCSourceEditorCommandInvocation, completionHandler: @escaping (Error?) -> Void)}

Xcode 8 has lots of improvements like the new code completion features, Swift image and color literals, and snippets. This led to the deprecation of many Xcode plugins. For some indispensable plugins like XVim, this is unbearable for some people. Some old plugin features can’t be achieved with the current Source Editor Extension system.

Unless you resign Xcode

A workaround to bypass the restriction from Xcode 8 for plugins, is to replace the existing Xcode signature by a technique called resign. Resigning is very easy — we just need to create a self-signed certificate and call the codesign command. After this, Xcode should be able to load plugins.

codesign -f -s MySelfSignedCertificate /Applications/Xcode.app

It is, however, not possible to submit apps built with resigned Xcode as the signature does not match the official version of Xcode. One way is to use two Xcodes: one official for distribution and one resigned for development.

Moving to Xcode extension

Xcode extension is the way to go, so I started moving my plugins to extension. For Xmas, since it modifies view hierarchy, it can’t become an extension.

Color literal in XcodeColorSense2

For the color sense, I rewrote the extension from scratch, and called it XcodeColorSense2. This, of course, can’t show an overlay over the current editor view. So I chose to utilize the new Color literal found in Xcode 8+.

The color is shown in a small box. It may be hard to distinguish similar colors, so that’s why I also include the name. The code is simply about inspecting selections and parsing to find the color declaration.

func perform(with invocation: XCSourceEditorCommandInvocation, completionHandler: @escaping (Error?) -> Void ) -> Void {    guard let selection = invocation.buffer.selections.firstObject as? XCSourceTextRange else {      completionHandler(nil)      return    }

let lineNumber = selection.start.line

guard lineNumber < invocation.buffer.lines.count,      let line = invocation.buffer.lines[lineNumber] as? String else {      completionHandler(nil)      return    }

guard let hex = findHex(string: line) else {      completionHandler(nil)      return    }

let newLine = process(line: line, hex: hex)

invocation.buffer.lines.replaceObject(at: lineNumber, with: newLine)

completionHandler(nil)  }}

Most of the functionality is embedded inside my framework Farge, but I can’t find a way to use the framework inside Xcode extension.

Since the extension feature is only accessible through the Editor menu, we can customise a key binding to invoke this menu item. For example I choose Cmd+Ctrl+S to show and hide color information.

This is, of course, not intuitive compared to the original plugin, but it’s better than nothing.

How to debug Xcode extensions

Working and debugging extensions is straightforward. We can use Xcode to debug Xcode. The debugged version of Xcode has a gray icon.

How to install Xcode extensions

The extension must have an accompanying macOS app. This can be distributed to Mac Appstore or self-signed. I’ve written an article on how to do this.

All extensions for an app need to be explicitly enabled through “System Preferences”.

The Xcode extension only works with editor for now, so we must open a source file for the Editor menu to have effect.

AppleScript in XcodeWay

In Xcode extensions, NSWorkspace, NSTask and private class construction don’t work anymore. Since I have used Finder Sync Extension in FinderGo, I thought I could try the same AppleScript scripting for Xcode extension.

AppleScript is a scripting language created by Apple. It allows users to directly control scriptable Macintosh applications, as well as parts of macOS itself. You can create scripts — sets of written instructions — to automate repetitive tasks, combine features from multiple scriptable applications, and create complex workflows.

To try AppleScript, you can use the app Script Editor built inside macOS to write prototype functions. Function declaration starts with on and ends with end . To avoid potential conflicts with system functions, I usually use my as a prefix. Here is how I rely on System Events to get the home directory.

User interface scripting terminology is found in the “Processes Suite” of the “System Events” scripting dictionary. This suite includes terminology for interacting with most types of user interface elements, including:

• windows
• buttons
• checkboxes
• menus
• radio buttons
• text fields.

In System Events, the process class represents a running app.

Many good citizen apps support AppleScript by exposing some of their functionalities, so these can be used by other apps. Here is how I get the current song from Spotify in Lyrics.

tell application "Spotify"  set trackId to id of current track as string  set trackName to name of current track as string  set artworkUrl to artwork url of current track as string  set artistName to artist of current track as string  set albumName to album of current track as string  return trackId & "---" & trackName & "---" & artworkUrl & "---" & artistName & "---" & albumNameend tell

To get all the possible commands of a certain app, we can open the dictionary in Script Editor. There we can learn about which functions and parameters are supported.

If you think Objective C is hard, AppleScript is much harder. The syntax is verbose and error-prone. For your reference, here is the whole script file that powers XcodeWay.

To open a certain folder, tell Finder using POSIX file. I refactor every functionality into function for better code reuse.

on myOpenFolder(myPath)tell application "Finder"activateopen myPath as POSIX fileend tellend myOpenFolder

Then, to run AppleScript inside a macOS app or extension, we need to construct an AppleScript descriptor with the correct process serial number and event identifiers.

func eventDescriptior(functionName: String) -> NSAppleEventDescriptor {  var psn = ProcessSerialNumber(highLongOfPSN: 0, lowLongOfPSN: UInt32(kCurrentProcess))  let target = NSAppleEventDescriptor(    descriptorType: typeProcessSerialNumber,    bytes: &psn,    length: MemoryLayout<ProcessSerialNumber>.size  )

let event = NSAppleEventDescriptor(    eventClass: UInt32(kASAppleScriptSuite),    eventID: UInt32(kASSubroutineEvent),    targetDescriptor: target,    returnID: Int16(kAutoGenerateReturnID),    transactionID: Int32(kAnyTransactionID)  )

let function = NSAppleEventDescriptor(string: functionName)  event.setParam(function, forKeyword: AEKeyword(keyASSubroutineName))

return event}

Other tasks, like checking the current Git remote, are a bit trickier. Many times I want to share the link of the file I’m debugging to my remote teammate, so they know what file I’m referencing. This is doable by using shell script inside AppleScript .

on myGitHubURL()set myPath to myProjectPath()set myConsoleOutput to (do shell script "cd " & quoted form of myPath & "; git remote -v")set myRemote to myGetRemote(myConsoleOutput)set myUrl to (do shell script "cd " & quoted form of myPath & "; git config --get remote." & quoted form of myRemote & ".url")set myUrlWithOutDotGit to myRemoveSubString(myUrl, ".git")end myGitHubURL

We can use quoted and string concatenation to form strings. Luckily we can expose Foundation framework and certain classes. Here is how I expose NSString to take advantage of all existing functionalities. Writing string manipulation from scratch using plain AppleScript will take lots of time.

use scripting additionsuse framework "Foundation"property NSString : a reference to current application's NSString

With this we can build our other functions for string handling.

on myRemoveLastPath(myPath)set myString to NSString's stringWithString:myPathset removedLastPathString to myString's stringByDeletingLastPathComponentremovedLastPathString as textend myRemoveLastPath

One cool feature that XcodeWay supports is the ability to go to the document directory for the current app in the simulator. This is handy when we need to inspect a document to check saved or cached data. The directory is dynamic so it’s hard to detect. We can, however, sort the directory for the most recently updated. Below is how we chain multiple shell scripts commands to find the folder.

on myOpenDocument()set command1 to "cd ~/Library/Developer/CoreSimulator/Devices/;"set command2 to "cd `ls -t | head -n 1`/data/Containers/Data/Application;"set command3 to "cd `ls -t | head -n 1`/Documents;"set command4 to "open ."do shell script command1 & command2 & command3 & command4end myOpenDocument

This feature helped me a lot when developing Gallery to check whether videos and downloaded images are saved in the correct place.

However, none of the scripts seem to work. Scripting has always been part of macOS since 1993. But, with the advent of the Mac Appstore and security concerns, AppleScript finally got restricted in mid 2012. That was when App Sandbox was enforced.

App Sandbox

App Sandbox is an access control technology provided in macOS, enforced at the kernel level. It is designed to contain damage to the system and the user’s data if an app becomes compromised. Apps distributed through the Mac App Store must adopt App Sandbox.

For an Xcode extension to be loaded by Xcode, it must also support App Sandbox.

At the beginning of App Sandbox enforcement, we could use App Sandbox Temporary Exception to temporarily grant our app access to Apple Script.

This is now not possible.

The only way for AppleScript to run is if it resides inside ~/Library/Application Scripts folder.

How to install custom scripts

macOS apps or extensions can’t just install scripts into the Application Scripts by themselves. They need user consent.

One possible way to do that is to enable Read/Write and show a dialog using NSOpenPanel to ask user to select the folder to install our scripts.

For XcodeWay, I choose to provide an install shell script so the user has a quick way to install scripts.

#!/bin/bash

set -euo pipefail

DOWNLOAD_URL=https://raw.githubusercontent.com/onmyway133/XcodeWay/master/XcodeWayExtensions/Script/XcodeWayScript.scptSCRIPT_DIR="${HOME}/Library/Application Scripts/com.fantageek.XcodeWayApp.XcodeWayExtensions"

mkdir -p "${SCRIPT_DIR}"curl $DOWNLOAD_URL -o "${SCRIPT_DIR}/XcodeWayScript.scpt"

AppleScript is very powerful. All of this is made explicit so the user has complete control over which things can be done.

Like an extension, a script is done asynchronously in a different process using XPC for inter process communication. This enhances security as a script has no access to the address space to our app or extension.

More security in macOS Mojave

This year, at WWDC 2018, Apple introduced macOS Mojave which focuses on lots of security enhancements. In the Your Apps and the Future of macOS Security we can learn more about new security requirement for macOS apps. One of them is the usage description for AppleEvents.

unable to load info.plist exceptions (egpu overrides)

We used to declare usage description for many permissions in iOS, like photo library, camera, and push notifications. Now we need to declare the usage description for AppleEvents.

_Source: [https://www.felix-schwarz.org/blog/2018/08/new-apple-event-apis-in-macos-mojave](https://www.felix-schwarz.org/blog/2018/08/new-apple-event-apis-in-macos-mojave" rel="noopener" target="blank" title=")

The first time our extension tries to execute some AppleScript commands, the above dialog is shown to ask for user consent. User can grant or deny permission, but for Xcode please say yes ?

The fix for us is to declare NSAppleEventsUsageDescription in our app target. We only need to declare in the app target, not in the extension target.

<key>NSAppleEventsUsageDescription</key><string>Use AppleScript to open folders</string>

Where to go from here

Huff huff, whew! Thanks for following such a long journey. Making frameworks and tools take lots of time, especially plugins and extensions — we have to continuously change to adapt them to new operating systems and security requirements. But it is a rewarding process, as we’ve learned more and have some tools to save our precious time.

For your reference, here are my extensions which are fully open source.

• XcodeWay
• XcodeColorSense2

I hope you find something useful in the post. Here are some resources to help explore Xcode extensions further:

• Xcode Plugins by NSHipster
• Writing Xcode plugin in Swift
• Xcode 8 Plugins (Alcatraz) — The end of an era
• Using and Extending the Xcode Source Editor
• Why do I need to resign Xcode to use XVim2

If you like this post, consider visiting my other articles and apps ?