This module provides core functionality for TEPA.

Overall application structure

TEPA application is written in the Elm language, and is converted to JavaScript, so you import it to use in your JavaScript (or TypeScript) file. If you are a Parcel user, you can load the Elm file that contains the main function built with application as follows:

<!-- index.html -->


<html>
  <body>
    <script src="./index.js"></script>
  </body>
</html>


// index.js


// Specify your file that contains `main` function here.
import { Elm } from "./Main.elm"


Elm.Main.init({
  // Create a `div` node in body and pass it as the parent node in which to render your TEPA application.
  node: document.body.appendChild(document.createElement("div")),
  // Pass some JSON value to TEPA upon initialization.
  flags: {
    "loaded-at": Date.now()
  }
})


-- Main.elm
-- (Details will be explained later.)


import Json.Decode (Value)
import Tepa exposing (AppUrl, NavKey, Program, Promise)


main : Program Memory
main =
    Tepa.application
        { init = init
        , procedure = procedure
        , view = view
        , onUrlRequest = onUrlRequest
        , onUrlChange = onUrlChange
        }


{- Data type for representing your application state.
-}
type alias Memory =
    { ...
    , ...
    }


{-| Your implementation for `init`.
-}
init : Memory
init =
    Debug.todo ""


{-| Your implementation for `procedure`.
-}
procedure : Value -> AppUrl -> NavKey -> Promise Memory ()
procedure flags url key =
    Debug.todo ""


{-| Your implementation for `view`.
-}
view : Layer Memory -> Document
view layer =
    Debug.todo ""


{-| Your implementation for `onUrlRequest`.
-}
onUrlRequest : Value -> UrlRequest -> NavKey -> Promise memory ()
onUrlRequest flags url key =
    Debug.todo ""


{-| Your implementation for `onUrlChange`.
-}
onUrlChange : Value -> AppUrl -> NavKey -> Promise memory ()
onUrlChange flags url key =
    Debug.todo ""

If you are not familiar with Elm language, we recommend you to check Core Language, Types, and Error Handling section of the Elm guide. API documentation for the core libraries of the language can be found on the package site. Among the core libraries, Platform, Platform.Cmd, Platform.Sub, Process, and Task modules are not used by TEPA, so you can just ignore them.

For TEA users: If you have an existing TEA application, you can use the low level API to partially integrate TEPA into your TEA application.

Key Concepts of TEPA

Memory

TEPA has a single Memory that holds all of the application state. You specify the initial state of the Memory as the init property.

