.. index:: page

*****
Page
*****

Page element
============

A *page* element represents a page on the UI, it is a first level UI element in a Scolvo script.

Syntax of the *page* element
----------------------------
..
  
  page <page-id> {<page-descriptor>}
  

where:

- The <page-id> is the name of the page.
- The <page-descriptor> defines the elements and the look of the *page* element.

.. index:: page events

Events of the *page*
--------------------
The page UI element supports following events:

- **on loaded**: this event is fired when the page is loaded.
- **on page action**: this event is fired when button of one of the page actions is selected.


.. code-block:: scolvoscript
  :caption: Example on loaded event and action of example page action of the page ExamplePage
  :linenos:

  
  function onExamplePageLoaded(originId) {
    // business logic to be executed according to the application logic
  }

  function onExampleAction(originId) {
    // business logic to be executed when action button is clicked
  }
  
..

.. index:: page dictionary keys

Dictionary keys of the *page*
------------------------------
The title of the *page* element is defined in the dictionary, the corresponding key has the form of 'page_<page-name>_headerText'. Other key form is defined for page actions, where the form can be page_<page-name>_<page-action-name>_label and 
page_<page-name>_<page-action-name>_icon. For possible icon values check the Icons API documentation page.


.. code-block:: properties
  :caption: Dictionary key definition for page Example page in the mobile_dictionary_en.properties file
  :linenos:

  
  page_ExamplePage_headerText=Example page title
  page_ExamplePage_DoAction_label=Do the logic
  page_ExamplePage_DoAction_icon=\ue939
  
..

.. index:: page related built-in functions

Built-in functions related to *page* element
--------------------------------------------
There are built-in functions related to *page* element, what can be used to display or dismisss a *page* object:

- **display(pageName, pageData, originId)**: function to show a page given by name.
- **finishPage(pageName, originId)**: function to dismiss a page.


Syntax of the *page* descriptor
--------------------------------
The page descriptor can contain one or more attribute descriptors.

..
  
  (<attribute-descriptor>[,|;])+
  <page-actions>
  <ui-elements>

..

where:

- Multiple <attirbute-descriptor> can be defined, the definitions are optionally separated by ',' or ';'.
- The <page-actions> block defines page level actions.
- The <ui-elements> block can contain UI elements construction a page content, this is not described here in detail.


Syntax of the *page* attribute descriptor
-----------------------------------------

..
  
  <attirubte-name>: <attribute-value>

..

where:

- List of valid attribute names and values are defined by client device types below.

.. index:: page attributes

Valid *page* attribute names and values
----------------------------------------
The following table describes the valid attributes and its values for different client device types.

.. list-table:: Valid attribute keys and values
    :widths: 10 5 10 50
    :header-rows: 1

    * - Attribute name
      - Description
      - Valid values
      - Example

    * - template
      - Defines the template to be used
      - vertical or horizontal
      - template: vertical,

    * - layout
      - Defines the layout to be used
      - fullscreen or general (default value)
      - layout: fullscreen;

    * - scolvoMenuVisible
      - Defines if this page is visible in the Scolvo menu
      - Boolean value: true or false, default value is false
      - scolvoMenuVisible: true;

    * - settingsVisible
      - Defines if the Settings menu is available from this page
      - Boolean value: true or false, default value is false
      - settingsVisible: true;


.. index:: page actions

Syntax of the *page* actions
----------------------------

..
  
  actions: <action-list>[,|;]

..

where:

- The actions are defined by 'actions' keyword and the list of actions. This definition can be optionally separated from other page description elements by ',' or ';'.

Syntax of the *page* action-list
--------------------------------

..
  
  [<action-name>+]
  
..

where:

- The action list is defined as collection of strings (in []), where the action names are double-quoted strings. E.g.: ["FirstPageAction", "SecondPageAction"].


Example *page* definition
-------------------------
The following code examples are defining a page and its value, where an example UI element is added:

.. code-block:: scolvoscript
  :caption: Example definition of a page with menu and display built-in function
  :linenos:

  
  menu defaultItem Example {
    item Example
  }
  
  function onExample(originId) {
    display(ExamplePage, {}, originId);
  }
  
  page ExamplePage {
    layout: vertical;
    template: fullscreen;
    scolvoMenuVisible: true;
    settingsVisible: true;
    
    actions: ["Do"];
    label DescriptionLabel {
      template: display1Primary;
    }
  }
  
  function onExamplePageLoaded(originId) {
  }
  
..

.. code-block:: properties
  :caption: Dictionary key definition for the example label
  :linenos:

  
  menu_Example_label=Example

  page_ExamplePage_headerText=Example page
  page_ExamplePage_Do_label=Do the action
  page_ExamplePage_Do_icon=\ue939
  page_ExamplePage_DescriptionLabel_defaultText=Here and now!
  
..