Creating mobile UI

While building your user interface (UI), you may work with Pages, Components, and UI Themes.

UI themes

If you wish to change the color scheme of your app, you can specify a change for the entire app, a single page, or a component.

Project theme

To set a color scheme for all the pages and components of your app, open the App settings > General tab and set Theme and Swatch parameters. You can use the standard theme, or create custom themes.

Note: For details, read working with themes.

ui002

All the pages (and components on the pages), will inherit the scheme. However, you can change the swatch of any page or component separately.

Single page swatch

If you want to set a single page swatch, access the Properties panel. To access the Properties panel, open the page, or click the page name from the breadcrumbs above the phone frame. Select the swatch you want for the page:

ui003

If the component’s Swatch property isn’t changed, the color scheme selected in this way will be valid for the components on the page. If you want to change the swatch of any part of the page (header, footer or container), you can click that section and change the Swatch property. Only components placed on this part of the page will inherit the selected colors.

An example where the header, footer and container each have unique swatches:

ui005

Component swatch

You can also change a specific component swatch if you want it to stand out from the other components. Select the component on the page, or click its name in the breadcrumbs. On the component’s Properties panel, change the Swatch property:

ui004

Working with pages

A page is the basic building block of an app. When you build an app in Appery.io, you create pages that contain UI components, such as: buttons, input and label areas, datepickers, links, radio and checkboxes, lists, images, video, audio, map and panel elements. Each component, as well as the page itself, contains properties that can be changed.

Page properties

When you open your startScreen page (or any other page), you will see the image of your device in the middle, the Components palette to the left of it, and the Properties panel to the right:

g001

A page layout can be portrait or landscape. Change the page layout by clicking the corresponding icon on the top menu. The icons appear as you open the Page tab:

Sel0011

The Properties panel has the following elements:

  • Save As Screen Template button – the page may be saved as a template. Upon creating a new page, you will be asked to choose the template:

Sel0014

  • Screen Type – upon clicking “Change,” a “Choose Template” dialog box opens, where you can change the page template:

Sel0015

  • Show Header checkbox – if checked (default), page header appears.
  • Show Footer checkbox – if checked (default), page footer appears.
  • Swatch drop-down list – changes the swatch of the page without changing other pages. To change the theme and a swatch of the whole project, go to App settings. Read more about working with themes.
  • Name – the name of the page. The page may be called by this name. By default, the start page is called StartScreen. Other pages are called Screen1, Screen2, etc.
  • Custom Size checkbox – if checked, you can customize page sizes.
  • Dimension – width and height fields become editable when the “Custom Size” box is checked.
  • Predefined Screen Size – drop-down list of the standard page sizes. Becomes disabled when the “Custom Size” box is checked.

The page consists of three parts: Header, Container and Footer. Header and Footer may be shown or hidden. Container is the main part of the page where the components may be placed. The Navbar component may be placed only on the Header or Footer. If both Header and Footer are hidden, the NavBar component will appear hidden too. Page Header has some unique properties:

  • Back Button checkbox – if checked, a button appears in the header.
  • Back Button Text – becomes editable when “Back” button is checked.

Page template

While building your Appery.io app, you may need to have several similar pages. In this case, you can create one screen template and use it for creating other pages’ UI.

Creating screen templates

To create a screen template:

1. Include all the components you want to incorporate into your template page.

2. Select the page name and in the Property panel, click “Save As Screen Template”:

g002

3. Name the new template, and save it in the “Save As Template” dialog box:

g003

4. The created screen template appears in the list of templates in Project view (left-hand side):

g004

5. In the Components palette, a new component appears – Workarea. Drag and drop it onto the page where you plan to place the different components on different pages, and save the project:

g005

When creating a new page, or changing the Screen Type property, you can now choose your new template as the page template. If the Workarea component is not included in the template, you will not be able to make a page of this type.  The template will be inactive until you add the Workarea component:

Sel0017

Editing page templates

To edit your screen template, you can select it from the list of templates in Project view, and the Screen Template tab will open. You can drag and drop components, edit properties, and add services and events to the template like you would to a common page. The only demand that defines the templates is the Workarea component. Every screen template needs to have at least one (or more) Workareas:

g006

Note: Events and services added to the screen template cannot be edited on the page created from the template. Therefore, they will not appear on the Events or Data tabs of your page, but they will still work. The components’ properties set on the screen template can be edited only if you export the properties:

1. Click the template name:

g007

2. On the Properties panel, click the “Export Properties” button:

g008

3. Add the property name, and select the component and the attribute from the lists:

