Getting Started

To begin working on TwitterTrends, unzip the file named TwitterTrends.zip, and from the TwitterTrendsStarter folder, open TwitterTrends.xcodeproj. As this project needs to use Twitter’s API endpoints, it is necessary to generate a bearer token. You have to pass that bearer token in the header of each request/API call, and Twitter checks that bearer token for authentication. If a valid bearer token is passed, Twitter sends a response with the data you request. Otherwise, Twitter will not give you access.

If you already own a Twitter Developer Account, you should be able to generate your own bearer token. But in case you do not own a developer account, you will first have to apply for it from Twitter’s developer account page.¹ Generally, it takes a day or two, or sometimes even more, for Twitter to review your application.

If your Twitter Developer Account is ready to use, generate your own bearer token by going through the article at this link.² Then, open TwitterTrendsAPI.swift in the TwitterTrends folder of the project and replace the string that says, “Your bearer token here,” with your bearer token string. Finally, you are ready to run the app.

Now, select the TwitterTrends scheme and run the project to see a screen similar to the screenshot shown in Figure 5-1.

Figure 5-1 shows the TwitterTrends app’s homescreen displaying a list of top trends trending worldwide on Twitter. TwitterTrends does this by making use of Twitter’s GET trends/place³ API endpoint. If you play with the app, you will see that you can tap each trend to get taken to a screen that displays tweets related to that trend (Figure 5-2).

Figure 5-2 shows the screen with a list of tweets which was shown after the #FarmersProtest trend was tapped in TwitterTrends’ homescreen. The list of tweets has been fetched by using Twitter’s GET search/tweets⁴ API endpoint.

To sum up, TwitterTrends lets users know about the top Twitter trends and also fetches the tweets related to those trends. But wait, did you check out the widget of TwitterTrends? TwitterTrends has a large widget (Figure 5-3) that displays the tweets related to the first trend of the array returned as a response by Twitter’s GET trends/place API endpoint.

In Figure 5-3, you can see how the large widget of TwitterTrends looks. The large widget is the only widget family that TwitterTrends has. At the top of the widget, the name of the trend is displayed. Below that, the tweets related to that trend are listed, along with some more information about each tweet. If there are more than three tweets, a Text that displays the number of tweets that could not be accommodated in the widget is shown.

Right now, if you try to edit the widget and configure it, you will see that there exists no option to do that. But in the upcoming sections, you will make your app configurable (Figure 5-4). Users will be able to choose a trend from a list of trends fetched from Twitter’s API endpoint (and not a list of hard-coded trends), and the widget will then display tweets related to that trend. This is what makes this chapter different from the previous one – fetching configuration options from a server and not hard-coding them.

Figure 5-4 displays the configuration screen of TwitterTrends’ widget that you will develop in the upcoming sections. The configuration screen consists of a parameter, Selected Trend, which is currently asking users to Choose a trend since no trend has been selected yet. After tapping Choose, users will see a screen that lists the Twitter trends trending worldwide (Figure 5-5). Those trends will be fetched from Twitter’s GET trends/place API endpoint.

From the screen shown in Figure 5-5, users can choose any one of the trends, and then the widget will display tweets related to that selected trend.

Doesn’t that sound fun? Now let’s take a look at the already existing code. We have already set up some basic stuff for you in TwitterTrends.

If you go to the Project Navigator and open the TwitterTrends project, you will see two main folders, that is, TwitterTrends and TwitterTrendsWidget. The TwitterTrends folder contains the files and folders related to the app, and the TwitterTrendsWidget folder contains the files and folders related to the widget. And there are certain files which are shared by both folders using Target Membership.

In the TwitterTrends folder, other than Assets.xcassets and Info.plist, you will see the Extensions folder that contains a file named View.swift. It contains an extension of View that helps to handle the redacted(reason:) view modifier.

The Models folder contains TrendTweets.swift, Trends.swift, and Tweets.swift, which are the models used for decoding the response data received from Twitter’s API. These files are used by both the app and the widget.

The Preview Content folder is a folder generated automatically by Xcode for storing the assets required for development purposes. Xcode does not include any assets in this folder in your release builds.

The next file is TwitterTrendsAPI.swift. It is responsible to handle communications with Twitter’s API endpoints. This file is used by both the app and the widget to fetch tweets and trends from Twitter.

There is a file named TwitterTrendsApp.swift which is the entry point of the app.

Now, the only folders remaining are ViewModel and Views. The ViewModel folder consists of TTViewModel.swift, which contains the view model used by the app. And Views contains TrendsView.swift and TweetsView.swift which contain the user interface of the screens that display the top trends and the tweets related to those trends, respectively.

That’s the description of the folders and files in the TwitterTrends folder.

Currently, there are less files and folders in TwitterTrendsWidget. In addition to Assets.xcassets and Info.plist, there is a folder called Model that contains TweetWidgetEntry.swift. This file contains a TimelineEntry called TweetWidgetEntry which is vital for your widgets to work.

The Provider folder contains TwitterProvider.swift, which is the TimelineProvider of the widget.

Likewise, you can see another folder, View. It contains LargeWidgetView.swift, which contains the user interface of your widget.

Lastly, there is a folder called Widget, and it contains TwitterTrendsWidget.swift. It is the entry point of your widget.

Throughout this chapter, you will add more files and folders in your widget’s folder and give your widget the power to fetch configuration options from a remote server.

Now, it’s finally time to start working to give your widget the capability to communicate with Twitter’s API to fetch the top trends and allow users to select any one of them to see the tweets related to that particular trend in the widget.

Time to Create a SiriKit Intent Definition File

This step is similar to that of the previous chapter. In this step, you will create an intent definition file, and using that file you will define configurable properties for your widgets. To create that file, follow the steps mentioned as follows:

