Mind is Software

Ying’s thoughts about software and business

Ionic Patterns

This is a note of Ionic patterns.

1 Basic Styles

The src/app/app.scss is the main style file that declares global styles. The src/theme/variable.scss is used to customize shared variables such as different colors. The theming variable page lists all variables. There is a .scss file for each component that defines styles for the corresponding component.

There are three methods to theme an Ionic application and they are listed in the order of preference: attributes, SASS variables, and custom styles in .scss file.

1.1 Element Attributes

Add an attribute to an element is the easies method to customize styules. Ionic comes with the following attributes:

  • Colors: Use color="primary"to change the color of an element. Colors include primary, secondary, danger, light, and dark.
  • Generic: disabled adds disabled style, ion-fixed adds fixed style (no scrolling), tappable adds quick click event.
  • ion-list: no-lines and inset.
  • ion-item:
    • detail-none and detail-push hides or displays the arrow icon on a list item.
    • item-left, item-right, item-content specifies the position.
    • text-wrap wraps text onto the next line.
    • ion-item can also be used as an attribute to make a clickable list item. For example, <button ion-item></button>.
  • ion-input: autofocus gives focus to the input element.
  • ion-label: fixed positions label to the left of the input element. floating makes label to float up. stacked position label above the input element.
  • ion-header: no-border removes the border. transparent adds transparent background.
  • ion-buttons: left, right, start and ends position the button.
  • button:
    • ion-button applies ionic button style – always use this.
    • icon-only means the button only contains an ion-icon.
    • icon-right and icon-left position ion-icon inside of the button.
    • full makes the button full width.
    • block and round styles the button as a block or round button.
    • outline makes an outline button.
    • large and small set the size.
  • Content space
    • padding: padding-horizontal, padding-vertical, padding-left, padding-right, padding-top, and padding-bottom adds padding to the side(s).
    • no-padding removes padding.
    • margin, margin-left, margin-right, margin-top, margin-bottom, margin-horizontal, margin-vertical adds a margin.
    • no-margin removes a margin.
  • Text
    • Text alignment: text-left, text-right, text-start, text-end, text-center, text-justify, text-wrap, and text-nowrap.
    • Text transformation: text-uppercase, text-lowercase, and text-capitalize.
    • Responsive attributes: text-{modifier}, text-{bp}-{modifier}. The {bp} is one of sm, md, lg, and xl. The {modifier} is any of the left, right, start, end, center, justify, wrap, no-wrap, uppercase, lowercase, and capitalize.
  • Element placement
    • Float elements: float-left, float-righ, float-start, and float-end.
    • Responsive: float-{bp}-{modifier}.

To set attribute dynamically, use [att.attr-name]="express".

1.2 Responsive Grid

A grid is made up of rows and columns. Contents can only be placed within columns. Each row can have up to 12 columns. The size can be xs, sm, md, lg, and xl.

  • ion-grid: no-padding removes padding from the grid and the immediate children columns. fixed set max width based on teh screen size.
  • ion-row:
    • vertical alignment: align-items-start, align-items-center, align-items-end, align-items-stretch, align-items-baseline.
    • horizontal aligment: justify-content-start, justify-content-center, justify-content-end, justify-content-around, and justify-content-between.
    • wrap: nowrap forces the columns to a single row. wrap-reverse will wrap in reverse.
  • ion-col:
    • vertical alignment: align-self-start, align-self-center, align-self-end, align-self-stretch, and align-self-baseline.
    • width: col-{num} or col-{bp}-{num} where the {num} is a number from 1 to 12.
    • stack to horizontal: col-{num} col-{bp} to specify the stack break point.
    • reorder:
    • offset-{num} or offset-{bp}-{num} add offset by the specified number of columns.
    • push-{num} or push-{bp}-{num} adjust the left.
    • pull-{num} or pull-{bp}-{num} adjust the right.

2 Page Structure

2.1 Root Level Components

An ionic page has three root level components: ion-header, ion-content, and ion-footer. ion-header and ion-footer are fixed components that don’t scroll. They hold the navbar and toolbar components.

The ion-header and ion-footer have an attribute no-border that removes border or box-shadow. They usally contain a toolbar or a navbar.

The ion-header usually has an ion-navbar or ion-toolbar that has a ion-title and some buttons.

2.2 Toolbar and NavBar

Both toolbar ion-toolbar and navbar ion-navbar can contain ion-title, any number of buttons, a segment, or a searchbar. The toolbar can be placed inside ion-header, ion-footer, and ion-content (will scroll with the content). Navbar acts as the toolbar but comes with a back button and can only be placed inside ion-header. Navbar is part of the dynamic navigation stack while the toolbar is a static component.

2.1.1 NavBar

Navbar can be configured via three methods: call the setBackButtonText() method, set hideBackButton attribute and config params in IonicModule:

IonicModule.forRoot(MyApp, {
  backButtonText: "", // the back text
  backButtonIcon: "arrow-back" // the back icon
});

The following code can emulate navbar using toolbar:

<ion-toolbar>  
  <button ion-button clear small navPop>  
    <img src="assets/image/back.png" />  
  </button>
  ...
</ion-toolbar>

2.1.2 ToolBar

A toolbar usually has some buttons and a title. A toolbar can be used after a navbar as a subheader.

Except the menuToggle button, buttons placed in a toolbar should be inside an ion-buttons element. The position can be set using an attribute of start, end, left, and right.

2.3 Menu Component

A menu is a navigation drawer that slides from the side of the current view. It should be a sibling to the app’s content element. Multiple menus can be attached to a content. Typical binding code is below:

<ion-menu [content]="mycontent">
...
</ion-menu>
<ion-nav #mycontent [root]="rootPage"></ion-nav>

There are several methods to open or close a menu: add a button in navbar or toolbar with MenuToggle directive, close menu using MenuClose directive, inject MenuController and call its methods. By default, only root page navbar shows a menu button, to make it persistent in all pages, set persistent="true" on the ion-menu element.

A menu has three display types: overlay (Android default), reveal (iOS default), and push.

A menu is like a page that can have ion-header, ion-content and ion-footer.

2.4 Navigation

If the target page is a child of the current view, push to the current stack thus a user can navigate back to the previous view. If it is a differnt section of the application, like dashboard, shop, about etc., you should change root. There is only one root component (the app.component.ts) but there could be many root pages.

3 Components

3.1 Overlay Components

3.1.1 Modal Dialog

A modal is a content pane that displays a tempory UI over the current page. It is often used for login, signup, message composition and option selection. When a modal is presented, it is added to the app’s root nav. A modal can be closed by using its ViewController’s dismiss method or using pop on the root nav controller.

3.1.2 Popover

A popover is also a content-only page that doesn’t have header and footer. You can dismiss it using its ViewController’s dismiss method. The unique feature of a popover is that you can open it in a specified location – usaully the event source location.

To pass data from a popover to its caller, call dismiss(param) in popover and receive data in popover.onDidDismiss(data => {...}).

3.1.3 Loading and Alert

Loading is a simple component that shows a message and dismisses controlled by its caller.

Alert is used to show a message with some buttons.

3.2 Collections

3.1 Buttons

3.2 List

A list can have a list of button or ion-item.


Share