g009

4. Or click the “Populate automatically” button to access the list of standard properties for exporting:

g010

You can add and/or remove properties from the list at any time. After the properties are added, they will appear in the screen Properties panel if the template is chosen as the screen type, or if the page is created based on this template. Thus, you can customize any of the exported properties for each use of the screen template. When you edit your screen template, all the pages based on it will change at once.

Using page templates

When you create a new page, you will be asked to choose between a blank page template and the templates created by you:

g011

If you choose your template, the new page will include all the components your template includes. The workarea will be separated by rectangles:

g012

If you don’t add a component to the workarea, it will be hidden while testing and using your app:

g014 g015

When you select a page name, the custom properties defined for the screen template will appear in the Properties panel:

g016

When you edit these properties, they will only change on this page. You cannot edit any other property of the template components while building the UI.

Note: You also cannot edit events and services added to the screen template on the page created from the template. They will not appear on the Events or Data tabs of your page, but they will still work. You also cannot add events to the components from the template.

If your page was created from the screen template, besides exported properties, you can edit only the page name. Other properties are disabled:

g017

If you need to change them, you can open your screen template and edit the screen properties there, or you can click “Break Apart Screen Template” if you don’t want to edit the screen template.

g018

After you click “Break Apart Screen Template” you will see the following changes:

  • Workareas disappear from the mobile page, but all the components from the workarea stay on the page.
  • Screen properties become editable.
  • The properties of every component on the page becomes editable.

Screen type

If you have a page created from the blank page template, you can change its template by doing the following:

1. Select the page name.

2. On the Properties panel, find the Screen Type property and click “Change”:

g019

3. Choose the template:

g020

Note: When you change the screen type to Blank mobile screen, the components from your page will stay as they were. However, if you change the screen type to any other template, all the components and events from your page will be replaced with the components that belong to the selected template. Your app may have one or more pages. After you created a project, it has one page named startScreen. To open it, click Project view >Pages > startScreen:

ui006

Renaming the page

You can rename the page in two ways:

  1. Change the Name property on the page Properties panel.
  2. On Project view in the page line, click the “cog” icon and select “Rename”:

ui007

Creating a page

To create a new page, click Project view > Create New > Page:

ui008

In the open window, enter the new page name and select the template.

Removing the page

To remove the page, click the “minus (-)” icon on the page line in the Project view.

ui009

You can’t remove the last page in the project. Your app must have at least one page.

Note: You can read about page properties and page templates here.

Adding components

When you open the page, to the left of the phone frame, you’ll find a Components palette:

ug015_

To add a component to the page, just drag and drop it from the palette to the page container (some components may be placed on the page header or footer):

ca001

Note: You may need to edit the component’s properties. For detailed information about components’ properties, read UI components.

Selecting components

While working on building the UI, you may need to select a component to change its properties or to add events to it. You may easily select the component by clicking it in the phone frame. You can select multiple components by holding the <Ctrl> key and clicking the components. The similar component properties may be edited. This way you can set the same values for the properties. Events cannot be added to multiple components. If you need to work on one of the complex components (e.g., Group Buttons, List, Grid etc.), click on the component to select its element (e.g., button of the group, item of the list, cell of the grid, etc.) and use the breadcrumbs above the phone frame to select the component (not its element) itself:

ui010

Deleting components

To delete the component, select it. A small “delete” icon will appear in the upper right corner of the component:

Selection_946

Click the icon and confirm to delete.

Creating a flexible layout

When you add components to a page, they’re automatically placed under or above another, taking up the entire phone frame width:

Use the Grid component to create a more flexible layout:

By default, when the Grid component is added to a page, it has two rows and two columns. You can change the number of rows and columns in the Properties panel:

To resize the grid cell, select it, and use the mouse to resize or edit the Dimension property:

One or several components may be placed to any grid cell:

ui011

The Collapsible Set component can also be used for layouts:

Note: You can read about the Collapsible Set component properties here. When building the mobile UI, the following information may be useful:

Creating tabbed pages

To create a tabbed layout, drag and drop the NavBar component. Mark the first tab as active. The NavBar component can only go into the header or footer sections:

To define the second tab, simply create a new page and add the NavBar component to it, marking the second tab as active:

To navigate between the pages (tabs), add a click event to each tab item, and use the Navigate to Page action. You may save and use the NavBar component as a custom component.

Note: For an example of using the Navbar component as a custom component, see the building a mobile app using custom components tutorial.

Working with JavaScript

