<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="copyright" content="Copyright (c) 2007, 2011 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <title>Branding</title>
  <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
</head>
<body>

  <h1>Branding</h1>
  <em>
    Note: Branding is only available when your RAP Application is used in a
    <a href = "application-setup.html#summary">setup</a> with workbench.
    When using a <q>RAP with OSGi</q> or<q>RWT Standalone</q>
    setup, see <q><a href = "application-configuration.html">Application Configuration</a></q>.
  </em>
  <h3>Introduction</h3>
  <p>
    With the help of RAP's branding features you're able to define several (visual) aspects of your
    RAP application. This includes for example the page title which is shown in the
    browser or the theme to be used for the application.
  </p>

  <h3 id="entrypoint">Creating an Entry Point</h3>
  <p>
    If you haven't done so already, define an
    <em><a href="../reference/extension-points/org_eclipse_rap_ui_entrypoint.html">org.eclipse.rap.ui.entrypoint</a></em>
    extension. Use the attribute <em>path</em> to specify the URL path for the
    entry point.
  </p>
<pre class="lang-xml">
&lt;extension point="org.eclipse.rap.ui.entrypoint"&gt;
  &lt;entrypoint id="example.entrypoint"
      class="example.MyEntryPoint"
      path="/example" /&gt;
  &lt;/entrypoint&gt;
&lt;/extension&gt;
</pre>
  <p>
    Unless you want to use the
    <em><a href="/help/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/equinox/app/IApplication.html">IApplication</a></em>
    interface (see below), let the <em>class</em> attribute point to your implementation of the
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/EntryPoint.html">EntryPoint</a></em>
    interface. (If the workbench is not used for the UI, <a href="hello-world.html#entrypoint">it is recommended</a> to extend
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/AbstractEntryPoint.html">AbstractEntryPoint</a></em>.)
  </p>

  <h3 id="iapplication">Using IApplication</h3>
  <p>
    If you want to use the <em><a href="/help/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/equinox/app/IApplication.html">IApplication</a></em>
    interface, leave the <em>class</em> attribute of your entry point extension empty and create an
    <em><a href="/help/topic/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_core_runtime_applications.html">org.eclipse.core.runtime.applications</a></em>
    extension (in <i>addition</i> to the <em>entrypoint</em> extension).
    Set your
    <em><a href="/help/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/equinox/app/IApplication.html">IApplication</a></em> implementation
    in the <em>class</em> attribute, then specify the <em>id</em> of the application extension in your entry point extensions <em>applicationId</em>:
  </p>
  <pre class="lang-xml">
&lt;extension point="org.eclipse.rap.ui.entrypoint"&gt;
  &lt;entrypoint id="example.application.entrypoint"
      path="/example"
      applicationId="example.application" /&gt;
  &lt;/entrypoint&gt;
&lt;/extension&gt;</pre>

  <h3 id="branding">Create the Branding</h3>
  <p>
    Now you can define a new branding by creating an extension for the
    <em><a href="../reference/extension-points/org_eclipse_rap_ui_branding.html">
    org.eclipse.rap.ui.branding</a></em>
    extension point. Give the branding an id, then set the same id
    in your entry point extension's <em>brandingId</em> attribute.
    The branding is now associated with your <em>EntryPoint</em> or
    <em>IApplication</em> implementation.
    A typical branding may look like this in the extension point editor:
  </p>
  <img src="../images/extension.png" alt="Extension point editor"/>
  <p>
    And here the same as it appears in the <em>plugin.xml</em>:
  </p>
  <pre class="lang-xml">
&lt;extension
    point=&quot;org.eclipse.rap.ui.branding&quot;&gt;
  &lt;branding
      id=&quot;my.project.branding1&quot;
      title=&quot;My Custom Title&quot;
      favicon=&quot;icons/favicon.png&quot;
      body=&quot;body.html&quot;
      themeId=&quot;org.eclipse.rap.design.example.business.theme&quot;&gt;
  &lt;/branding&gt;
&lt;/extension&gt;</pre>

  <h4>id</h4>
  <p>
    The id is used to reference the branding in a <em><a href="../reference/extension-points/org_eclipse_rap_ui_entrypoint.html">org.eclipse.rap.ui.entrypoint</a></em> extension.
  </p>

  <h4>themeId</h4>
  <p>
    The id of the theme to be used for this branding.
    The theme must be defined by an extension of <em><a href="../reference/extension-points/org_eclipse_rap_ui_themes.html">org.eclipse.rap.ui.themes</a></em>.
    Without this parameter, the RAP default theme will be used.
    See also <a href="theming.html">RWT Theming</a>.
  </p>

  <h4>title</h4>
  <p>
    To define the title which will be shown in the browser title or the the title of
    the browser tab, you can use the <code>title</code> attribute.
  </p>

  <h4>favicon</h4>
  <p>
    The <a href="http://en.wikipedia.org/wiki/Favicon">favicon</a> is a 16x16 pixel
    square icon shown in the browser's address bar or tab.
    To be compatible with legacy browsers, use a file in the
    <a href="http://en.wikipedia.org/wiki/ICO_%28icon_image_file_format%29">ICO format</a>.
  </p>

  <h4>body</h4>
  <p>
    An optional file containing an HTML snippet to be included in the RAP index page.
    This snippet will be included in the <em>body</em> element of the generated index page.
    That way a simple splash screen can be implemented.
    Please note that the preferred way of styling the application background is to add a theming
    for the Display background property.
  </p>

  <h4>Element additionalHeaders</h4>
  <p>
    An optional sub-element of a branding extension, that allows to add
    <em>&lt;meta&gt;</em> or <em>&lt;link&gt;</em> tags
    to the <em>&lt;head&gt;</em> of the generated index page.
    Here's an example:
  </p>
  <pre class="lang-xml">
&lt;additionalHeaders&gt;
  &lt;meta name=&quot;author&quot; content=&quot;Arthur Dent&quot;&gt;
  &lt;/meta&gt;
&lt;/additionalHeaders&gt;</pre>
  <p>
    Available tags are <em>&lt;meta&gt;</em> and <em>&lt;link&gt;</em>.
    You can add more additional attributes to each tag with the <em>attribute</em> element.
  </p>

</body>
</html>