Ionic UI Components

Components Palette Overview

The components PALETTE is shown to the left of the canvas, and includes the following groups of UI components:

• Appery.io components.
• AngularJS and Ionic components.
• HTML component – to write any custom HTML code.

🚧

Important Note!

Note that the option of creating new apps with the Ionic framework was removed but we still support the projects that were created with it earlier.

Component Actions

Appery.io provides a standard set of tools to copy, paste, clone (duplicate), and remove UI components. All of these actions can be accessed through the context menu.

Context Menu

To add a UI component to your app, locate it on the PALETTE and then drag and drop it to the editor page.
To manipulate it, select the component and access the context menu by clicking the gear button.
Generally, the context menu consists of the Сlone, Сopy, Paste, and Delete options. However, several UI components (for example, Card or Grid) have more than one option available from the context menu. The + button, which is duplicated by an Add item option from the drop-down menu will add another nested item to the component, for example, it will add another cell to the Grid. Depending on the situation certain options may be unavailable.

📘

Note

To delete a component, select it using breadcrumbs or OUTLINE view and click Delete.

Cloning Components

Cloning existing UI components can be useful and time-saving. A full clone of a UI component with all of the nested children, including other components will be created. To apply this feature, select the component from the menu and click Clone.
The component with the same properties appears right after the original component by default. For the most part, all UI components or their parts can be cloned, but the ability to be cloned depends on the component’s environment. Some components cannot clone their own parts, for example, you cannot clone a Button inside the Input Addon in a Bootstrap/AngularJS project. In this instance, cloning will be unavailable for the Button component.

Copying And Pasting Components

Most of the PALETTE components can be copied with all their properties and nested components by using the context menu for the selected components.
To use the copy-paste feature:

1. Click Copy to deposit the selected component in local storage, (which allows you to copy and paste for different projects and sessions).
2. Then select any container UI component. The component may be located on the same page or on the other one.
3. Open the intended destination context menu and select Paste.

📘

Note

If the Paste option is disabled, the remembered component may not be contained within the currently selected one.

Copy-Paste Hotkeys

Components can be copied and pasted via the Ctrl+C (⌘+C for Mac) and Ctrl+V (⌘+V for Mac) hotkeys as well. Some components (i.e. those not present in the PALETTE) cannot be copied, as well as sub-components (e.g. Card Item, Grid Cell, etc.).
The previously copied component cannot be pasted into the currently selected one for one of the following reasons:

• different project types (e.g. copying from an Ionic project and trying to paste into a Bootstrap project)
• incompatible components (e.g. trying to paste a Textarea component into Header Controls in Ionic index screen, which accepts only Buttons and Inputs)
• nothing to paste (in this case, the Empty Clipboard message appears)
  With Ctrl+V hotkeys (⌘+V for Mac), you can paste a component inside of the currently selected one, but also right after it. If the selected component is not a container or is incompatible with the component being pasted – the latter attempts to be pasted near the selected component (only if it is compatible with one’s parent).

📘

Note

Copying/pasting works for the active frame context only: clicking outside the DESIGN tab of the screen editor (for example, Toolbar or Project view) and applying special hotkeys will result in nothing. Click within the Project tabs: DESIGN, PROPERTIES, PALETTE panels, etc, to make the hotkeys work.

General Components Properties

Every component contains its properties; some are general, others are specific to particular components. General properties belonging to most components include:

All complex and not obvious properties are provided with tooltips: by hovering over them, you can get information on the property and how to use it.

Autocomplete