In Appery.io, you always start with a mobile web app. This means you can use any JavaScript in your app. You can use any 3rd party libraries or any JavaScript you developed yourself. There are a number of ways to add a JavaScript file (libraries) to your app:

Adding new JavaScript

1. Project View > Create New > JavaScript. Enter JavaScript file name. 2. Either:

  1. Create a blank JavaScript file.
  2. Load a file from a URL. In this case, the content of the URL will be copied to this file.
  3. Upload a file.

Load external JavaScript library

1. Go to Project View > Project > App settings > External resources. 2. Enter the URL of the JavaScript file you want to load. In this case, you are simply creating a link to a remote JavaScript file.

Using JavaScript

No matter which way the file is loaded, the JavaScript library will be available on every page in your app. For example, if there is a function called foo() in the JavaScript that you loaded, anywhere in the app you can call the function by simply entering foo().

“Run JavaScript” action

Another option is to run custom JavaScript by using the Run JavaScript action:

You can easily reference any JavaScript function in this action. For example, say you created (or loaded) a JavaScript file with a function called foo(). To invoke the function in this action, your screen would look like:

Auto-format in JavaScript editor

It’s possible to format unreadable code in the JavaScript editor by clicking “Auto Format Code”:

butt

After:

after1

“Auto Format” has hot-keys: Shift-Ctrl-F. This is very useful: if you use the JavaScript Editor in the Events panel, you might notice that there is no “Auto Format” button, but with the hot-keys, it is still possible to format your code:

events_panel

Resulting in:

eventspanelafter

Collapse code blocks

Another important feature is the ability to collapse code blocks. To collapse the block, just click the row where the block begins:

collapse2

You’ll see:

collapse3

It is also possible to do this in the Events panel.

Create & use custom components

Appery.io provides a list of standard, pre-built components, such as: Button, Link, Image etc, that can be used to design the UI. In addition, you can build your own custom components to increase this library.

What are custom components?

Similar to the use of standard components, you can also create a common design pattern in a custom component and then reuse that component multiple times in one or more Appery.io mobile UIs. For example, suppose you want to create an app with several screens: Each screen has its own content, but all the screens have the same navigation bar in the header or footer. Rather than adding the events to every NavBar item on every screen, you can use the Navbar component on one screen, set the properties, add the events, and save the component as “Custom Component”:

cc010

Once the project is saved, the new component appears in the list of custom components, and in the Components palette. Unlike screen templates, custom components provide more flexibility, because custom components allow you to add properties that will appear in the properties panel. The value of the added property can be new on every screen where the custom component is added. This behavior differs from that of screen templates, which do not have a way of changing the properties on every screen, only in the template.

Creating custom components

To create a custom component, you will need to:

  1. Drag and drop the standard component (the base of the custom component) to the screen.
  2. Set the needed properties in the custom component.
  3. Add events. Be careful when adding an Invoke service action; you may need to add components used in the service mappings.
  4. Click “Save As Custom Component,” then enter the name and the category for your custom component:

cc011

If it’s not the first custom component, you can select one of the existing component categories or enter the new category name:

cc012

When you choose the category, the new custom component will appear under the category name:

cc008

When your custom component is created, save the project. You’ll see the following changes:

  • The component will appear in the list of “Custom components” in Project view (left-hand side):

c013

  • The “component” button will appear in the Components palette:

cc004

  • The Properties panel of the component will change considerably:

cc014

  • The events added to the custom component will vanish from the Events tab. They can be edited by clicking “Edit Source” in the Properties panel.

Note: You can select only one component to save it as a custom component, but you can add more components when editing your custom component.

Editing custom components

To edit your custom component, you can click on it in the list of custom components in Project view, or click the “Edit Source” button in the Properties panel. The Custom Component tab will open:

cc007

While editing your custom component, you can drag and drop any standard or custom component from the Components palette, add events, services, and mapping.

cc015

If no single component is selected, the Properties panel contains only the “Export Properties” button. When the button is clicked, the new popup will appear, where you can add properties to any component of your custom component and select the attribute:

cc016

To add standard attributes of every component as export properties, click “Populate automatically”:

cc017

After the properties are added, they will appear in the Properties panel when the custom component is used in the UI. Thus, you can customize any of the exported property for every use of the custom component. When you edit your custom component, all of its copies used in the project will also change.

Using custom components

To use your custom components while building the UI, just drag and drop it from the Components palette to the screen. In the Properties panel, the custom properties defined for the custom component will appear:

cc018

When you edit these properties, they will change only for this copy of custom components. You cannot edit any other property of the custom component elements while building the UI.

