====== Getting Started ======

In this document we describes how to get started using the WebClient API for Flex. \\ 
This tutorial describes how to get started using Adobe Flash Builder specifically.

===== 1. Project Setup =====

Create a new project by selecting ''File -> New -> Flex Project''.  This prepares a new Flex project with an empty mxml application ready to go.

==== Add compiler flag ====

Because the library embeds a SWF component that integrates with flex, you must add a compiler flag to your project.

To set compiler flags, open your project properties (right-click -> properties) and select the ''Compiler''  section on the left hand side.  Add this flag to the list : 

<code mxml>-includes+=mx.managers.systemClasses.MarshallingSupport</code>

{{compiler_flag.png|}}

==== Enable direct rendering ====

the WebClient uses the Stage3D API made available by Flash Player.  To use this API, the Flash Player must be started in "direct" rendering mode.  This can be done by setting the "wmode" attribute. 

In Flash Builder you can achieve this by editing the ''index.template.html'' file in the ''html-template'' folder.

{{edit_template.png|}}

Then add this line : 

{{edit_template_wmode.png|}}

==== Add the library ====

First you should add the Flex library to your project.  By default Flash Builder will prepare a "libs" folder that contains all libraries that are automatically added to the project.  You can simply drag & drop the ''webclient_api_flex.swc'' file to this folder.

{{add_library.png|}}

==== Use the SWF file ====

The API itself is implemented in a file called ''webclient_api.swf''.  The Flex library is a wrapper around this SWF file giving easy access to the available functions and events.  As a result, the Flex library needs a reference to this SWF file before it can be used.

There are 2 ways to do this.

=== Reference the swf file on your Publisher server ===

You can configure the location of the swf file that is used, by setting the ''swfFile'' property of the ''orbit.webclient.Client'' component.  You can configure this property to reference your own Orbit Publisher server for example : 

<code mxml>
<webclient:Client id="client" width="100%" height="100%" swfFile="http://server/api/<version>/webclient_api.swf"/>
</code>

<note>Referencing the swf file on the Publisher server is highly recommended.\\ This makes it possible to update the SWF component when upgrading the server.</note>

=== Copy the swf file to your application folder ===

You can make sure the swf file exists in the same folder as your application.  When developing, you can achieve this by copying the swf file to the application 'source' folder like this : 

{{add_swf.png|}}

You can find this file in the 'api' folder of your Orbit Publisher server.  

Make sure you copy the ''webclient_api.swf'' file next to your final application as well.

===== 2. Using the component =====

Below is a simple application that handles license activation and then loads a publication.

<code mxml>
<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
               xmlns:s="library://ns.adobe.com/flex/spark" 
               xmlns:mx="library://ns.adobe.com/flex/mx"
               backgroundAlpha="0" 
               xmlns:webclient="orbit.webclient.*">
    
    <fx:Script>
        <![CDATA[
            
            import orbit.webclient.LicenseStatusCode;
            import orbit.webclient.events.ClientEvent;
            import orbit.webclient.events.LicenseEvent;
            import orbit.webclient.events.LoadPublicationEvent;

            function handleClientReady(event:ClientEvent):void
            {
                client.setDeveloperId("02462C3CA72BFFB");
                client.setProductId("696D4BD8568DD72");
                client.checkLicense();
            }
            
            function handleLicenseGranted(event:LicenseEvent):void
            {
                if (event.statusCode==LicenseStatusCode.OK)
                {
                    this.loadPublication();
                }
            }
            
            function loadPublication():void
            {
                client.setServer("http://developer.orbitgis.com/service");
                client.setCredentials("dev","dev");
                client.loadPublication("Sint-Niklaas_31370");
            }
            
            function handleLoadPublicationSuccess(event:LoadPublicationEvent):void
            {
                trace("Publication loaded: "+ event.publicationName);
            }
            
        ]]>
    </fx:Script>
    
    <webclient:Client id="client"
                      width="100%" 
                      height="100%"
                      clientReady="handleClientReady(event)"
                      licenseGranted="handleLicenseGranted(event)"
                      loadPublicationSuccess="handleLoadPublicationSuccess(event)"/>
    
</s:Application>
</code>