---
title: "Getting Started"
author: "David Granjon"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

`{shinyMobile}` is built on top of the latest [framework7](https://framework7.io) template (V5.7.14). It may be 
used for different purposes:

  * develop mobile-ready shinyapps
  * develop progressive web shinyapps (PWA, similar to native apps)
  * develop desktop shinyapps
  
## Custom skins

`{shinyMobile}` has 3 skins:

  * __aurora__ for desktop apps
  * __ios__ and __md__ for mobile apps

It automatically detects if the app is running with android or iOS and accordingly adapt 
the layout. It is of course possible to apply the iOS skin on android and inversely, even though not recommended.

`{shinyMobile}` also provides 2 themes, namely light and dark. 
While framework7 allows to apply dark or light theme not only at the global level but at the "widget level", 
`{shinyMobile}` does not support that feature, to improve the overall consistency. 
Only panels can have a color independent of the global theme.


## Layouts

`{shinyMobile}` brings 3 out of the box layouts:

  * `f7SingleLayout`: develop simple apps (best choice for iOS/android Apps)
  * `f7TabLayout`: develop complex multi-tabbed Apps (best choice for iOS/android Apps)
  * `f7SplitLayout`: for tablets and desktop with a sidebar, navbar and a main panel
  * Coming soon: a multi-pages layout with animations between pages!


## New Inputs

`{shinyMobile}` has its own custom input widgets with unique design for each skin (iOS/android/aurora):

  * `f7Slider()`
  * `f7Text()`
  * `f7checkBox()`
  * `f7checkBoxGroup()`
  * `f7Radio()`
  * `f7Toggle()`
  * `f7Stepper()`: equivalent to `numericInput()` from {shiny}
  * `f7Picker()`
  * `f7DatePicker()`
  * `f7ColorPicker()`
  * `f7Password()`
  * `f7SmartSelect()`
  * `f7Select()`
  * `f7AutoComplete()`
  * `f7Button()`: similar to `actionButton()` from {shiny}
  * `f7Fab()`: enhanced `f7Button()` with ability to be gathered in a `f7Fabs()` container
  * and more
  
It also has custom update functions to act on the server side:

  * `updateF7AutoComplete()`
  * `updateF7Picker()`
  * `updateF7Stepper()`
  * `updateF7Toggle()`
  * `updateF7Slider()`
  * `updateF7Fab()`
  * `updateF7Text()`
  * `updateF7Checkbox()`
  * and many more
  
Finally, it also provides tools to dynamically update widgets on the server side 
like cards, accordions, tabs, panels and more:

  * `updateF7Accordion()`
  * `updateF7Card()`
  * `updateF7Gauge()`
  * `updateF7Progress()`
  * `updateF7Sheet()`
  * many more
  
## Create your first App

#### Select a template

This choice is crucial when you are developing an App. It depends on the complexity
of your visualizations and content. If your plan is to develop a simple graph or table,
you should go for the `f7SingleLayout()` option. For more complex design, the best is
`f7TabLayout()`. `f7SplitLayout()` is specific for tablets and desktop apps.

#### Simple Layout

```r
f7SingleLayout(
  ..., 
  navbar, 
  toolbar = NULL, 
  panels = NULL,
  appbar = NULL
)
```

While only the navbar is mandatory, other components such as the toolbar are 
optionnal for the `f7SingleLayout()`. 


#### Tabs Layout

```r
f7TabLayout(
  ..., 
  navbar, 
  panels = NULL, 
  appbar = NULL
)
```
  
The ... argument requires `f7Tabs(..., id = NULL, swipeable = FALSE, animated = TRUE)`.
The id argument is mandatory if you want to exploit the `updateF7Tabs()` function.
`f7Tabs()` expect to have `f7Tab(..., tabName, icon = NULL, active = FALSE)` passed inside.


#### Split Layout (similar to sidebarLayout in {shiny})

```r
f7SplitLayout(.
  ..., 
  navbar, 
  sidebar, 
  toolbar = NULL, 
  panels = NULL,
  appbar = NULL
)
```

The main content goes in the ... parameter. Navigation items are gathered in the
sidebar slot. The sidebar expect a `f7Panel`. Importantly, the side parameter must
be set to "left" and the style to "reveal". The navigation menu is organized as follows:

```r
f7PanelMenu(
  id = "menu",
  f7PanelItem(
    tabName = "tab1", 
    title = "Tab 1", 
    icon = f7Icon("email"), 
    active = TRUE
  ),
  f7PanelItem(
    tabName = "tab2", 
    title = "Tab 2", 
    icon = f7Icon("home")
  )
)
```

The __id__ argument is important if you want to get the currently selected item or
update the select tab. Each `f7PanelItem` has a mandatory __tabName__. The associated input
will be `input$menu` in that example, with "tab1" for value since the first tab was
set to an active state. To adequately link the body and the sidebar, you must wrap the
body content in `f7Items()` containing as many `f7Item()` as sidebar items. The __tabName__ must
correspond!


#### Core Layout Components

#### Page
It is the main skeleton of the template.

```r
f7Page(
  ..., 
  options = list(
    theme = c("ios", "md", "auto", "aurora"),
    dark = TRUE,
    filled = FALSE,
    color = "#007aff",
    touch = list(
      tapHold = TRUE,
      tapHoldDelay = 750,
      iosTouchRipple = FALSE
    ),
    iosTranslucentBars = FALSE,
    navbar = list(
      iosCenterTitle = TRUE,
      hideNavOnPageScroll = TRUE
    ),
    toolbar = list(
      hideNavOnPageScroll = FALSE
    ),
    pullToRefresh = FALSE
  ),
  title = NULL, 
  preloader = FALSE, 
  loading_duration = 3,
  allowPWA = FALSE
)
```

__options__ sets up the app look and feel. __preloader__ is useful
in case you want to display a loading screen. `f7Page()` accepts any `{shinyMobile}` layout.

##### Navbar
The __navbar__ is a mandatory element of any `{shinyMobile}` layout.
It contains a title, a subtitle, triggers for both right and left panels (`f7Panel()`) as well
as a subnavbar (`f7SubNavbar()`).

```r
f7Navbar(
  ..., 
  subNavbar = NULL, 
  title = NULL, 
  subtitle = NULL,
  hairline = TRUE, 
  shadow = TRUE, 
  bigger = FALSE,
  leftPanel = FALSE, 
  rightPanel = FALSE
)
```

For complex apps, it might be interesting to add a `f7SubNavbar(...)`. It may contain
any element like `f7Button()` or text. `f7Navbar()` has also styling parameters such as
shadow and hairline.

##### The Toolbar

This is an option if you decide not to embed a `f7SubNavbar()`. The toolbar is the
rigth place to add `f7Button()`, `f7Link()`, `f7Badge()`... Its position is controlled
with the position parameter (either top or bottom).

```r
f7Toolbar(
  ..., 
  position = c("top", "bottom"), 
  hairline = TRUE,
  shadow = TRUE, 
  icons = FALSE, 
  scrollable = FALSE
)
```

Under the hood, `f7Tabs()` is a custom `f7Toolbar()`!

##### Panels

Panels are also called sidebars. `f7Panel()` is the corresponding function.

```r
f7Panel(
  ..., 
  id = NULL,
  title = NULL, 
  side = c("left", "right"),
  theme = c("dark", "light"), 
  effect = c("reveal", "cover"),
  resizable = FALSE
)
```

Although the App has a __theme__ option, `f7Panel()` has an independent __theme__ option.
For instance, it is definitely possible to create a dark `f7Panel()` while the page
theme is light, and conversely. Its behaviour is controlled via the effect argument:

  - __reveal__ will make the body content move and resize
  - __cover__ will cover the body content
  
The __resizable__ argument allows to dynamically resize the panel.

Note that for the moment, there is no option to control the width of each panel.
  
As stated previously for the `f7SplitLayout()`, the `f7Panel()` may also be considered
as a sidebar. In that case, we may include `f7PanelMenu()`.
Finally do not forget to set up the `f7Navbar()` so that panels are allowed!

##### The appbar

`f7Appbar()` is displayed on top of the `f7Navbar()`. It is a best choice to embed
`f7Searchbar()`. `f7Appbar()` may also trigger `f7Panel()`. 

```r
f7Appbar(
  ..., 
  leftPanel = FALSE, 
  rightPanel = FALSE,
  maximizable = FALSE
)
```

#### Options

This is probably the most important element of the template: 

```r
options = list(
    theme = c("ios", "md", "auto", "aurora"),
    dark = TRUE,
    filled = FALSE,
    color = "#007aff",
    touch = list(
      tapHold = TRUE,
      tapHoldDelay = 750,
      iosTouchRipple = FALSE
    ),
    iosTranslucentBars = FALSE,
    navbar = list(
      iosCenterTitle = TRUE,
      hideNavOnPageScroll = TRUE
    ),
    toolbar = list(
      hideNavOnPageScroll = FALSE
    ),
    pullToRefresh = FALSE
  )
```

As stated above, you may choose between 3 skins and 2 color themes. There is a third option
called __filled__ that allows to fill the navbar and toolbar if enabled. The __color__ options simply
changes the color of elements such as buttons, panel triggers, tabs triggers, ... 
`{shinyMobile}` brings a lot of different colors. __hideOnPageScroll__ allow to hide/show the navbar and toolbar
which is useful to focus on the content. The __tapHold__ parameter ensure that the "long-press" feature is activated. 
Framework7 has many more options which can be passed through this __options__ parameter