Note: When you edit your custom component, the changes appear in all the copies of the custom component in the project. If you want the component placed in one screen to be changed only in this screen, but not when the custom component is edited, click “Break Apart Custom Component”:

cc019

The elements of the custom component will appear to be common components, and you will be able to edit all their standard properties.

Note: To get a better idea how custom components work, please try this tutorial.

Creating a master-detail page

Master-detail is a very common UI design where a list of items is displayed on the first page. When an item is clicked, the item details are shown on the next page. When building a mobile app in Appery.io, you can use one of the following approaches. Both approaches use the browser’s local storage. Understand that this is not specific to Appery.io; a similar approach is used in every other tool. We also have a step-by-step tutorial: Building a clickable list app with HTML5 local storage, which shows one of the approaches in this section. The key is knowing which item was clicked, and making the item’s ID available on the next page to display the item’s details. The first step is to display the list of items. This example uses List, but you can use any other component, such as Grid. Using JavaScript:

Screen Shot 2013-10-07 at 9.00.06 PM

When you are mapping the service to the List, you will need to add very basic JavaScript to the mapping:

Screen Shot 2013-10-07 at 9.05.44 PM

The JavaScript code looks like:

Screen Shot 2013-10-07 at 9.09.45 PM

This code adds a new list HTML attribute to the list element called data-item-id (you can call it anything else) and sets it to the current item’s Id value (from the JSON response). This will happen for every item in the list. When the list is displayed, every list item will have a new attribute that is set to the ID we need, to know which item was selected. The next step is to read the value stored when the item is clicked in the list. To do this, add a click event on the list (item):

Screen Shot 2013-10-07 at 9.16.57 PM

When an item is clicked in the list, read the value of the data-item-id attribute and save it into local storage under the itemId name. Once you have the value in local storage, you can use it to invoke a service on the next page (or any other page of the app). You will also need to add an action to navigate to the next page. For example, invoking the service using the saved value:

Screen Shot 2013-10-07 at 9.21.07 PM

Note that because you saved the value into local storage using the local storage API, itemId will not automatically be listed under “Local storage variables” on the page side. To create the variable, enter its name in “Create variable” and select Create > Local storage variable. When you navigate to the next page, you can invoke the service on the page show event.

Using a hidden label

Another approach also uses local storage, but has a slightly different setup. Instead of adding a new attribute to the element, it uses a hidden value in the list. The list contains two labels; the first label will display the item name. The second label is a hidden label, and its name has been changed to itemId:

Screen Shot 2013-10-07 at 9.32.07 PM:

The mapping will look like:

Screen Shot 2013-10-07 at 9.36.33 PM

Notice that both Name and Id are mapped to the Labels inside the List. When the List is displayed, every list item will have a hidden ID with the value you need to use on the next page. When a list item is clicked, you need to read the hidden value and save it into local storage. In the Events tab, add the Set local storage variable action:

Screen Shot 2013-10-07 at 9.34.48 PM

The local variable is called itemId, and its value is going to be set to the value of the itemId hidden label in the list. You will also need to add an action to navigate to the next page (after the local storage variable is set). Once the value is stored in local storage, you can use it on any page of the app. Because the local storage variable was created via an action, you don’t need to create it by hand for the mapping. Mapping the ID for service invocation:

Screen Shot 2013-10-07 at 9.21.07 PM

When you navigate to the next page, you can invoke the service on the page show event.

Components

Every component can be configured via its properties. To see what properties are available, simply select the component and find them on the Properties panel:

t079

You can select multiple components by holding <Ctrl> key and clicking components. The similar properties of the multiple components will be available on the Properties panel. The properties with different values will be highlighted. You can set the same values of the available properties for the selected components:

c024

Adding properties to components

For some UI components, not all possible properties are available on the Properties panel. For these cases, Appery.io has the “More Properties” button:

Via “More Properties,” you can add any attributes supported by the selected component. In fact, you are not limited to just setting properties that aren’t visible in the Properties panel; you can set any properties. For example, adding these two properties:

Will result in a mini style button with a “star” icon:

Adding events to components

When building a mobile app, many aspects of the app are based on events. For example, clicking a button is a click event, loading a page is a load event. Most of the steps the user is required to make using your app can be covered with specific events. By adding events to the component, you define actions to be executed when the event fires, e.g., navigate to another page or invoke some JavaScript.

Note: These are all just standard HTML events. All events are browser events, not Appery.io events. There are also PhoneGap events which are native device events. To add an event to a component and define an action, open the Events tab:

