Gorilla SDK - UXDivers/Gorilla-Player-Support GitHub Wiki

Gorilla Player SDK usage

Why the SDK ?

Gorilla Player focuses on XAML and in particular Xamarin Forms XAML. This is the only thing he understands, rest everything he cannot understand and will tend to ignore it.

That is what happens with custom renderers. Out of the box, Gorilla cannot parse what is there in your custom renderer and thus will ignore it. The same would happen with any other non-XAML artifact like custom controls, converters, static references, styles defined through platform specific means, etc. In order to fix this and to allow Gorilla to learn new tricks, you will need to instruct him with a few changes that he will need to process the preview.

There are two different ways of doing this:

Integrate Gorilla Player SDK to your application. This is usually the most common approach. It is the best approach when you want previewer very specific for your application needs, that knows all your custom stuff including assemblies, resources, platform specific styes.
Extend the Gorilla Player solution (installed as part of Gorilla installation) by adding assemblies/fonts/resources you need there. For example, if in your apps you usually use XLabs controls and Prism, you might create a version of the Gorilla Player app which is capable of previewing standard XAML + XLabs controls + Prism.

For the former approach you need to:

Add Gorilla Player SDK Nuget packages to Xamarin.iOS and Xamarin.Android projects in your solution. Packages should be added only to those projects that act as an entry point to your application (i.e. where the LoadApplication is performed).
Instruct Gorilla to instantiate the application for you.
Register the new known assemblies in the configuration object (i.e. Config, see bellow).

For the latter approach you need to:

Add the assemblies/resources you need to the player projects (Android and iOS)
Register the new known assemblies in the Config object.

What follows is an example of how to integrate Gorilla to an existent application.

Note: Starting with Gorilla 1.0.0.15 specifying the knownAssemblies in the Gorilla.json is optional, read the section titled Gorilla.json bellow for additional information.

Integrating Gorilla SDK on a project: a real case scenario

In this case we are going to add Gorilla Player as part of our Grial UI Kit application. So it can make use of custom controls and custom renderers and preview them on design time.

How to preview Grial custom renderers on Gorilla Player

Open your Visual Studio for Mac with Grial solution
Add Gorilla Player SDK Nuget packages to platform specific projects that act as an entry point to your application (i.e. Grial.iOS and Grial.Droid).
Now it is time to add some code on MainActivity.cs (and AppDelegate.cs) to launch your application in Gorilla mode and start previewing things:

Simply comment the default LoadApplication(new App()); call and, on Android, add this line:

LoadApplication (UXDivers.Gorilla.Droid.Player.CreateApplication(
    this, 
    new UXDivers.Gorilla.Config("Good Gorilla")
      // Register Grial Shared assembly
      .RegisterAssemblyFromType<UXDivers.Artina.Shared.CircleImage>()
      // Register UXDivers Effects assembly
      .RegisterAssembly(typeof(UXDivers.Effects.Effects).Assembly)
      // FFImageLoading.Transformations
      .RegisterAssemblyFromType<FFImageLoading.Transformations.BlurredTransformation>()
      // FFImageLoading.Forms
      .RegisterAssemblyFromType<FFImageLoading.Forms.CachedImage>()
    ));

...and this line on iOS AppDelegate.cs:

LoadApplication (UXDivers.Gorilla.iOS.Player.CreateApplication( 
  new  UXDivers.Gorilla.Config("Good Gorilla")
      // Register Grial Shared assembly
      .RegisterAssemblyFromType<UXDivers.Artina.Shared.CircleImage>()
      // Register UXDivers Effects assembly
      .RegisterAssembly(typeof(UXDivers.Effects.Effects).Assembly)
      // FFImageLoading.Transformations
      .RegisterAssemblyFromType<FFImageLoading.Transformations.BlurredTransformation>()
      // FFImageLoading.Forms
      .RegisterAssemblyFromType<FFImageLoading.Forms.CachedImage>()
    ));

These lines do the following things:

tell Gorilla to instantiate the application for you
configure Gorilla SDK through the Config object, saying your server is called Good Gorilla
register the assemblies UXDivers.Artina.Shared, UXDivers.Effects.Effects, FFImageLoading.Transformations.BlurredTransformation, FFImageLoading.Forms.CachedImage as a known assemblies to the SDK