The intelligent autocomplete mechanism is available for nearly all editable properties in the PROPERTIES panel, except for the combo-boxes (they already have a predefined set of values).
To access the autocompletion window in DESIGN view, select a UI component you need and in the PROPERTIES panel, try to focus on an editable property. Press Ctrl+Space or simply start typing to invoke the drop-down with the list of available variables and functions with their types.
Code assist will suggest some scope variables and functions matching the entered letters or phase.
Now you can navigate among the alternatives using the up and down buttons. To apply the selected value, press Enter or Tab, you can also click on it with a mouse.
The autocompletion feature is available for custom attribute names. It suggests all known AngularJS directive names including custom directives.
The autocompletion drop-down is shown after typing the opening double-braces in the properties, which accept that binding.
This feature demonstrates intellectual behavior: assume that we have the scope variable people with type arr described by the following model:

arr : Array
  arr[i] : Object
    name : String
    age : String

Having added ng-repeat = person in people to a List item and trying to use person variable in other properties inside of this component you will see the variable recognized by code assist with the suggested sub-properties.

Button

The Button component is one of the most commonly used. It can navigate to a page or link, copy a property to a local storage variable or set the other component’s property, open and close popups, invoke a service or run JavaScript.

The Button component has the following properties:

Visit the Ionic documentation to read more about Buttons.

Button Group

The Button Group component includes several buttons together on a single line.
The Button Group component has the following property:

Visit the Ionic documentation to read more about Button Groups.

Card

The Card component consists of Card Items – containers that can hold any other UI component. The number of Card Items can be changed by adding or cloning them.
The Card Item has the following properties:

The available Card Item types are described below.

Default types:

• item-avatar – image that must be the first child element. It is in the form of a round avatar.
• item-avatar-right – similar to item-avatar, but the item-avatar image is shifted to the right.
• item-body – container for different content: any other components can be placed inside.
• item-default – no type is added to the item.
• item-divider – used for headers and footers.
• item-icon-left – child element icons are shifted to the left. In case there are several icons in the item, all of them will be placed within one block overlapping each other.
• item-icon-right – similar to item-icon-left, but with the icons shifted to the block on the right.
• item-image – image is stretched over the entire width of the card Item.
• item-text-wrap – card item with the text.
• item-thumbnail-left – similar to item-avatar, but instead of a round avatar there is a square thumbnail.
• item-thumbnail-right – similar to item-thumbnail-left, but a thumbnail image is shifted to the right.

Example

To modify the view of the Card or Card components, custom CSS can be used. Let’s create the app with a card similar to the one in the showcase here:

1. From the PALETTE, drag and drop the Card component.
2. Drag an Image and 2 Text components to the upper Card Item. The Image component must be the first of all child elements of the Card Item.
3. Set the Card Item type to item-avatar. For Image, click Change for the Image property and upload the image with the Media Manager.
4. Select Container = span for the first Text component and p for the second. Add any necessary text.
5. Add an Image and 3 Text components to the second Card Item and set the Item type to item-body. Define the Container for the first Text component as p.
6. Set Container = label and Class = subdued for the other two Texts.
7. Add one more Card Item and set its type = item-divider and Class = **card-item-with-buttons.
8. Drag & drop three Buttons. Add the corresponding icons and define text for the Buttons. Set Color = dark and Style = Clear for all three Buttons.
9. Lastly, click CREATE NEW > CSS, then Create CSS and enter the following code:

.subdued {
        padding-right: 10px;
        color: #888;
        text-decoration: none;
    }
    .card-item-with-buttons {
        display: flex;
        padding: 0;
    }
    .card-item-with-buttons .button {
        flex-basis: 0;
        flex-grow: 1;
        flex-shrink: 1;
        font-size: 10px;
        text-align: center;
    }
    .card-item-with-buttons .button.icon-left:before {
        float: none;
    }

📘

Note