{-| Your own type that represents your application state.


It is common to declare [type alias](https://guide.elm-lang.org/types/type_aliases) for [record](https://guide.elm-lang.org/core_language#records).


-}
type alias Memory =
    { pageState : PageState
    }


{-| Initial state of `Memory`. Pass it as `init` property to the `application` function.
-}
init : Memory
init =
    { pageState = InitialPageState
    }

Flags

You can pass a JSON value, called Flags, to the TEPA application upon initialization. Common uses are passing in API keys, environment variables, and user data.

The sample index.js in the application document passes { "loaded-at": Data.now() } as flags.

Elm.Main.init({
  // Create a `div` node in body and pass it as the parent node in which to render your TEPA application.
  node: document.body.appendChild(document.createElement("div")),
  // Pass some JSON value to TEPA upon initialization.
  flags: {
    "loaded-at": Date.now()
  }

On the Elm side, the JSON object is converted to Value type which you can decode with the Json.Decode module.

Procedure

In TEPA, you describe application behaviour as Procedure, the time sequence of proccessing.

Promise

To build your procedure, you combine some Promises that represent the eventual completion of an operation and its resulting value. Similar to Promise in JavaScript.

The main difference from Promise in JavaScript is that Promise in TEPA does not be rejected. When you represent rejected state, just return Result value as its result. The rejection of JavaScript Promise is a sort of Exception, which drops context.

Primitive Promises

Bind results

currentState is resolved with the current state, but how to retrieve the value? You can use bind to pass the result into another sequence of procedures.

Recursive procedures

It is common technique to call procedures recursively.

formProcedure : Promise Memory ()
formProcedure =
    Tepa.bind submit <|
        \result ->
            case result of
                Err error ->
                    [ Tepa.modify <|
                        \m ->
                            { m | error = error }
                    , formProcedure
                    ]


                Ok body ->
                    [ Debug.todo ""
                    ]

However, this code may cause run out of stack memory. To optimize memory usage, you can use lazy.

formProcedure : Promise Memory ()
formProcedure =
    Tepa.bind submit <|
        \result ->
            case result of
                Err error ->
                    [ Tepa.modify <|
                        \m ->
                            { m | error = error }
                    , Tepa.lazy <|
                        \_ ->
                            formProcedure
                    ]


                Ok body ->
                    [ Debug.todo ""
                    ]

Common helpers

DOM events

To request DOM related operations, you can use Tepa.Dom module.

Page navigation

To navigate to another page, you can use Tepa.Navigation module.

Random values

To request random values, you can use Tepa.Random module.

Handle time

To request time related operations, you can use Tepa.Time module.

HTTP requests

To send HTTP request to the backend server, you can use Tepa.Http module.

Port requests

Streams

Some Promises are resolved with Stream, which is an advanced technique for controlling Promises precisely. See Tepa.Stream for details.

Lower level functions

Application Procedures

There are three type of procedures you specify as an application property.

Main Procedure

The main procedure, set as the value of the procedure property, is executed on every page load. It takes three arguments:

• Flags: JSON value passed by JavaScript on initialization.

• Application URL: The initial URL requested by a user.

  TEPA uses the AppUrl type to represent internal URLs.

• Navigation Key: Required by functions exposed by Tepa.Navigation.

Procedure to handle page transition requests.

You specify the procedure for handling page transition requests as onUrlRequest property of application. It takes three arguments:

• Flags: JSON value passed by JavaScript on initialization.
• Requested URL: UrlRequest value that indecates requested URL.
• Navigation Key: Required by functions exposed by Tepa.Navigation.

In most cases, you will declare the function as follows:

onUrlRequest : Value -> Tepa.UrlRequest -> NavKey -> Promise Memory ()
onUrlRequest _ urlRequest key =
    case urlRequest of
        Tepa.InternalPath url ->
            Nav.pushPath key url


        Tepa.ExternalPage href ->
            Nav.load href

Procedure executed after URL changed

Immediately after the URL is changed, onUrlChange property of application function is evaluated. A common use case is to change the page state based on the new URL.

It takes three arguments:

• Flags: JSON value passed by JavaScript on initialization.
• New URL: Loaded new URL.
• Navigation Key: Required by functions exposed by Tepa.Navigation.

In sample application, the onUrlChange function retrieves the session information, such as the logged-in user data, and then calls the main procedure.

Layer

The Layer is the concept of an isolated space. You can create a new layer with the newLayer function, execute a procedure on a layer with the onLayer function, delete or overwrite the existing layer with modify.

A main use of the layer is to manage page transition. See that you have the following Page type to represent your page state.

import Page.Home as PageHome
import Page.Users as PageUsers
import Tepa exposing (Layer)


type alias Memory =
    { page : Page
    }


type Page
    = PageLoading
    | PageHome PageHome.Memory
    | PageUsers PageUsers.Memory

This approach may seem to work at first, but it may exhibit unexpected behavior, such as

1. A user opens the home page.
   • The main procedure is executed, replacing the page in memory with the PageHome param (where param is the initial value of PageHome.Memory).
   • The main procedure continues to execute the procedure for the home page.
   • The home procedure is executed to replace the image to be displayed every 20 seconds (process A).
2. The user is redirected to the user list page.
   • The onChangeUrl procedure is executed and the page in memory is replaced with PageUsers param (param is the initial value of PageUsers.Memory).
   • At this point, process A is asleep.
3. The user immediately changes to the home page.
   • The onChangeUrl procedure is executed, and the page in memory is again replaced with the PageHome param (param is the initial value of PageHome.Memory).
   • The onChangeUrl procedure continues to execute a new procedure for the home page.
   • A new process (Process B) runs to update the display image every 20 seconds, overlapping with Process A.
   • Now it is time for Process A to refresh the image.
     • Because the memory state is still PageHome, Process A cannot detect that the page has changed in the middle of the process.
   • Process B also refreshes images periodically, so the slideshow now refreshes images at odd times!

The reason for this unexpected behavior is that the process cannot determine that the page state has changed in the middle of a page based only on the memory state. To solve this problem, you can use Layer.

type Page
    = PageLoading
    | PageHome (Layer PageHome.Memory)
    | PageUsers (Layer PageUsers.Memory)

The new Page' definition above usesLayer' to wrap each page memory state. A procedure executed on a layer will be aborted when the layer has expired by being overwritten by another layer. This allows you to avoid running duplicate procedures.

View

The View determines how your application is rendered in the web browser, based only on the current layer state. You use Tepa.Html and Tepa.Mixin to tell the web browser how to render the page.

Define Views

To define View function, you use layerView.

import Tepa exposing (Document, Layer)


view : Layer Memory -> Document
view =
    Tepa.layerView <|
        \{ state } ->
            { title = "Sample App"
            , body =
                [ case state.page of
                    PageNotFound _ ->
                        pageNotFoundView


                    PageLogin pageLogin ->
                        PageLogin.view pageLogin


                    PageHome pageHome ->
                        PageHome.view pageHome
                ]
            }

The state field of the ViewContext indicates current memory state of the Layer.

Keys

Key is used to specify a specific View element.

import Tepa exposing (Layer, Msg)
import Tepa.Html as Html exposing (Html)
import Tepa.Mixin as Mixin


formView : Layer Memory -> Html
formView =
    Tepa.layerView <|
        \{ setKey, values } ->
            Html.node "form"
                [ Mixin.attribute "novalidate" "true"
                ]
                [ Html.node "label"
                    []
                    [ Html.text "Name: "
                    , Html.node "input"
                        [ setKey "form_name"
                        , Mixin.attribute "type" "text"
                        , Mixin.attribute "placeholder" "Sakura-chan"
                        ]
                        []
                    ]
                , Html.button
                    [ setKey "form_submit"
                    ]
                    [ Html.text "Submit"
                    ]
                , errors values
                ]


errors : Dict String String -> Html
errors formValues =
    case Dict.get "form_name" formValues of
        Just "" ->
            Html.text "Name is required."


        _ ->
            Html.text ""

This example uses the setKey of the ViewContext to set the key named "form_name" to the name input, and "form_submit" to the submit button. In this way, you can retrieve the user input value with the values field of the ViewContext.

Note that keys on the same Layer must be unique.

For TEA users: You can use setKey alternative for Html.Attribute that elm/html expose. It means you can use layout libraries such as neat-layout or elm-ui.

Handle form value on Procedure

The key is also used to communicate View and Procedure. If you want to get user inputs on the Procedure side, you can use getValue or getValues.

The setValue is used to overwrite or initiate the input value from the Procedure side.

Note that the Procedure can only get/set values in Views on the same Layer that the Procedure is executed.

Handle form check state on Procedure

You can get/set checked property values of radio/checkbox elements.

Note that the Procedure can only get/set check state in Views on the same Layer that the Procedure is executed.

Helpers to handle form state

Handle View events on Procedure

To capture View events on Procedure, you can use awaitViewEvent or awaitCustomViewEvent.

For more precise control, you can use Stream versions.

Note that the Procedure can only capture events in Views on the same Layer that the Procedure is executed.

Freshness of input values

The user input values obtained by the value field of the ViewContext and getValue / getValues in the Procedure are updated whenever the change event of the target element occurs. So if you want to implement something like an incremental search, getting values in this ways will not give you the latest input values. Use search type of input element or capture the input event with awaitCustomViewEvent to handle this situation.

Scenario

To create user scenarios and generate tests for them, see the Tepa.Scenario module.

Headless

Connect to TEA app

For TEA users: If you have an existing application built with TEA, you can partially replace it with TEPA.

Unsafe functions