Release Notes Gorilla Player 1.0
We are glad to announce the release of Gorilla Player 1.0. This release includes several improvements, features and bug fixes. Most of the effort was in the following areas:
- Usability and documentation. The goal was to help our users in the process of knowing the big guy. We do this by - providing more guidance within the tool and better documentation explaining how to use the tool.
- Support for Images. Improve image support by providing features like clear image cache, error images, image on buttons/tabs, etc
- Sample Data. Added support for global sample data and automatic sample data generation.
- Connectivity. Improved in discoverability and troubleshooting.
- IDE Support. Added support for Visual Studio 2017 and Visual Studio for Mac
Note: Before installing Gorilla 1.0 on Windows, please manually uninstall any previous version of Gorilla you might have.
The signature of the UXDivers.Gorilla.Droid.Player.CreateApplication method used in the setup of the SDK has changed. Now, instead of the ApplicationContext`` it receives an Activity``` as its first parameter.
Previously the SDK in Android was initialized with something like:
LoadApplication (
UXDivers.Gorilla.Droid.Player.CreateApplication(
ApplicationContext,
new UXDivers.Gorilla.Config("Good Gorilla")
.RegisterAssemblyFromType<CircleImage>())
);
Now you should do:
LoadApplication (
UXDivers.Gorilla.Droid.Player.CreateApplication(
this,
new UXDivers.Gorilla.Config("Good Gorilla")
.RegisterAssemblyFromType<CircleImage>())
);
Until version 0.9.1.2 Gorilla SDK was divided in 2 nuget packages, UXDivers.GorillaPlayer.SDK and UXDivers.GorillaPlayer.Common. Starting with Gorilla 1.0 UXDivers.GorillaPlayer.Common was merged into UXDivers.GorillaPlayer.SDK.
If you have Gorilla SDK installed in your solution and you are updating it, you will need to manually remove UXDivers.GorillaPlayer.Common after upgrading the UXDivers.GorillaPlayer.SDK.
There are five main areas of improvements:
- Gorilla SDK needed notification
- Missing sample data notification
- Empty Page
- Player UI redesign
- Setting apart the “Out of the Box Player” from the “SDK Player”
Out of the box, Gorilla player can preview XAML that includes Xamarin Forms core elements + some popular libraries (e.g. Prism, FFImageLoad). When you need to render custom stuff like custom controls, custom renderers, custom converters you need to go through the Gorilla SDK path. Additionally, Gorilla will always try to preview the selected XAML even if there are elements unknown to him, which will be stripped out from the previewed page. Now Gorilla will show an notification each time it encounters something not known or that may require the SDK in order to be fully previewed.
The notification will be displayed for a couple of seconds and then it will automatically get hidden. If you tap the notification, you will have more details about the issue (as shown in the image on the right).
This particular page (taken from Grial UIKit) uses a couple of custom controls + font awesome + plus styles defined through the iOS appearance API. And that is the reason why Gorilla is complaining.
Using Gorilla SDK, all this issues would be solved and Gorilla will stop notifying as shown in the following image:
Most of the XAML pages define bindings to its data. Providing design-time data is crucial to get a relevant preview. Gorilla now analyzes XAML in conjunction with the design-time data provided through the DesignTimeData.json and alerts you if it finds out any missing design-time data.
The notification will like the following figures:
The Missing Data notification is displayed for a couple of seconds and then it will automatically hide. Tapping the notification will display detailed information about what is missing.
In the above sample it tells you that a binding to Comments was found in the XAML, but no design-time data was provided. As a result, if we scroll down to the bottom of the page we will see that there is a comment section not being displayed as shown in the next image, but is correctly displayed below that image when data is present:
This alert will stop showing up once the design-time data is provided. Currently, Gorilla will notify missing binding only for the first level bindings.
For example, if your page has:
- a title
- some content
- a list
…the alert will show up if design-time data for any of these items is missing. However, if inside the list element you have a name, photo and date, Gorilla will not complain if design time data is missing for one of those sub-elements.
Previously, when you attempted to preview an empty page, Gorilla was just showing the emptiness, which might be confusing, especially for users new to Gorilla.
Now Gorilla will notify you showing something like this:
The UI of the mobile app was completely redesigned to simplify its usage and provide better visual feedback.
See a couple of screenshots below:
Gorilla comes in two flavors: Gorilla “out of the box” Player and Gorilla SDK. Previous versions of Gorilla didn’t provide any hint about which of the flavors were being used which caused confusion most of the cases. In this new version each one has different base color and icons helping to clearly recognize which is in use:
Gorilla settings can now be configured by tapping the gear icon on the top right corner of the toolbar through the Settings page:
Through the Settings Page you can control:
- Display Global Issues. Whether if issues found at the Project level or solution level should be displayed in the status page. These errors are not displayed by default.
- Prevent Device Sleep. Self-explained. It is on by default.
- Clear Image Cache. Allows clearing image cache each time you need to (more info about image support enhancements below this topic).
- SDK might be required and Missing Sample Data. Control if the “SDK needed” and “Missing Data” notifications should be displayed.
- Log related settings. Allows turning on/off whether the log should be stored into memory or logged to console. You can set the log level and also view the log (+ pushing it to the server).
Support for images has been reimplemented (using a modified version of the amazing FFImageLoading library) in order to support the following features:
- Image Cache. Image cache can now be controlled and cleared from the Settings page.
- Error Image. An error image is displayed when an image is not found, or if an error occurred while loading it.
- Image on Button preview support. Images on Buttons are now supported in iOS. Android support is still pending.
-
Image on TabbedPage. Images on
TabbedPageare now supported.
UI Controls that display images need special treatment to properly work in Gorilla. Each time you bind an image file to an image control Gorilla will intercede to get the appropriate image from your Xamarin Forms solution and deliver it to the control.
In order to do so, Gorilla needs to know which controls are image controls and which properties need are bound to an image. By default, Gorilla uses a heuristic to determine this. Now Gorilla allows custom image properties to be marked as image properties through the Config object.
The property IsImagePropertyDiscriminator is a Func that given a PropertyInfo simply returns true if must be considered as an image property.
For example, in order to make the FFImageLoading.Forms.CachedImage previewable in Gorilla you will need to mark its Source property as an image property as follows:
var config = new Config("Good Gorilla");
config.IsImagePropertyDiscriminator = IsImageDiscriminator;
…
private static bool IsImageDiscriminator(PropertyInfo prop)
{
return prop.DeclaringType == typeof(FFImageLoading.Forms.CachedImage) &&
prop.Name == "Source";
}
By default Gorilla uses a heuristic to determine if a property must be treated as an image or not. The usage of this heuristic can also be controlled through the property UseIsImagePropertyHeuristic of the Config object. Its default value is true.
Sample data was renamed to “design-time data”, in order to be consistent with the way Xamarin calls it. We will gradually change it across our documentation and samples.
Now the SampleData.json file is called DesignTimeData.json. However, we still recognize the SampleData.json filename as valid.
Previously you can only define design time data for each page independently.
Gorilla 1.0 adds support for global design-time data, which means this data is available for all pages. This is achieved through the @Global property in DesignTimeData.json file:
{
"@Global": {
"Version":"1.0",
"Icon": "app.png"
},
"Page1.xaml": { },
"Page2.xaml": { }
}
In the above sample, Version and Icon will be merged with the properties in Page1.xaml and Page2.xaml.
If Version or Icon properties are also defined in Page1.xaml or Page2.xaml, the page specific value will take precedence over the global value.
Having accurate design time data is crucial for a good preview experience. At the same time, this is a tedious and time-consuming task. Most of the times this means a lot of duplication and inconsistencies among app data. Aiming to help in this area Gorilla 1.0 adds a Design-Time Data Generator.
Given a class in your solution, the tool generates the JSON with the required structure that can be added to the DesignTimeData.json file.
For example, let’s say we are designing a page to display a magazine article called ArticleViewPage. This page has a companion view model class called ArticleViewModel.
In order to generate the design-time data for the view model you will need to
- Find the class using the Solution Explorer
- Right click it and select Generate Designtime Data from this (see image bellow).
Note 1: You must successfully Build your project in order for this generation to work.
Note 2: The class you select must have a default constructor.
A new tool window will be displayed (Gorilla design-time data Helper) with the generated data. You might just copy the data to the clipboard and paste it into your DesignTimeData.json file, below the element ArticleViewPage.xaml. That’s it! Now you have all the data needed to preview your page.
The tool not only helps by extracting the structure of the class but also populates it with data. It instantiates your class and try to extract the value of each property from the created instance. If no value is set by the property, a value is auto-generated for it. In the example above, all the data was defined in a static class.
Please note that the tool is still in early stage, so it might fail to generate the data in some scenarios. Please, let us know how you feel about it and what would you like to see in future versions.
The tool is currently only available for Visual Studio.
The discovery process has been reimplemented in order to work appropriately in devices where it did not previously work (e.g. VS Android emulator). Its setup and configuration are still the same.
Please note that now your server might be discovered more than once, i.e. one per network interface it is bound to.
It is possible to list all the devices connected to a given server and disconnect them if needed. This functionality is available through the About Page, accessible from:
- System Tray (Win) / Menu Bar (Mac). Click on the icon and select “About Gorilla Player…”, then select “Show Details”.
- Using your Browser. Open your favorite browser and go to http://localhost:9014 (9014 is the default port, use your own if you changed it) where you will see the About Page.
The About Page will look as in the following image:
As in previous versions of Gorilla, the About Page shows relevant information about your Gorilla Server.
Now it also adds the “Connected Devices” button that once clicked will show a list of devices as shown in the following image:
It will display some useful information about each device (e.g. the version of the OS and the version of Gorilla installed on the device) and will give you the option to disconnect the device from the server.
Note that from the browser you can hit the connected devices page directly by going to http://localhost:9014/devices.html.
Xamarin Forms Control templates are now supported.
The MergedWith property in ResourceDictionaries is now supported.
A new Getting Started guide was made in order to help in the onboarding process of our users.
Also, a Troubleshooting Connectivity guide was made to help diagnose what could be wrong when devices does not connect to our server.
We added support for Visual Studio 2017 and Visual Studio for Mac.
Also Gorilla 1.0 adds support for Xamarin Studio 6+ in Windows, which was not supported out of the box by our previous release.
Previously, Gorilla SDK setup required that any assembly you wanted Gorilla to know needed to be specified in two places:
Gorilla.json- and the Configuration object created, before calling the Xamarin Forms
LoadApplication.
By specifying an assembly as known in the Gorilla.json file 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 Configuration object is to make sure the assembly is loaded, before any preview occurs and to make the type information available for Gorilla.
Starting with this release, 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 Configuration object is still required. If Gorilla finds any known assemblies declared in the Gorilla.json it will consider only those. Project referenced assemblies will not be considered at all.
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.
By default now Gorilla prevents the Device from going to Sleep so you can design your screens without interruptions. This default setting can be changed in the Settings page.
Now you can control whether Gorilla icon is shown only in the menu bar or in the menu bar and the Dock. This setting can be set through the config.json file by adding as follows:
{ "serverName":"Gorilla on Leonardos-MacBook-Pro.local", "showDock": false }
By default it will be shown in both, i.e. showDock is true.
Added the possibility to change the log level at runtime through the system tray menu and added another menu option to open the location where logs are stored.
Additionally, logging capabilities were added to the mobile app to better diagnose issues that might occur. Can be configured through Settings page.
By default the logger is configured in log level Error and to output the log to console, as shown in the following image:
Log to Memory option will store the log events in memory. Later the log can be viewed through the View Log option and also pushed to the server, as shown in the following image:
Once the log is pushed to the server it will be stored along with the regular server log.
Defining design time data for a grouped ListView is something that we already supported in Gorilla, but it was not very well documented. We added a new sample to illustrate how this can be achieved.
| GitHub | Description |
|---|---|
| #134 | Invalid XAML file definition |
| N/A | Fixed Resource not found error when resources defined at the page level where referenced within a DataTemplate
|
| #143 |
BackgroundImage not filling full screen |
| N/A | Fixed issue where images were not displayed sometimes after an error occurred. |
| N/A | Fixed -.Missing namespace definition for XXXX.- error incorrectly reported sometimes. |
| #158 | Prism App.xaml resources where not correctly recognized. |
| #149 | Errors occurs when the previewed solution is located in a directory with special characters |
| N/A | Fixed issues in the discovery mechanism causing not working in some environments. |
| #203 | There was an issue instantiating Gorilla platform specific services. Is Gorilla (+ dependencies) installed in the platform specific project? (service not found JSONLoader) |