SafariDialog.yml

name: Modules.SafariDialog
summary: Allows a Titanium application to use the iOS Safari ViewController to create an embedded browser.
platforms: [iphone, ipad]
since: "5.1.0"
extends: Titanium.Module
osver: {ios: {min: "9.0"}}
description: |
    
    The SafariDialog module provides Titanium access to the native SFSafariViewController. This enables you to 
    deliver interactive web content in your app just like Safari, including the key Safari UI elements already 
    familiar to your users. See how to easily bring Safari features like Reader and AutoFill into your app.

    ### Requirements

    The SafariDialog module is available with the Titanium SDK starting with Release 5.1.0.
    This module only works with devices running iOS 9.
    Please make sure you have at least Xcode 7 to build to the required sources.


    ### Getting Started

    Add the module as a dependency to your application by adding a **`<module>`** item to the
    **`<modules>`** element of your `tiapp.xml` file:

        <ti:app>
          ...
          <modules>
            <module platform="iphone">ti.safaridialog</module>
          </modules>
          ...
        </ti:app>

    Use `require()` to access the module from JavaScript:

        var dialog = require("ti.safaridialog");

    The `dialog` variable is a reference to the module. Make API calls using this reference:

        if(dialog.isSupported()){
          dialog.open({
            url:"http://appcelerator.com",
            title:"Hello World",
            tintColor:"red"
          });
        }

    ### Sample Application

    The module contains a sample application in the
    `<TITANIUM_SDK_HOME>/modules/iphone/ti.safaridialog/<VERSION>/example/` folder.
properties:
  - name: supported
    summary: Indicates if SafariDialog is supported.
    type: Boolean
    osver: {ios: {min: "9.0"}}
    permission: read-only

  - name: opened
    summary: Indicates is SafariDialog is open.
    type: Boolean
    osver: {ios: {min: "9.0"}}
    permission: read-only
    
  - name: tintColor
    summary: The view's tintColor. This property is applicable on iOS 7 and greater. 
    description: |
        This property is a direct correspondant of the tintColor property of UIView on iOS. 
        If no value is specified, the tintColor of the View is inherited from its superview. 
    type: String
    osver: {ios: {min: "9.0"}}
    
  - name: barColor
    summary: Background color for the nav bar, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>. This property
        is only available in iOS 10 and later and will be ignored on older versions.
    type: String
    osver: {ios: {min: "10.0"}}
    since: 6.0.0

methods:
  - name: isOpen
    summary: Indicates if SafariDialog is open.
    osver: {ios: {min: "9.0"}}
    returns:
        type: Boolean

  - name: isSupported
    summary: Indicates if SafariDialog is supported.
    osver: {ios: {min: "9.0"}}
    returns:
        type: Boolean

  - name: open
    summary: Opens the SafariDialog with the options provided.
    description: |
      var dialog = require("ti.safaridialog");
       if(dialog.isSupported()){
          dialog.open({
              url:"http://appcelerator.com",
              title:"Hello World",
              tintColor:"red"
          });
       }
    osver: {ios: {min: "9.0"}}
    parameters:
      - name: params
        summary: |
            Dictionary containing the following properties:

              * `url` (String): Required field.  The URL to be opened in the SafariDialog. 
              * `entersReaderIfAvailable` (Boolean): Optional field.  Indicates if the Safari Reader version of content should be shown automatically.
              * `title` (String): Optional field.  Sets the title of the page displayed. 
              * `tintColor` (String): Optional field.  The tintColor applied to SafariDialog.

        type: Dictionary

  - name: close
    summary: Programmatically closes the SafariDialog.
    description: |
      var dialog = require("ti.safaridialog");
       if(dialog.isOpen()){
          dialog.close();
       }
    osver: {ios: {min: "9.0"}}
events:
  - name: open
    summary: |
      The open event is fired after the SafariDialog has opened.
    properties:
      - name: url
        summary: The URL provided when opening the SafariDialog
        type: String
  - name: close
    summary: |
      The close event is fired when the SafariDialog is closed by the user or programmatically.
    properties:
      - name: url
        summary: The URL provided when opening the SafariDialog
        type: String
  - name: load
    summary: Fired when the initial URL load is complete.
    description: |
        This event is invoked when the safari dialog completes the loading of the URL that you pass to
        its initializer. It is not invoked for any subsequent page loads in the same safari dialog instance.
        Note: This event is available in Titanium SDK 6.0.0 and later.
    properties:
      - name: url
        summary: The URL provided when opening the SafariDialog
        type: String
      - name: success
        summary: Returns `true` if loading completed successfully, `false` otherwise.
        type: Boolean