<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="CACHE-CONTROL" content="NO-CACHE"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no"><meta http-equiv="X-UA-Compatible" content="ie=edge"><title>Customization through the Royale API</title><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/css/styles.css"><link rel="shortcut icon" href="/img/favicon.ico"></head><body class="page post" id="main"><header class="docs-header"><div class="container"><div class="topbar"><div class="topbar-left"><a href="/"><span class="site-title">Apache Royale</span></a></div><div class="topbar-center"></div><div class="topbar-right"><button class="topMenu-dropbtn"><i class="fa fa-bars"></i>&nbsp;Menu</button><ul class="topMenu"><li><a href="/features">Features</a></li><li><a href="https://apache.github.io/royale-docs/get-started">Get Started</a></li><li><a href="/download">Download</a></li><li><a href="/docs">Docs</a></li><li><a href="/blog">Blog</a></li><li><a href="https://github.com/apache/royale-asjs/wiki/Apache-Royale-Source-Code-Repositories"><i class="fa fa-github"></i> GitHub</a></li></ul></div></div><div class="post-header"><h1>Customization through the Royale API</h1><div class="post-meta">by Carlos Rovira on August 01, 2018</div></div></div></header><div class="page-content"><div class="container"><article><p>This example shows you how to use the powerful Royale API to get access to the internal workings of components and customize them to suit your needs. As you can see, although Royale does a lot for you to simplify development, you always have full control of your code.</p><p>It uses the new Jewel UI set that supports themes and is available in <a href="https://royale.apache.org/download/">the 0.9.4 release or later</a>.</p><pre><code class="language-mxml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;j:Application xmlns:fx=&quot;http://ns.adobe.com/mxml/2009&quot;
              xmlns:j=&quot;library://ns.apache.org/royale/jewel&quot;
              xmlns:js=&quot;library://ns.apache.org/royale/basic&quot;
              xmlns:html=&quot;library://ns.apache.org/royale/html&quot;
              xmlns:models=&quot;models.*&quot;&gt;

    &lt;fx:Script&gt;
        &lt;![CDATA[
            import org.apache.royale.core.IBeadLayout;
            import org.apache.royale.core.IBeadView;
            import org.apache.royale.events.CloseEvent;
            import org.apache.royale.events.Event;
            import org.apache.royale.events.MouseEvent;
            import org.apache.royale.jewel.Alert;
            import org.apache.royale.jewel.CheckBox;
            import org.apache.royale.jewel.beads.layouts.HorizontalLayout;
            import org.apache.royale.jewel.beads.layouts.VerticalLayout;
            import org.apache.royale.jewel.beads.views.AlertView;

           private var alert:Alert;
           private var check:CheckBox;

           // Adding content to the Alert component and changing the ControlBar's Buttons Layout
           private function clickHandler(event:MouseEvent):void {
               alert = Alert.show(&quot;This example shows access to AlertView and ControlBar to add a CheckBox to the Alert's content area, expand the Button layout and change its defaults. The height of the alert is changed to 300px, too.&quot;, &quot;Customized Alert Example&quot;, 3);
               alert.addEventListener(CloseEvent.CLOSE, alertClickHandler);
                alert.height = 300;

               check = new CheckBox();
               check.selected = true;
               check.text = &quot;Buttons must fill the ControlBar's available space&quot;;
               check.addEventListener(Event.CHANGE, expandButtons);

               expandButtons();
           }
           
           private function expandButtons(event:Event = null):void {
               var alertView:AlertView = alert.getBeadByType(IBeadView) as AlertView;

               if(event == null)
               {
                   var verticalLayout:VerticalLayout = new VerticalLayout();
                   verticalLayout.gap = 9;
                   alertView.content.addBead(verticalLayout);

                   alertView.content.addElement(check);
               }

               var layout:HorizontalLayout = alertView.controlBar.getBeadByType(IBeadLayout) as HorizontalLayout;
               layout.itemsExpand = check.selected;
           }

           // Event handler function for displaying the selected Alert button.
           private function alertClickHandler(event:CloseEvent):void {
               alert.removeEventListener(CloseEvent.CLOSE, alertClickHandler);

               if (event.detail == Alert.YES)
                   status.text=&quot;You answered Yes&quot;;
               else
                   status.text=&quot;You answered No&quot;;
           }
        ]]&gt;
    &lt;/fx:Script&gt;

    &lt;j:initialView&gt;
        &lt;j:View&gt;
            &lt;j:beads&gt;
                &lt;j:HorizontalCenteredLayout/&gt;
            &lt;/j:beads&gt;

            &lt;j:Card width=&quot;350&quot;&gt;
                &lt;html:H3 text=&quot;Customization through Royale API&quot;/&gt;
                
                &lt;j:Label text=&quot;This is a complex example that adds and retrieves beads at runtime. Click the button below to display an Alert window that adds content and makes changes in some parts of the default layout.&quot;
                       multiline=&quot;true&quot;/&gt;
                &lt;j:Button text=&quot;Click Me&quot; click=&quot;clickHandler(event)&quot;/&gt;
                &lt;j:Label id=&quot;status&quot;/&gt;
            &lt;/j:Card&gt;
        &lt;/j:View&gt;
    &lt;/j:initialView&gt;

&lt;/j:Application&gt;
</code></pre><p>This example takes the <a href="https://royale.apache.org/using-jewel-alert-control/">Using the Jewel Alert Control</a> example and uses the Royale API to add content and customize some parts of the Alert.</p><p>The code is more complex than in some of our other examples, for teaching purposes:</p><ul><li>In the <strong>clickHandler</strong> method, we create an Alert control and create a CheckBox to add to the Alert's content zone. Then we call the <strong>expandButtons</strong> method to end initial customization.</li><li>The <strong>expandButtons</strong> method is where the heavy work of the Royale API happens:<ul><li>Since all components in Royale are &quot;composed&quot; through the Strand/Bead API, we want to access the view part of the Alert; in this case we're talking about AlertView.</li><li>We can access AlertView with <strong>getBeadByType</strong> that retrieves a bead by its type.</li><li>Then, for learning purposes, we create a VerticalLayout bead and add it to the Alert's content using the <strong>addBead</strong> method (you can investigate other methods in the API like <strong>removeBead</strong> as well).</li><li>We add the CheckBox created in the previous method to the Alert's content. Since this involves a call-back method and an initialization method, we only want to add the checkbox at initialization time and not each time the user clicks the CheckBox.</li><li>Finally, we retrieve the ControlBar's default HorizontalLayout and customize it to expand its items (the buttons) to fill all the available space in the control bar. We use <strong>getBeadByType</strong> again to reference the layout, and then use a method available in most Jewel Layouts called <strong>itemsExpand</strong> that expect a Boolean. When this method is set to &quot;true&quot; all items in the layout expand to use all available space.</li></ul></li></ul><h2>Where to go from here</h2><ul><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/alert">Jewel Alert Royale Docs page</a></li><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/button">Jewel Button Royale Docs page</a></li><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/checkbox">Jewel CheckBox Royale Docs page</a></li><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/label">Jewel Label Royale Docs page</a></li><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/card">Jewel Card Royale Docs page</a></li></ul><p>The result of this code snippet is the following:</p><iframe width="100%" height="400" src="/blog-examples/BE0010_Customization_through_the_Royale_API/index.html"></iframe><p>(We're using an iframe to host the actual results of this example compilation. To see the example in a separate window click <a href="/blog-examples/BE0010_Customization_through_the_Royale_API/index.html" target="_blank">this link</a>.)</p><p>Full project with source code can be found <a href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0010_Customization_through_the_Royale_API">here</a>:</p><p><a class="btn btn-download" href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0010_Customization_through_the_Royale_API"><i class="fa fa-download"></i> Project Source Code</a></p></article></div></div><footer class="footer"><div class="footer-row"><div class="footer-column"><ul class="footer-list"><li class="apacheroyale"><a href="/">Apache Royale</a></li><li><a href="/">Home</a></li><li><a href="/features">Features</a></li><li><a href="/download">Download</a></li><li><a href="/ides">IDEs and Editors</a></li><li><a href="/showcase">Showcase</a></li><li><a href="/blog">Blog</a></li><li><a href="/team">Team</a></li><li><a href="/thanks-to">Thanks To</a></li><li><a href="https://apache.org/logos/#royale"><i class="fa fa-external-link-square"></i> Logos</a></li><li><a href="https://www.apache.org/licenses/"><i class="fa fa-external-link-square"></i> Apache License v2.0</a></li></ul></div><div class="footer-column"><ul class="footer-list"><li class="documentation"><a href="/docs">Documentation</a></li><li><a href="https://apache.github.io/royale-docs/get-started">Get Started</a></li><li><a href="/docs">Docs</a></li><li><a href="/asdoc">API Reference</a></li><li><a href="https://github.com/apache/royale-asjs/wiki"><i class="fa fa-github"></i>Wiki</a></li><li><a href="https://stackoverflow.com/questions/tagged/apache-royale"><i class="fa fa-stack-overflow"></i> StackOverFlow Tag</a></li></ul><ul class="footer-list"><li class="community"><a href="/get-involved">Community</a></li><li><a href="/get-involved">Get Involved</a></li><li><a href="/mailing-lists">Mailing Lists</a></li><li><a href="/faq">FAQ</a></li></ul><ul class="footer-list"><li class="development"><a href="/source-code">Development</a></li><li><a href="https://github.com/apache/royale-asjs/wiki/Apache-Royale-Source-Code-Repositories"><i class="fa fa-github"></i> Github</a></li><li><a href="https://github.com/apache/royale-asjs/issues"><i class="fa fa-github"></i> Issues</a></li><li><a href="/source-code"><i class="fa fa-code"></i> Source Code</a></li></ul></div><div class="footer-column"><ul class="footer-list"><li class="social_t">Social</li><li><a href="https://twitter.com/apacheroyale"><i class="fa fa-twitter"></i> Twitter</a></li><li><a href="https://facebook.com/ApacheRoyaleSDK/"><i class="fa fa-facebook"></i> Facebook</a></li><li><a href="https://www.linkedin.com/groups/12118437"><i class="fa fa-linkedin"></i> LinkedIn</a></li><li><a href="/feed/index.xml"><i class="fa fa-rss"></i> RSS</a></li></ul><ul class="footer-list"><li class="apache"><a href="https://www.apache.org/">Apache</a></li><li><a href="https://www.apache.org/"><i class="fa fa-external-link-square"></i> Apache</a></li><li><a href="https://www.apache.org/foundation/contributing.html"><i class="fa fa-external-link-square"></i> Donations</a></li><li><a href="https://www.apache.org/events/current-event"><i class="fa fa-external-link-square"></i> Events</a></li><li><a href="https://www.apache.org/foundation/sponsorship.html"><i class="fa fa-external-link-square"></i> Sponsorship</a></li><li><a href="https://www.apache.org/foundation/thanks.html"><i class="fa fa-external-link-square"></i> Thanks</a></li><li><a href="https://www.apache.org/security/"><i class="fa fa-external-link-square"></i>Security</a></li></ul></div><div class="aboutusdiv"><p class="aboutus">About Us</p><p class="aboutus_p"><img class="aboutus-logo" src="/img/apache-royale-logo-footer-circle-grey.svg"><a href="/" class="aboutus_a">Apache Royale™</a> is a highly productive open source application technology for building expressive frontend applications that outputs to different formats and deploy consistently on all major browsers, desktops and devices.</p><p><img class="aboutus-apache-logo" src="/img/Apache_PoweredBy.svg"> <a href="/" class="aboutus_a">Apache Royale™</a>, <a href="https://www.apache.org" class="aboutus_a">Apache™</a> and the <a href="https://www.apache.org/foundation/press/kit/" class="aboutus_a">Apache feather logo™</a> are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. Read more about our privacy policy on our <a href="/privacy-policy">Privacy Policy page</a>.</p></div></div><div class="asf">Copyright &copy; 2017-2022 <a href="https://www.apache.org">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a></div></footer></body></html>