first_comp

If you select a component and then open the Events list, only events for that particular component will be shown. To see events/actions defined for another component, select it from the component drop-down list. To see all events defined on this page, select the page name from the drop down or click “Show All,” on the right-hand side.

Note: For more detailed information, read working with UI events and actions.

Working with CSS

The Appery.io builder uses HTML5 and jQuery Mobile components to build the mobile UI. You can always change and/or customize any styling by adding custom CSS to the app.

Creating a new CSS file

To create a new CSS file, select Create New > CSS (from Project view). Give the file a name and click “Create CSS.” This file will be included in every app page.

Applying CSS to components

Let’s say we want to customize the button style:

Selection_818

Create a new CSS file and add:

Upon running the app:

Selection_820

How do you know which CSS class to use? Run the app in the browser and use Chrome Dev Tools or Firebug to view the source:

Selection_819

If you have two or more buttons, the style will be applied to all the buttons. To apply the style to just one component, create a new CSS class. For example:

Then add .my-button class in button’s Class Name property:

Selection_823

The result:

Selection_822

Styling with JavaScript

You can also style any component by running JavaScript. Let’s say you add a Label component (called: labeljs) and you want to change its font. You could run this JavaScript upon page load:

Note: The above is the same as:

The result will look like:

Selection_824

Styling jQuery Mobile components

Styling jQuery Mobile components isn’t always simple. Please carefully review the docs or any styling examples for the component you are trying to update. In many instances, when manipulating the component via JavaScript, jQuery Mobile will require you to update the component via refresh() method.

Using the Media Manager

The Media Manager allows you to work with image files in the App Builder. You can upload, rename, delete images and select them as assets for the Image component. To open the Media Manager, click “additional menu” (the “three lines” button) in the upper-right corner of the builder and select “Media Manager”:

mm001

The Media Manager window opens and you can see all the previously uploaded images.

mm002

Uploading images

To upload a new image from your hard drive, click “Upload file”:

mm004

Click “Upload a file,” and select the files or drag and drop the files from your file manager:

mm005

Only image files can be uploaded. If you select anything but an image file, an error message will appear:

mm007

When the upload of the selected images is complete, click “Back to images list.”

Renaming images

If you click the image from the list in the Media Manager, you will see its size. You can edit its name in the Image properties block:

mm003

To save the new image name click “Rename.”

Removing images

To remove an image from the Media Manager, click the image from the list, and in the Image properties block, click “Delete.” The image will be removed.

Select an image for image component

The Image component has the Asset property:

mm006

As you click “Change,” the Media Manager opens. Here you can select the image from the list or upload a new image and select it. To select the image, click it in the list. The image will appear in the Image properties block. Then click the “Select” button (this button appears only when selecting the asset for the Image component):

mm008

Centering a component

To center the component on the page, add the following JS onscreen load event:

Where mobileimage_1 – your component name:

t080

Click “Test” to see results:

2013-04-19_2325

Custom background

You can set a custom background color or picture via simple CSS. This example uses a remote image as a background:

When you test, you will see this background:

Screen Shot 2014-02-03 at 11.28.41 AM

Image source: http://www.publicdomainpictures.net/view-image.php?image=67301&picture=balloons

To resize custom background image to fit  different screen sizes add the following JavaScript code on screen Load event:

Image below illustrates the difference between scaled background (the left one) and not scaled (the right one):
comparison

You can also upload the image to your app and use it as a background. The uploaded image is then referenced using the Appery.io JavaScript API:

If you need to set the background to a particular color:

Instead of invoking JavaScript on page show, you can also use a CSS class. For example:

Then set the class for the mobiecontainer1:

Screen-Shot-2014-02-03-at-1.54.28-PM

You could use the same approach for setting the background to an image.

Embedding a Youtube video

Appery.io now has built-in Youtube and Vimeo components. YouTube doesn’t give you a URL that can be played via an HTML5 video element. Therefore, the only option is to embed the video. An example: Run the following code on page load:

Navigating after x-seconds

This is useful if you want to create a splash-like first page and then navigate to another page. Create a page and place an image on it. Add a page load event and run this JavaScript:

page_name would be the page name to which you navigate. 1000 means that the navigation will happen after 1 second.

Custom AJAX status

To change the default loader that appears when AJAX calls perform, create a CSS file with the following code:

Change the image URL according to your uploaded loader. In the example above, the image is placed via the following path:

ajax_loader_place


Posted: August 22, 2013 Last modified: September 03, 2014