1. 1.

   Right-click the TwitterTrendsWidget folder in the project and click New Group to create a new folder. Name it Intent.

    
2. 2.

   Now, right-click the Intent folder and click New File….

    
3. 3.

   In the dialog box that appears, select SiriKit Intent Definition File, name it TwitterTrends.intentdefinition, and create the file. While creating the file, make sure that both TwitterTrendsWidgetExtension and TwitterTrends targets are checked at the bottom of the dialog box.

    
4. 4.

   Open TwitterTrends.intentdefinition and click the “+” icon at the bottom left of the intent file. After that, from the list of options, click New Intent (Figure 5-6).

    

1. 5.

   Name the intent as Trends and modify some configuration of that intent. Since you are going to use the intent for widgets only, put a checkmark on Intent is eligible for widgets and remove checkmarks from Intent is user-configurable in the Shortcuts app and Add to Siri and Intent is eligible for Siri Suggestions.

    
2. 6.

   Now, add a parameter named selectedTrend in the Parameters section by clicking the “+” button below it. Parameters are the properties that users will see and modify in the configuration screen of your widget to configure your widget. The display name that is displayed in the configuration screen of your widget (Figure 5-4) is automatically set to Selected Trend.

    
3. 7.

   Then, change the type of the selectedTrend parameter to Add Type… (Figure 5-7).

    

1. 8.

   As soon as you click Add Type…, a new screen is displayed that appears similar to Figure 5-8. Change the name of the new type to SelectedTrend by typing it in the item under the TYPES header at the left.

    

In this way, you have created an intent definition file and added the parameter, selectedTrend, using which users will select a trend of their choice from the widget’s configuration screen.

Setting Up IntentHandler to Fetch Top Trends and Send Them to the Widget

Now, you have to add a mechanism to use selectedTrend parameter when the timeline is created. In the previous chapter, it was a straightforward and simple process, as you had an enum with a set of values you had defined or hard-coded. But this time, you are using a class, and things are going to be different.

So, first, you need to provide the widget the values that the selectedTrend parameter of SelectedTrend type can hold. For that, you will require an intent handler that will be responsible to fetch those values from the server and provide them to your widget.

1. 1.

   In Xcode, go to File ➤ New ➤ Target to create a new target. In the dialog box that appears, select Intents Extension and click Next.

    
2. 2.

   In the dialog box displayed, set TwitterTrendsIntent as Product Name, Swift as Language, and None as Starting Point. Make sure that Include UI Extension is not checked. And set Project to TwitterTrends and the value of Embed in Application to TwitterTrends. Then, click Finish. And click Cancel if you are asked to Activate “TwitterTrendsIntent” scheme because you will not have to activate that scheme to run your widget or app later.

   Now, a new folder called TwitterTrendsIntent is created in your project, and it contains IntentHandler.swift and Info.plist. The IntentHandler.swift file is where you will write the code to fetch the top trends from Twitter’s server and send them to your widget.

    
3. 3.

   Now, open the TwitterTrends.intentdefinition file in TwitterTrendsWidget’s Intent folder and update its Target Membership by adding a checkmark to TwitterTrendsIntent. Now, that file is accessible from TwitterTrends, TwitterTrendsWidget, and TwitterTrendsIntent.

    
4. 4.

   One thing to keep in mind is that the TwitterTrendsIntent target should know the types of intents it can support. For that, select the TwitterTrends project (and not the TwitterTrends folder) located at the top of the Project Navigator to go to project settings. Now, select the TwitterTrendsIntent target under the TARGETS section and go to its General tab.

    
5. 5.

   In the General tab of TwitterTrendsIntent, go to the Supported Intents section and click the “+” sign below it to add a new supported intent. Then the screen will look like Figure 5-9.

    

After pasting the code of Listing 5-2, you must be seeing a lot of errors. So, before describing what is happening in Listing 5-2, first let’s get rid of the errors. If you go through the error messages, you will see that Xcode is complaining about being unable to find the types Trends, TrendTweets, Trend, and Tweets. It is because TwitterTrendsAPI is now a member of the TwitterTrendsIntent target also, but the structs that it uses (TrendTweets, Trend, and Tweets) are not the members of that target. So, you need to make those structs members of TwitterTrendsIntent.

Switching to IntentConfiguration

Right now, if you build and run your project, you will see that long pressing your widgets does not give the option to Edit Widget. It is because you have still not made necessary preparations to replace StaticConfiguration with IntentConfiguration . And to use IntentConfiguration, you will need a different timeline provider than the one you are using right now. Just follow the steps given to make “the big switch” to IntentConfiguration.

Test – Test – Test!

Uninstall all the existing installations of TwitterTrends in your device or simulator. Now, select the TwitterTrends scheme and run it. To test your widget, add the TwitterTrends widget to your homescreen and try editing it. You should see a configuration screen similar to the one shown in Figure 5-4. Tap on Choose to see a screen where you can see a list of trends fetched from Twitter. This screen will look similar to Figure 5-5. From that screen, select any trend and go back to your homescreen. Now, in your widget, you should see the tweets related to that particular trend you had selected.

Awesome job! We hope you had fun.

Summary

Congratulations on making it this far! In this chapter, you learned how you can make your widget fetch data from a server so that you can use those data as configuration options for the parameter in your configurable widget. Some part of this chapter must have been like a revision of the previous chapters to you. And we hope you enjoyed following along and learning. If you have any confusions, please check out the final version of the code by opening the final project folder named TwitterTrendsFinal in TwitterTrends.zip.

Now you are able to create any kind of widgets – be it a widget that can or cannot be configured or a widget whose parameter has hard-coded configuration options or dynamic configuration options fetched from a server. You have mastered them all.

We wish you luck for the future. Happy coding!