Google Git
Sign in
apache / royale-website / refs/heads/asf-staging / . / blog / page / 6 / index.html
blob: d1d3aa609761453db5df1dc8b7cb116e9bcaeae9 [file] [log] [blame]
<!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>Apache Royale Blog</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>Apache Royale Blog</h1><div class="post-meta"></div></div></div></header><div class="page-content"><div class="container"><article><h2 class="post-title"><a href="/blog/using-view-states-to-show-or-hide-content/">Using View States to show or hide content</a></h2><div class="post-meta">by Carlos Rovira on June 06, 2018</div><div><p>This example shows you how to display or hide content in your Royale application, thanks to the <strong>View States</strong> feature. 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;&gt;
&lt;j:initialView&gt;
&lt;j:View id=&quot;view&quot;&gt;
&lt;j:states&gt;
&lt;js:State name=&quot;login&quot; /&gt;
&lt;js:State name=&quot;loggedIn&quot; /&gt;
&lt;/j:states&gt;
&lt;j:beads&gt;
&lt;js:SimpleStatesImpl/&gt;
&lt;/j:beads&gt;
&lt;j:Card id=&quot;loginForm&quot; includeIn=&quot;login&quot;&gt;
&lt;html:H1 text=&quot;Royale login&quot;/&gt;
&lt;j:TextInput id=&quot;username&quot; text=&quot;someuser&quot;/&gt;
&lt;j:TextInput id=&quot;password&quot; text=&quot;somepass&quot;&gt;
&lt;j:beads&gt;
&lt;j:PasswordInput/&gt;
&lt;/j:beads&gt;
&lt;/j:TextInput&gt;
&lt;j:Button text=&quot;Login&quot; emphasis=&quot;primary&quot; click=&quot;view.currentState = 'loggedIn'&quot; /&gt;
&lt;/j:Card&gt;
&lt;j:Card id=&quot;loggedInForm&quot; includeIn=&quot;loggedIn&quot;&gt;
&lt;html:H1 text=&quot;You are logged in!! :)&quot;/&gt;
&lt;j:Button text=&quot;Logout&quot; click=&quot;view.currentState = 'login'&quot;/&gt;
&lt;/j:Card&gt;
&lt;/j:View&gt;
&lt;/j:initialView&gt;
&lt;/j:Application&gt;
</code></pre><p>The View States feature is a way of putting different filters over part of the application so that different things appear depending on what the app is doing, what permissions the user has, what the user has just done, or some other condition. You create a series of &quot;states&quot; and associate components of your application with one or more of the states. The way you associate a component with a state is to add the includeIn attribute to the component and set the attribute equal to one or more of the available states. Once you have associated a parent component to a state, all of its children (the things &quot;inside&quot; it) are also associated to the state.</p><p>Using states gives you a lightweight and quick way of updating what the user sees, without having to provide all sorts of modules that have to be loaded and unloaded.</p><p>The example shows using states to switch between two Card components, what you see before logging in and what you see once you have logged in. To make this work you need to add the SimpleStatesImpl bead. Then define the states you need in the State class. Here, our two states are login and loggedIn. Finally, add an &quot;includeIn&quot; attribute to each Card component and associate it with a state.</p><p>When you first see the app, the currentState in the view is the first state listed in the State class: login.</p><p>When you click the button, the &quot;click&quot; function assigns a new state as the currentState. Anything that is not associated with the new state magically disappears, and anything that is associated with it is suddenly visible.</p><p>Instead of using includeIn, you have another way via dot notation in attributes, in this case notice the notation visible=&quot;true&quot; and <code>visible.&lt;state&gt;=&quot;false&quot;</code> in the following code:</p><pre><code class="language-mxml">&lt;j:Card id=&quot;loginForm&quot; visible=&quot;true&quot; visible.loggedIn=&quot;false&quot;&gt;
&lt;html:H1 text=&quot;Royale login&quot;/&gt;
&lt;j:TextInput id=&quot;username&quot; text=&quot;someuser&quot;/&gt;
&lt;j:TextInput id=&quot;password&quot; text=&quot;somepass&quot;&gt;
&lt;j:beads&gt;
&lt;j:PasswordInput/&gt;
&lt;/j:beads&gt;
&lt;/j:TextInput&gt;
&lt;j:Button text=&quot;Login&quot; emphasis=&quot;primary&quot; click=&quot;view.currentState = 'loggedIn'&quot; /&gt;
&lt;/j:Card&gt;
&lt;j:Card id=&quot;loggedInForm&quot; visible=&quot;false&quot; visible.loggedIn=&quot;true&quot;&gt;
&lt;html:H1 text=&quot;You are logged in!! :)&quot;/&gt;
&lt;j:Button text=&quot;Logout&quot; click=&quot;view.currentState = 'login'&quot;/&gt;
&lt;/j:Card&gt;
</code></pre><p>You can use it in almost any attribute you want, not only visible.</p><p>Another way to set SimpleStatesImpl is vía CSS. You can do this in MXML or in an external CSS file:</p><pre><code class="language-css">@namespace &quot;//www.w3.org/1999/xhtml&quot;;
@namespace js &quot;library://ns.apache.org/royale/basic&quot;;
global {
IStatesImpl: ClassReference(&quot;org.apache.royale.core.SimpleStatesImpl&quot;);
}
</code></pre><h2>Where to go from here</h2><ul><li><a href="https://apache.github.io/royale-docs/features/view-states">View States Royale Docs page</a></li><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/textinput">Jewel TextInput 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/card">Jewel Card Royale Docs page</a></li></ul><p>The result of this code snippet is the following:</p><iframe width="100%" height="300" src="/blog-examples/BE0008_Using_View_States_to_show_or_hide_content/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/BE0008_Using_View_States_to_show_or_hide_content/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/BE0008_Using_View_States_to_show_or_hide_content">here</a>:</p><p><a class="btn btn-download" href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0008_Using_View_States_to_show_or_hide_content"><i class="fa fa-download"></i> Project Source Code</a></p></div><h2 class="post-title"><a href="/blog/selecting-options-from-a-group-of-jewel-checkbox-controls/">Selecting options from a group of Jewel CheckBox controls</a></h2><div class="post-meta">by Carlos Rovira on May 22, 2018</div><div><p>In this example we'll show a set of Jewel <strong>CheckBox</strong> controls that let the user select one or more options in a Royale application. 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:html=&quot;library://ns.apache.org/royale/html&quot;&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function checkboxChanged(event:Event):void
{
result.text = &quot;The options selected are: &quot;;
if(chk1.selected)
result.text += chk1.value + &quot; &quot;;
if(chk2.selected)
result.text += chk2.value + &quot; &quot;;
if(chk3.selected)
result.text += chk3.value;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;j:initialView&gt;
&lt;j:View&gt;
&lt;j:beads&gt;
&lt;j:VerticalLayout gap=&quot;10&quot;/&gt;
&lt;/j:beads&gt;
&lt;html:H2 text=&quot;Selecting options from a group of Jewel Checkbox controls&quot;/&gt;
&lt;j:Label text=&quot;Which option(s) do you prefer?&quot;/&gt;
&lt;j:CheckBox id=&quot;chk1&quot; text=&quot;Option 1&quot; value=&quot;1&quot; change=&quot;checkboxChanged(event)&quot;/&gt;
&lt;j:CheckBox id=&quot;chk2&quot; text=&quot;Option 2&quot; value=&quot;2&quot; change=&quot;checkboxChanged(event)&quot;/&gt;
&lt;j:CheckBox id=&quot;chk3&quot; text=&quot;Option 3&quot; value=&quot;3&quot; change=&quot;checkboxChanged(event)&quot;&gt;
&lt;j:beads&gt;
&lt;j:Disabled id=&quot;opt3disable&quot; disabled=&quot;false&quot;/&gt;
&lt;/j:beads&gt;
&lt;/j:CheckBox&gt;
&lt;j:Label id=&quot;result&quot; text=&quot;The options selected are:&quot;/&gt;
&lt;j:Button text=&quot;disable/enable option 3&quot; emphasis=&quot;primary&quot; click=&quot;opt3disable.disabled = !opt3disable.disabled&quot;/&gt;
&lt;/j:View&gt;
&lt;/j:initialView&gt;
&lt;/j:Application&gt;
</code></pre><p>The CheckBox is a two-state button control with the following properties available:</p><ul><li><strong>text</strong>: The label description for the CheckBox</li><li><strong>value</strong>: The internal value of the CheckBox</li><li><strong>selected</strong>: If this is true it means that the CheckBox is selected; it is false otherwise</li></ul><p>Each checkbox has <strong>CLICK</strong> and <strong>CHANGE</strong> events. <strong>CLICK</strong> is dispatched when the user clicks the CheckBox, either to select it or to remove the selection. <strong>CHANGE</strong> is dispatched when the CheckBox is selected/unselected, and is used in this example to update a label with the value properties of all selected check boxes.</p><p>As a bonus, you can provide the ability to disable/enable any of the check boxes (and any other Jewel control) by adding the <strong>Disabled bead</strong> to it. In the example, see if you can have Option 3 both selected and disabled!</p><p>Adding beads lets you extend what controls can do by composition, rather than being limited to what the control inherits. The Disabled bead lets you enable or disable the control programmatically, depending on whatever you find important for your application (for instance, whether the user is logged in or has made a selection in another control that is required before selecting one of these options). We'll be talking more about beads in future posts.</p><h2>Where to go from here</h2><ul><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></ul><p>The result of this code snippet is the following:</p><iframe width="100%" height="300" src="/blog-examples/BE0007_Selecting_options_from_a_group_of_jewel_checkbox_controls/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/BE0007_Selecting_options_from_a_group_of_jewel_checkbox_controls/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/BE0007_Selecting_options_from_a_group_of_jewel_checkbox_controls">here</a>:</p><p><a class="btn btn-download" href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0007_Selecting_options_from_a_group_of_jewel_checkbox_controls"><i class="fa fa-download"></i> Project Source Code</a></p></div><h2 class="post-title"><a href="/blog/binding-the-text-property-of-a-jewel-textinput-to-update-a-text-label/">Binding the text property of a Jewel TextInput to update a text Label</a></h2><div class="post-meta">by Carlos Rovira on May 09, 2018</div><div><p>In this example we'll cover how to use the data binding feature with a Jewel <strong>TextInput</strong> field in a Royale application. 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;&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function textChanged(event:Event):void
{
result.text = &quot;The textinput text value is: &quot; + textinput.text;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;j:beads&gt;
&lt;js:ApplicationDataBinding /&gt;
&lt;/j:beads&gt;
&lt;j:initialView&gt;
&lt;j:View&gt;
&lt;j:beads&gt;
&lt;j:VerticalLayout gap=&quot;10&quot;/&gt;
&lt;/j:beads&gt;
&lt;j:Label text=&quot;Binding the text property of a Jewel TextInput field to update a text Label&quot;/&gt;
&lt;j:TextInput id=&quot;textinput&quot; change=&quot;textChanged(event)&quot;&gt;
&lt;j:beads&gt;
&lt;j:TextPrompt prompt=&quot;Using change event&quot;/&gt;
&lt;/j:beads&gt;
&lt;/j:TextInput&gt;
&lt;j:Label id=&quot;result&quot; text=&quot;The TextInput field text value is: &quot;/&gt;
&lt;j:TextInput id=&quot;databinding_ti&quot;&gt;
&lt;j:beads&gt;
&lt;j:TextPrompt prompt=&quot;Using databinding&quot;/&gt;
&lt;/j:beads&gt;
&lt;/j:TextInput&gt;
&lt;j:Label text=&quot;The TextInput field text value is: {databinding_ti.text}&quot;/&gt;
&lt;/j:View&gt;
&lt;/j:initialView&gt;
&lt;/j:Application&gt;
</code></pre><p><strong>Data binding</strong> is a general technique that binds together and synchonizes data from a provider, or source (in this case the contents of the text property of a TextInput field), and a consumer (in this case the text property of a Label). You can use data binding with many controls, variables and components to provide a powerful user experience. You can bind a List as the data provider for an ArrayList variable so the ArrayList displays details of the item the user selects in the List. Changing a Slider's value can change the width of a control or container the Slider is bound to.</p><p>In Apache Royale, you can configure data binding at different levels: Application, View, Container, ItemRenderer, and more. This follows the <strong>PAYG</strong> (Pay As You Go) philosophy that is key to the global design of Apache Royale. PAYG keeps an application as lightweight as possible, since you only add many features and functions to the components that actually need them. Other front-end technologies follow a &quot;just in case&quot; model of providing every possible function to each component even though most of those features, and the weight of that code, will serve no good use. In Royale you stay light and agile by declaring features like data binding only if the application, or some part of it, needs them.</p><p>In this example, we use data binding at the application level, since the whole example is only a few lines of code. So we use the <strong>ApplicationDataBinding</strong> bead. This bead adheres to the Application <em>strand</em>, &quot;composing&quot; or &quot;adding&quot; the binding functionality at the application level. In a more complex application, you might decide you only need data binding in a particular <strong>View</strong> or <strong>Container</strong>. Then you could use a <strong>ViewDataBinding</strong> bead, or a <strong>ContainerDataBinding</strong> bead. PAYG ensures features like data binding are only present where you really need them, and not using up system resources by sitting around in parts of the application where they will never be used.</p><p>In our example the first <strong>TextInput</strong> control uses a normal <strong>CHANGE</strong> event handler to update the text property of the Label field below it. The second TextInput control uses data binding to update the Label below it. You get the same result, but in different ways.</p><p>Notice that both TextInput controls use a <strong>TextPrompt</strong> bead that adds the prompt functionality to the control. We wanted that feature for this example; but since not every TextInput control in every application has to have a prompt, you &quot;pay&quot; for the function by adding the TextPrompt bead only where you need it: PAYG!</p><h2>Where to go from here</h2><ul><li><a href="https://apache.github.io/royale-docs/features/data-binding">Data Binding Royale Docs page</a></li><li><a href="https://apache.github.io/royale-docs/component-sets/jewel/textinput">Jewel TextInput 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></ul><p>The result of this code snippet is the following:</p><iframe width="100%" height="300" src="/blog-examples/BE0006_Binding_the_text_property_of_a_Jewel_Textinput_to_update_a_text_label/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/BE0006_Binding_the_text_property_of_a_Jewel_Textinput_to_update_a_text_label/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/BE0006_Binding_the_text_property_of_a_Jewel_Textinput_to_update_a_text_label">here</a>:</p><p><a class="btn btn-download" href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0006_Binding_the_text_property_of_a_Jewel_Textinput_to_update_a_text_label"><i class="fa fa-download"></i> Project Source Code</a></p></div><a class="btn btn-quiet" href="/blog/page/5/"><i class="fa fa-arrow-left"></i> Newer Posts</a> <a class="btn btn-quiet" href="/blog/page/7/">Older Posts <i class="fa fa-arrow-right"></i></a></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>