When the Text component with Container = p is added to the Card Item, the Text property color is ignored. This comes from the Ionic CSS styles implying that the tag p is always grey:
.item p { color: #666; ... }
To change the text color, you must apply custom CSS styles or change the Container property to another property (for example, div) and use the color property.

Visit the Ionic documentation to read more about Cards.

Checkbox

The Checkbox component is an option that may be checked.
The Checkbox component has the following properties:

Visit the Ionic documentation to read more about Checkboxes.

Form

The Form component is a form with the simple HTML markup and extended classes for different styles of forms.
The Form component has the following property:

Google Map

The Google Map component allows you to embed Google Maps into your app page.
The Google Map component has the following properties:

To learn more about Google Maps directives, check the AngularJS UI documentation.
Google Map is a complex component, containing 5 main components (called directives): Google Map itself, Marker, Markers, Window and Windows.
Each directive in Appery.io contains necessary and optional (only the most commonly used) properties. The latter are added as custom attributes by default and may be deleted. You can add any other properties that are present in AngularJS-UI documentation and absent in component defaults.
A short description of each directive with their required properties is provided next.

Google Map Directive

Google Map is the main container for the map. To change its dimensions in preview, assign any class name to the map and set the desirable style via CSS. By default it’s 100% wide and 250px high.

📘

Note

The visual editor doesn’t represent any changes in the CSS styles of Google Map, they are assigned in preview.

Google Map may contain 3 types of children: Marker, Markers and Window. In the Appery.io Visual Builder, they are grouped into three areas for accessibility. Use the + buttons, which appear inside each area after selecting the map, for adding appropriate children.

Marker Directive

Marker is a single component, which has a required property coords. It should be an object containing latitude and longitude properties, typed as-is into the attribute value, or passed via scope variable.
IdKey property should be unique. To make it a simple string, use quotes (otherwise AngularJS will search the scope for a variable with a specified name).
Don’t use ng-click for indicating clicking on a marker. Use the click property instead.
For making a Marker draggable, create an object in scope, containing the property draggable = true, and pass this object name to the options property of the Marker.

Example

It's possible to specify a custom icon for a map Marker, the image file can be uploaded into project using Media Manager and define it in the Marker Properties with attribute options

{icon: 'files/images/icon_file.png'}

Markers Directive

The Markers directive is similar to the Marker directive, but it is used when many markers need to be added to the map. It overcomes the high overhead of using the ng-repeatmarker directive.
For making it work in Appery.io, in scope, you should specify the models array, which contains objects with coords and ids of each marker.
This approach assumes, that the coords property of the directive contains a special value 'self' (with quotes!) and the idKey property is empty (or equal to id).

Window Directive

The Window directive is used to display a single InfoWindow object on your map. Its content is set via the HTML property, where you can put a simple text, HTML tags or scope variables.
In Appery.io, it might be used in two ways:

1. Select a Marker and click + button inside it. A Marker's Window will be added to the marker. Since all the properties are not required, a window appears after clicking the marker. Variables used in its properties (e.g. HTML property) will be taken first from the marker’s scope.
2. Select Google Map and click the last + button. A Separate Window will be added to the map. It can be displayed without a marker, but its displaying should be controlled by the necessary property show; coords should be passed into the coords property. Variables used in properties will be taken first from google-map scope (so using {{title}} in HTML property will lead to the same title displaying in each window).

📘

Note

The last is recommended for use if you don’t need to display different windows for each marker simultaneously (otherwise, use Windows directive). You can use a single window and change its coords and show properties while clicking on each marker. This approach might be useful both with Marker and Markers directives.

Windows Directive

The Windows directive is used to display multiple InfoWindow objects on your map. It has a performance advantage over the Window directive, since you don’t have to rely on ng-repeat to instantiate multiple objects and avoid excessive DOM manipulation. The overall design of this directive is identical to Markers in how the models attribute is a replacement of ng-repeat. The same restrictions apply where every model requires an idKey which defaults on the id field of a model object.

This directive has every attribute that Window has, along with extra attributes that go along with a plural directive.

📘

Note

The Windows directive is useful for rendering a lot of windows all at once. Otherwise it is highly suggested to use Window.

API Key

The Google Map component API key is required for the component to work properly. Read how to get an API key. The API key can be set in Project > App settings > Components. The same API key will be used for all components in an app. If you are creating a hybrid app, you don't need to set any API key restrictions.

Grid

The Grid component allows you to format page content into rows and columns.
The Grid Row has the following properties:

The Grid Cell has the following properties:

Visit the Ionic documentation to read more about Grids.

Working with Ionic Grid

As you add the Grid component to the page, it has one row with two cells by default. You can add cells and rows by clicking the green plus icon in the upper right corner of the component.

📘

Note

Working with the Grid component, pay attention to the breadcrumbs above the phone frame.

• If you click + when the Grid is selected, the row will be added.
• If you click Clone Grid Cell when the GridRow is selected, the cell in the selected row will be cloned.
  The Grid component has the only one default property: Component Name. If you change the name, it will appear in the breadcrumbs.
  The Grid Row has the following default properties:
• Component Name – the name that appears in the breadcrumbs.
• Position – the default choice for aligning vertically the cells in the row, if some cell appears taller than others.
  • None – all cells are raised to the height of the tallest cell:
  • Top – every cell has its height, the top of each cell is aligned with the top of the tallest cell on the row.
  • Center – every cell has its height, the vertical center of each cell is aligned with the vertical center of the tallest cell on the row.
  • Bottom – every cell has its height, the bottom of each cell is aligned with the bottom of the tallest cell on the row.
• Responsive – used to turn each cell in a row into its own row at certain breakpoints:
  • False – all the cells stay on one row in any screen width;
  • Small – every cell turns into a row if the screen is small;
  • Medium – every cell turns into a row if the screen is medium size and smaller;
  • Large – every cell turns into a row in all sizes of the screen.

The Grid Cell has the following properties:

• Component Name – the name that appears in the breadcrumbs.
• Offset – a cell can be offset from the left.
• Position – the selected cell can be vertically aligned the way different from defined for the row. This property has the same values as described earlier for Grid Rows: None (default value), Top, Center, Bottom.
• Width – you can define the width of the selected cell. You can choose the percentage of the width or the None value. None is the default value. You only have to define the percentage for the cells that need it, and the others (with the None value) will evenly divide up the available areas.

HTML

The HTML component allows you to insert custom tags.
The HTM component has the following properties:

• Container – html, div, span.

📘

Note

Actually, the HTML component is generated only if html is selected for Container property. Otherwise, it is just a component container.

• HTML – contents of HTML component with html type.

📘

Note

You can use a special keyword %children% to insert child components in the middle of HTML content.

Icon

The Icon component allows you to add custom icons to your app.
The Icon component has the following properties:

• Color – an icon color (light, stable, positive, calm, balanced, energized, assertive, royal, dark).
• Size – small, normal, large.
• Style – an icon style.
  Ionic comes with its own free and open-sourced icon font, Ionicons, with over 500 icons to choose from.
  Simply add an icon and the Ionicon class name for the icon to show, which can be easily looked up on the Ionicons homepage.
  Also, Icons can easily be added to any button by using either the built in Ionicons, or any custom font-pack you choose.
  Visit the Ionic documentation to read more about Icons.
  AngularJS also comes with default icons that are created using SVG. Read here more about AngularJS Material icons.

Image

The Image component allows adding custom images to your app.
The Image component has the following properties:

• Alt. Text – alternative text to be displayed instead of an image.
• Dimensions:
  • Height.
  • Width.
• Image – uploads an asset.
• Responsive – automatically adjusts to fit the screen size.
• Shape – default, rounded, circle, thumbnail.
• ng-src – an alternative source to dynamically load image. Prevents the browser from loading images before the handlebars get parsed when loading dynamically. To specify the dynamic path, ng-src should be used in {{}} markup. More information about the ng-src directive is here.

Input

The Input component allows you to receive data from the app user. It may be a name, login, email, password, a word, phrase, location or anything else you need in your app.
The Input component has the following properties:

Visit the Ionic documentation to read more about Inputs.

Making the Input Required

See this blog post to learn how to make Input required.

List

The List component shows a list of items. It is designed as a simple DIV containing items without any AngularJS directives.
The List component has the following properties:

📘

Note

Setting the Class property to card makes the list look more organized. Read here for more.

The List Item has the following properties:

Select the List Item and click + to add a Button.
The List Item Button has the following properties:

Be sure not to overuse different properties (like Badge and/or Icon) with the List item button – it won’t look attractive.

📘

Note

Only one List Item Button can be added to a List Item.

All List Item side elements (for the left side: Icon Left, Picture with Type = avatar or thumbnail-left; for the right side: Button, Icon Right, Picture with Type = thumbnail-right, Item Badge) occupy the same place and overlap each other.
Visit the Ionic documentation to read more about Lists.

Radiobutton

The Radiobutton component is a group of options where only one may be checked.
The Radiobutton component has the following properties:

Visit the Ionic documentation to read more about Radiobuttons.

Range

The Range component has the following properties:

Visit the Ionic documentation to read more about Ranges.

Scroll

The Scroll component creates a scrollable container for all content inside.
It has the following properties:

📘

Note

It’s important to set the height of the scroll box as well as the height of the content to enable scrolling to have full control over scrollable areas.

Please visit this page to read more about ion-scroll.

Scrollable Image Example

To see how Scroll works, let’s create an app with a scrollable image.

1. From the Components PALETTE, drag and drop the *Scroll *component.
2. Then, drag and drop an Image component to the screen and place it into the Scroll.
3. Select the Image and, under PROPERTIES, click Change to start the Media Manager, then, upload the image file and then confirm by selecting it.
4. Now, for the Scroll component, set Direction to xy.
5. Lastly, specify its Dimensions properties Height and Width so that they are smaller than those for the image.
6. Here, the Dimensions of the image are: Height = 200px and Width = 600px.

📘

Note

Scrolling is used when the content is bigger than scroll. For example, for the above image, specify the dimensions for scroll container like the following: Height = 100px and Width = 500px or lower.

Scrollable List Example

Now, let’s create an app with a scrollable shopping list to see how scrolling works for long lists of items:

1. From the components PALETTE, drag and drop the Scrollcomponent.
2. Then, drag & drop a List component to the screen and place it into the Scroll.
3. Add as many List items as needed. (here: 50) (you may use the Clone option in the Context menu).
4. Now, define the List items' Text properties with your data.
5. Next, set Direction to y for the Scroll component.
6. Lastly, specify its Dimensions properties Height and Width so that they are smaller than those for the List. In this example, the Dimensions of the Scroll component are: Height = 500px, Width = auto.

Now, let’s modify the app to be able to scroll the content to its top on a button click:

1. In DESIGN view, for the Scroll component, set Delegate Handle to topscroll.
2. Add a Button above the Scroll component with Color = balanced, Text = To the top and ng-click = scroll().
3. Switch to SCOPE and add a new function: scroll().
4. Click Edit for it and, to get ionicScrollDelegate to work, insert the following code into the code editor:

var $ionicScrollDelegate = Apperyio.get('$ionicScrollDelegate');
$ionicScrollDelegate.$getByHandle('topscroll').scrollTop();

Now, you can get to the top of the list on one button click.

Screen

There are the following screen types in Ionic/AngularJS projects:

• index screen – the application entry point, its content is available on any app page.
• Screen – a usual screen for various applications. There are two templates: Blank Ionic Page and Ionic page with content. Find details here.
• Modal screen – a dialog invoked over the current one.
  Please visit this page to read more about Screens.

Header

Header is a fixed region at the top of a screen that can contain a title label and navigation buttons.

Footer

Footer is a region at the bottom of a screen that can contain various types of content, for example, a copyright notice, navigation buttons, or contact information.

Content

The Content area is the scrollable viewport of your app. While your headers and footers are fixed, the Content fills the remaining available space.

Side Menu

By default, Side Menus are hidden under the Content area. To open the Side Menu, swipe the content side to side.

Select

The Select component allows you to choose one item from a predefined set of values.
The Select component has the following properties:

• Text – a select label text.

The Select options have the following properties:

• Opened – opens a select (works in the Appery.io Visual Builder only and doesn’t affect the preview).
• ng-model – binds a select to a property on the scope.
• ng-options – dynamically generates a list of select options.
  Double click Options to open them.

The Select option has the following properties:

• Selected – determines if an option is selected.
• Text – an option text.
• Value – an option value.
  Visit the Ionic documentation to read more about Select.

Slide Box

The Slide Box component consists of Slide Box Items – containers that can be swiped or dragged between. Slide Box Items can hold any other UI components. The number of Slide Box Items can be changed by adding or cloning them.
The Slide Box component has the following properties:

• Active Slide Model - model to bind the current slide index to.
• Autoplay - whether the slide box should automatically slide.
• Delegate Handle - the handle used to identify this slideBox with $ionicSlideBoxDelegate
• Does Continue - whether the slide box should loop.
• On Slide Changed - expression called whenever the slide is changed. Is passed an '$index' variable.
• Pager Click - expression to call when a pager is clicked (if show-pager is true). Is passed the 'index' variable.
• Show Pager - whether a pager should be shown for this slide box.
• Slide Interval - how many milliseconds to wait to change slides (if does-continue is true). Defaults to 4000.
  All properties are optional.
  Slide Box Item has no specific properties.
  Visit the Ionic documentation to read more about Slide Box.

Spinner

The Spinner component enables you to give your users feedback that the app is processing/thinking/waiting/chilling out, or whatever you’d like it to indicate.
The Spinner component has the following properties:

• Color – a range button color (light, stable, positive, calm, balanced, energized, assertive, royal, dark).
• Spinner type – (auto, Android, Ios, Ios small, bubbles, circles, crescent, dots, lines, ripple, spiral).
• ng-show – shows or hides a property on the scope.
  Visit the Ionic documentation to read more about Spinners.
  To control the Spinner component behavior, you can create variables showSpinner1/closeSpinner1 (the flow is similar to the flow with creating the showAlert1/closeAlert1 variables when working with Alerts in Bootstrap/AngularJS projects).

Tabs

The Tabs component consists of clickable tabs. It uses a directive that allows you to add dynamic content. It is pretty similar to AngularJS tabs but uses Ionic CSS.
The Tabs component has the following properties:

• Active Tab – an active tab by default.
• Color – tabs color (light, stable, positive, calm, balanced, energized, assertive, royal, dark).
  The Tabs Item has the following properties:
• Active – determines if a tab is active.
• Heading – a text heading.

If needed, other UI components (like Button, Input, or Icon etc.) can be added to a Tabs Item.
Visit the Ionic documentation to read more about Tabs.

Text

The Text component can be used to show text on the page. It can be used for text messages (up to 2048 characters).

The Text component has the following properties:

• Color – text color can be selected from the combo box of the Ionic color list. This property allows you to apply interpolated AngularJS expressions (i.e. wrapped in {{}}). The entered value should match the {{ ... }} pattern or one of the predefined values.
• Container – a content type (span, label*, p, div, a, h1-h6). Here, HTML tags are selected as containers for text. span and label are of inline type while p and div are block elements. div can be useful for colored text in Card components.
• Text – a component property where the content is to be entered. This field can’t be empty. HTML tags are not supported. Multiline text is supported (lines will be separated with br tag).

Textarea

The Textarea component allows the app user to enter multiline text.
The Textarea component has the following properties:

Toggle

The Toggle component allows switching from one effect, feature, or state to another.
The Toggle component has the following properties:

📘

Note

Also, to apply AngularJS styling to the app platform, the ionic.Platform utility can be used. Learn here, how to use it to dynamically style app elements.