Getting Started
Gorilla provides realtime preview of your Xamarin Forms XAML files on multiple devices and simulators at the same time. This document will give you an overview of the components involved, how they work and which is the typical workflow when using Gorilla.
Gorilla player consists on three components:
- Desktop server App. This is where the heart of Gorilla resides. This server app will analyze your solution and command the Player Mobile apps to render your XAML as needed. The IDE addin will communicate with this server to control which XAML files should be previewed. You can interact with it through a system tray icon on Windows and menu bar on Mac.
- Player Mobile App. One or more application deployed across your Android/iOS devices or simulators. This player apps will run the Gorilla SDK, which will allow them to preview the stuff you change in your XAML files.
- IDE Addin. Visual Studio addin (available in Windows and Mac) whose main role is to control what should be previewed.
Gorilla helps you preview your XAML in realtime as you build it. In order to do so, Gorilla analyses your solution to get all the assets needed to preview your XAML and instruct all the player apps connected to the server to render it. Gorilla also monitor your solution for changes that might occurs that requires to update your preview, e.g. when you make a change to your XAML file, and automatically update the preview. Also, if Gorilla detects an error in your XAML it will display it so you can quickly correct it.
Gorilla preview is built from the XAML file you are previewing (usually called Target XAML) + other XAML files it might depends on + images + design time data. Almost anything that can be defined in XAML can be previewed by Gorilla. This includes custom controls, derived pages, converters or attached properties you might have. Through the Gorilla SDK you can preview any custom renderer, controls, converters o custom xaml element you might define.
In order to start previewing you must make sure that:
- Desktop server App is up and you are signed in.
- Player app is started and connected to the server for all the devices (or simulators) you want to preview with.
- The solution you want to preview is open in your Visual Studio and you choose which XAML file to preview.
After those steps were carried on, you should be previewing your XAML across all your devices. Each time you save the XAML file, it will instantaneously refresh across all your devices. You can interact with your UI using the device or simulator as you do with your app, by tapping, scrolling, changing orientation, etc. You can provide design time data to your XAML through the DesignTimeData.json file. Using design time data you can simulate the different states of your view models. Optionally, through the device you can trigger the status page to see possible errors, warnings and suggestions. Through the status page you can also navigate to the settings page to configure Gorilla.
If you didn't yet installed Gorilla on your desktop machine, follow the instructions described here. If you already installed Gorilla, look for the Gorilla icon in the system tray in Windows or the menu bar in Mac.
Mac
Windows
If the icon is not there, just start the Gorilla and sign in.
The blog post Gorilla Player: A Tool to Craft Beautiful XAML UIs for Xamarin.Forms illustrates how you can easly configure the Gorilla SDK in your app using the Auto Configuration feature released in Gorilla 1.5.0 (release notes).
Once Installed, if your device is connected to the same WIFI as your desktop, the mobile App will automatically discover the server. Just tap the server name, in the list of discovered servers, and you will be connected. If no severs are discovered, you might need to connect manually specifying the IP address of the server. If you have issues connecting please refer to our Connectivity Troubleshooting guide.
The add-in installed in Visual Studio will allow you to control which XAML file gets previewed. The IDE where the add-in is installed must be in the same desktop computer that Gorilla desktop app resides, since both need to access your solution in the file system.
Gorilla add-in will try to automatically connect to the Gorilla server when Visual Studio starts. If anything goes wrong it will fail silently. In order to check if you are connected to Gorilla server go to View > Other Windows > Gorilla Player Status
This will display a tool windows showing the status of the add-in among other things. If the add-in is connected you will see as follows:
If not connected just click the Connect button.
Any solution you open will be automatically registered against Gorilla, so you can preview any of the XAML files it contains. Gorilla can handle any number of solutions opened at the same time.
There are two ways for setting the target XAML:
- Follow Me Mode (default). In this mode each time you switch to a XAML file in your IDE it will be automatically previewed in all the connected devices.
- Stick to this XAML Mode. In this mode you explicitly say which XAML must be previewed. Once set, it never minds what XAML you are working in your IDE, it will stick to the specified XAML.
You can switch between this modes by going to Tools > Gorilla Player. Additionally, when you right click a XAML file you will have a "Stick Gorilla to this XAML" option, to preview the selected XAML in Gorilla.
When a XAML file is being previewed you will see a Gorilla image in the top right of your XAML document windows as shown in the image bellow:
The Gorilla Player Status tool windows will also display the path of the XAML file being previewed.
Gorilla add-in will try to automatically connect to the Gorilla server when Visual Studio for Mac starts. If anything goes wrong it will fail silently. In order to check if you are connected to Gorilla server go to Tools > Gorilla Player. If you are already connected you will see the option "Disconnect from Gorilla ()" as shown in the following image.
If you are not connected you will see the "Connect to Gorilla" option as shown in the following image:
Just click Connect to Gorilla and you should be good to go.
Any solution you open will be automatically registered against Gorilla. You can open many simultaneous solutions within Visual Studio and preview the XAML files within any of them without any additional step in Gorilla.
There are two ways for setting the target XAML:
- Follow Me Mode (default). In this mode each time you switch to a XAML file in your IDE it will be automatically previewed in all the connected devices.
- Stick to this XAML Mode. In this mode you explicitly say which XAML must be previewed. Once set, it never minds what XAML you are working in your IDE, it will stick to the specified XAML.
You can switch between this modes by going to Tools > Gorilla Player. Additionally, when you right click a XAML file you will have a "Stick Gorilla to this XAML" option, to preview the selected XAML in Gorilla.
When a XAML file is being previewed you will have a "(Gorilla)" as a postfix of the file name in the Solution Pad, as shown in the image.
Designing your screens most of the times requires design time data. It is important to have a simple, flexible and powerful way to specify the data to be bound to your XAML files while your preview. In Gorilla, design time data can be specified using a JSON file which is a very convenient way of working with your data. First of all you will need to add a file called DesignTimeData.json with build action None at the root of your PCL project (or Shared) where your XAML files resides. This JSON file can only define design time data for the XAML files within the container project. The following image shows the DesignTimeData.json for the MyCoolCompanyApp sample included with Gorilla.
In order to define the design time data for a specific XAML file, you need to define a property with the name of the XAML file in the DesignTimeData.json's root JSON object. The value of the property will be data to be bound to the page during preview. Continuing with the MyCoolCompanyApp sample, what follows is the content of the DesignTimeData.json included in the previous screenshot (only part of the data is shown to reduce size).
{
"MyPeopleTemplate.xaml": {
"Name": "John Silverstain",
"City": "MELBOURNE",
"Department": "Marketing",
"Color": "Red",
"Age": 29,
"Followers": 243,
"Photo": "friend_thumbnail_27.jpg"
},
"MyPeople.xaml": [
{
"Name": "John Silverstain",
"City": "MELBOURNE",
"Department":"Marketing",
"Color":"Red",
"Age":29,
"Followers":243,
"Photo":"friend_thumbnail_27.jpg"
},
{
"Name": "Pam Tailor",
"City": "SIDNEY",
"Department":"Design",
"Age":32,
"Followers":24,
"Photo":"friend_thumbnail_75.jpg"
}
]
}
For a detailed explanation on how to work with design time data using JSON files and other mechanisms, please read Working with Design Time Data.
Navigation pages are widely used in mobile applications. By default, Gorilla previews XAML pages without including them in a navigation page, which implies no navigation toolbar. In some cases it is important to see the toolbar, whether to have an more precise idea of how the page will looks like with it or to see stuff displayed in the toolbar itself.
This default behavior can be changed through the Gorilla.json. Gorilla.json allows to specify configuration related to how gorilla renders your stuff. The file must be added to the root of your PCL project (or shared), as shown in the following image:
In order to change the default behavior the file should look like:
{
"navigationPage":{
"all": true
}
}
This specifies that a navigation page should be added to all the pages. You can also specify which specific pages should include the navigation page. For more information please refer to the document Previewing with a Navigation Page.