New assemblies can be registered in the Config object using:

the RegisterAssembly or RegisterAssemblies method which receive an Assembly / Assembly[] respectively;
the RegisterAssemblyFromType method that receives as a generic argument any type within the assembly you want to register;
the RegisterAssembliesFromTypes is the same as RegisterAssemblyFromType but receives several generic arguments so several assemblies can be registered.

Note: RegisterAssemblyFromType<UXDivers.Artina.Shared.CircleImage>() is just a convenient way to say RegisterAssembly(typeof(UXDivers.Artina.Shared.CircleImage).GetTypeInfo().Assembly).

Build your Xamarin.iOS/Xamarin.Android project and deploy them on the Simulators or devices of your choice. Since the project now contain the Gorilla Player SDK, you will see the Gorilla Player UI running when your application starts.
Once the application starts in your device select the server you want to connect to:

Finally, open the XAML file you want to preview in your IDE (i.e. Xamarin Studio or Visual Studio). Gorilla will preview your XAML including custom controls, custom renderers, platform specific style, etc. Each time you open a XAML file Gorilla will instantly preview in all the connected devices.

Gorilla.json

Previously, Gorilla SDK required assemblies with custom stuff to be registered in two separate places, Gorilla.json and the Config object created, before calling the Xamarin Forms LoadApplication.

By specifying an assembly as known in the Gorilla.json you instruct Gorilla that it is safe to keep any reference to the assembly in the final preview. If an assembly is not among the known assemblies, Gorilla will simply remove any reference to the assembly from the preview.

The main reason for specifying the assembly in the Config object is to make sure the assembly is loaded, before any preview occurs and to make the type information available for Gorilla.

Starting in Gorilla 1.0, specifying the known assemblies in the Gorilla.json file is optional. If you don’t specify anything, Gorilla will automatically consider those assemblies referenced by your project as known. Note that registering each individual assembly in the Config object is still required. If Gorilla finds any known assemblies declared in the Gorilla.json it will consider only those and the assemblies referenced by the project will be completely ignored.

Registering assemblies in the Gorilla.json might still make sense if you want Gorilla to exclude one or more assemblies from the preview, because your player does not have it installed or for any other reason. You can download a sample of the file from here. Add it to the root of your PCL project (Build action should be None).

Trigger Status Page

Gorilla provides a Status Page where you can check error and warnings about the page being previewed. This page is automatically displayed if an error occurs. Additionally, through this page you can access the Settings Page where you can configure logging, clear image cache, etc. Gorilla does not define a default way to trigger the Status Page. In the SDK you will need to configure it yourself. The status page can be displayed by invoking method UXDivers.Gorilla.Coordinator.Instance.RequestStatusUpdate().

In the Player the status page can be displayed by pressing the Menu key in Android or by shaking the device in iOS. You can mimic the same behavior in the SDK by overriding the OnKeyUp in the MainActivity.cs:

public override bool OnKeyUp (Android.Views.Keycode keyCode, Android.Views.KeyEvent e)  
{  
	if ((keyCode == Android.Views.Keycode.F1 || keyCode == Android.Views.Keycode.Menu) && Gorilla.Coordinator.Instance != null) {  
		Gorilla.Coordinator.Instance.RequestStatusUpdate (); 
		return true; 
	} 

	return base.OnKeyUp (keyCode, e); 
}

and by registering the following Shake detector custom renderer in iOS:

iOS:

[assembly: ExportRenderer(typeof(Page), typeof(UXDivers.Gorilla.ShakeDetectionRenderer))]

Things to keep in mind

Gorilla Player app must be running on your machine. You can validate this by verifying that you can see the gorilla icon in your system tray.

Make sure your Gorilla Player is connected to the same Gorilla Server as seen in the system tray.
Ensure that your IDE is in connected state. If you are using Visual Studio you can check this from Gorilla Player Status Window. You can open this window from View/Other Windows/ Gorilla Player Status Click on Connect if not already in connected state:

If you have any issue connecting the player to the device please see our Troubleshooting Connectivity guide.