Getting Started

Leonardo Rodríguez edited this page Nov 3, 2016 · 1 revision

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.

Anatomy

Gorilla player consists on four main components:

  • Desktop application. Is a very thin application, that acts as a host for the Server component. You can interact with it through a system tray icon on Windows and menu bar on Mac.
  • Server component. This is where the heart of Gorilla resides. The IDE add-ins will communicate with it to control which XAML files should be previewed. Also the server will command the Players to render your XAML as needed.
  • Player Apps. One or more player application deployed across your Android/iOS devices or simulators.
  • IDE Add-ins. VS or XS add0ins whose main role is to control what should be previewed.

How it works ?

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 + sample 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. Out of the box, Gorilla only allows to preview XAML that contains elements from the Xamarin Forms core framework. If you need to preview other custom elements you will need to use Gorilla SDK. By using the SDK you will be able to preview also Custom Renderers, add custom fonts and platform specific styles you might define.

Start previewing

In order to start previewing you must make sure that:

  1. Gorilla desktop application is up and you are signed in.
  2. Gorilla Mobile app is started and connected to the server for all the devices (or simulators) you want to preview with.
  3. The solution you want to preview is open in your VS or XS 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 sample data to your XAML through the SampleData.json file. Using sample 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.

Gorilla Desktop App

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

image

Windows

image

If the icon is not there, just start the Gorilla and sign in.

Gorilla Mobile App

You can install Gorilla Player in your devices directly from the Apple Store/Google Play or by deploying the app yourself. Please see detailed description of how to do it here. 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.

Working in your IDE

The add-in installed in Visual Studio or Xamarin 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.

Setting Target XAML

Visual Studio

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:

image

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:

image

The Gorilla Player Status tool windows will also display the path of the XAML file being previewed.

Xamarin Studio

Gorilla add-in will try to automatically connect to the Gorilla server when Xamarin Studio 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.

image

If you are not connected you will see the "Connect to Gorilla" option as shown in the following image:

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 Xamarin 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.

image

Sample data

Designing your screens most of the times requires sample 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, sample 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 SampleData.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 sample data for the XAML files within the container project. The following image shows the SampleData.json for the MyCoolCompanyApp sample included with Gorilla.

image

In order to define the sample data for a specific XAML file, you need to define a property with the name of the XAML file in the SampleData.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 SampleData.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 sample data using JSON files and other mechanisms, please read Working with Sample Data.

Navigation Page and other configurations

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 behaviour 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:

image

In order to change the default behaviour 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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.