Add menu to ExUssd menu list.

Arguments:

• menu :: menu() :: The parent menu
• menu :: menu() :: The menu to add to the parent menu list.

Example

iex> resolve = fn menu, _payload -> 
...>   menu = 
...>    menu 
...>    |> ExUssd.set(title: "Menu title")
...>    |> ExUssd.add(ExUssd.new(name: "option 1", resolve: &({:ok, ExUssd.set(&1, title: "option 1")})))
...>    |> ExUssd.add(ExUssd.new(name: "option 2", resolve: &({:ok, ExUssd.set(&1, title: "option 2")})))
...>   {:ok, menu}
...> end
iex> menu = ExUssd.new(name: "HOME", resolve: resolve)
iex> ExUssd.to_string!(menu, [])
"Menu title\n1:option 1\n2:option 2"

Add menus to ExUssd menu list.

Arguments:

• menu :: menu() :: The parent menu
• menus :: list(menu()) :: The menu to add to the parent menu list.
• opts :: keyword_args() :: Options to pass to ExUssd.add/3

Example:

    iex> defmodule AppWeb.LocationResolver do
    ...>  use ExUssd
    ...>  def ussd_init(menu, _) do
    ...>   # Get locations from database
    ...>    locations = Enum.map(1..5, &Integer.to_string/1)
    ...>    # convert locations to menus
    ...>    menus = Enum.map(locations, fn location ->
    ...>       ExUssd.new(name: "Location " <> location, data: %{name: location})
    ...>    end)
    ...>    menu = 
    ...>      menu
    ...>      |> ExUssd.set(title: "Select Location")
    ...>      |> ExUssd.add(menus, resolve: &(ExUssd.set(&1, title: "Location " <> &1.data.name)))
    ...>   {:ok, menu}
    ...>  end
    ...> end
    iex> menu = ExUssd.new(name: "HOME", resolve: AppWeb.LocationResolver)
    iex> ExUssd.to_string!(menu, [])
    "Select Location\n1:Location 1\n2:Location 2\n3:Location 3\n4:Location 4\n5:Location 5"

Teminates session.

      ExUssd.end_session(session_id: "sn1")

ExUssd.goto/1 is called when the gateway provider calls the callback URL.

Keyword Arguments:

• payload: The payload from the gateway provider.
• menu: The menu to be rendered.

Example:

    case ExUssd.goto(menu: menu, payload: payload) do
    {:ok, %{menu_string: menu_string, should_close: false}} ->
      "CON " <> menu_string

    {:ok, %{menu_string: menu_string, should_close: true}} ->
      # End Session
      ExUssd.end_session(session_id: session_id)

      "END " <> menu_string
    end

ExUssd.new/1 - Creates a new ExUssd menu.

Keyword Arguments:

• name :: The name of the menu.
• resolve :: The resolve function to be called when the menu is selected.
• orientation :: The orientation of the menu.
• is_zero_based :: indicates whether the menu list is zero based.

Example:

iex> resolve = fn menu, _payload -> 
...>  menu =
...>    menu 
...>    |> ExUssd.set(title: "Menu title")
...>    |> ExUssd.add(ExUssd.new(name: "option 1", resolve: &({:ok, ExUssd.set(&1, title: "option 1")})))
...>    |> ExUssd.add(ExUssd.new(name: "option 2", resolve: &({:ok, ExUssd.set(&1, title: "option 2")})))
...>  {:ok, menu}
...> end
iex> menu = ExUssd.new(name: "HOME", resolve: resolve)
iex> ExUssd.to_string!(menu, [])
"Menu title\n1:option 1\n2:option 2"
iex> # Change menu orientation
iex> menu = ExUssd.new(name: "HOME", resolve: resolve, orientation: :horizontal)
iex> ExUssd.to_string!(menu, [])
"1:2\noption 1\nMORE:98"

zero based

Used when the menu list is zero based.

Example:

iex> resolve = fn menu, _payload -> 
...>  menu =
...>    menu 
...>    |> ExUssd.set(title: "Menu title")
...>    |> ExUssd.add(ExUssd.new(name: "offers", resolve: fn menu, _ -> {:ok, ExUssd.set(menu, title: "offers")} end))
...>    |> ExUssd.add(ExUssd.new(name: "option 1", resolve: &({:ok, ExUssd.set(&1, title: "option 1")})))
...>    |> ExUssd.add(ExUssd.new(name: "option 2", resolve: &({:ok, ExUssd.set(&1, title: "option 2")})))
...>  {:ok, menu}
...> end
iex> menu = ExUssd.new(name: "HOME", is_zero_based: true, resolve: resolve)
iex> ExUssd.to_string!(menu, [])
"Menu title\n0:offers\n1:option 1\n2:option 2"
iex> ExUssd.to_string!(menu, [simulate: true, payload: %{text: "0"}])
"offers"

NOTE: ExUssd.new/1 can be used to create a menu with a callback function.

Use the anonymous function syntax to create menu if you want to perform some action before the menu is rendered.

Remember to use ExUssd.set to set the menu name and the resolve function/module.

Example:

iex> defmodule User do
...>  def get_user(phone_number), do: %{name: "John", phone_number: phone_number, type: :personal}
...> end
iex> defmodule HomeResolver do
...>  def home(%ExUssd{data: %{name: name}} = menu, _) do
...>  menu =
...>    menu 
...>    |> ExUssd.set(title: "Welcome " <> name)
...>    |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
...>    |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
...>    |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
...>  {:ok, menu}
...>  end
...>  def product_a(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product a")}
...>  def product_b(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product b")}
...>  def product_c(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product c")}
...> end
iex> menu = ExUssd.new(fn menu, %{phone: phone} = _payload ->
...>    user = User.get_user(phone)
...>   menu =
...>      menu
...>      |> ExUssd.set(name: "Home")
...>      |> ExUssd.set(data: user)
...>      |> ExUssd.set(resolve: &HomeResolver.home/2)
...>   {:ok, menu}
...> end)
iex> ExUssd.to_string!(menu, [payload: %{text: "*544#", phone: "072000000"}])
"Welcome John\n1:Product A\n2:Product B\n3:Product C"

You can also use the anonymous function syntax to create menu if you want to create dymamic menu name.

Example:

iex> defmodule User do
...>  def get_user(phone_number), do: %{name: "John", phone_number: phone_number, type: :personal}
...> end
iex> defmodule HomeResolver do
...>  def home(menu, %{phone: phone} = _payload) do
...>    user = User.get_user(phone)
...>    menu =
...>      menu 
...>      |> ExUssd.set(title: "Welcome "<> user.name)
...>      |> ExUssd.set(data: user)
...>      |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
...>      |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
...>      |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
...>      |> ExUssd.add(ExUssd.new(&account/2))
...>   {:ok, menu}
...>  end
...>  def product_a(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product a")}
...>  def product_b(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product b")}
...>  def product_c(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product c")}
...>  def account(%{data: %{type: :personal, name: name}} = menu, _payload) do
...>    # Should be stateless, don't put call functions with side effect (Insert to DB, fetch)
...>    # Because it will be called every time the menu is rendered because the menu `:name` is dynamic
...>    # See `ExUssd.new/2` for more details where `:name` is static.
...>   menu =
...>      menu 
...>      |> ExUssd.set(name: "Personal account")
...>      |> ExUssd.set(resolve: &({:ok, ExUssd.set(&1, title: "Personal account")}))
...>   {:ok, menu}
...>  end
...>  def account(%{data: %{type: :business, name: name}} = menu, _payload) do
...>    # Should be stateless, don't put call functions with side effect (Insert to DB, fetch)
...>    # Because it will be called every time the menu is rendered because the menu `:name` is dynamic
...>    # See `ExUssd.new/2` for more details where `:name` is static.
...>   menu =
...>      menu 
...>      |> ExUssd.set(name: "Business account")
...>      |> ExUssd.set(resolve: &({:ok, ExUssd.set(&1, title: "Business account")}))
...>   {:ok, menu}
...>  end
...> end
iex> menu = ExUssd.new(name: "HOME", resolve: &HomeResolver.home/2)
iex> ExUssd.to_string!(menu, [payload: %{text: "*544#", phone: "072000000"}])
"Welcome John\n1:Product A\n2:Product B\n3:Product C\n4:Personal account"

ExUssd.new/2 - Creates a new ExUssd menu.

Arguments: name: The name of the menu. resolve: The resolve function/module.

It similiar to ExUssd.new/1 that takes callback function. The only difference is that it takes a static name argument.

Example:

iex> defmodule User do
...>  def get_user(phone_number), do: %{name: "John", phone_number: phone_number, type: :personal}
...> end
iex> defmodule HomeResolver do
...>  def home(menu, %{phone: phone} = _payload) do
...>    user = User.get_user(phone)
...>    menu =
...>      menu 
...>      |> ExUssd.set(title: "Welcome "<> user.name)
...>      |> ExUssd.set(data: user)
...>      |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
...>      |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
...>      |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
...>      |> ExUssd.add(ExUssd.new("Account", &account/2))
...>   {:ok, menu}
...>  end
...>  def product_a(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product a")}
...>  def product_b(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product b")}
...>  def product_c(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product c")}
...>  def account(%{data: %{type: :personal}} = menu, _payload) do
...>    # Get Personal account details, then set as data
...>     {:ok, ExUssd.set(menu, resolve: &({:ok, ExUssd.set(&1, title: "Personal account")}))}
...>  end
...>  def account(%{data: %{type: :business, name: name}} = menu, _payload) do
...>    # Get Business account details, then set as data
...>    {:ok, ExUssd.set(menu, resolve: &({:ok, ExUssd.set(&1, title: "Business account")}))}
...>  end
...> end
iex> menu = ExUssd.new(name: "HOME", resolve: &HomeResolver.home/2)
iex> ExUssd.to_string!(menu, [payload: %{text: "*544#", phone: "072000000"}])
"Welcome John\n1:Product A\n2:Product B\n3:Product C\n4:Account"

ExUssd.set/2 - Sets the menu field.

Arguments: menu: The menu to set. field: The field to set.

It sets the field of the menu.

Settable Fields

• :data Set data to pass through to next menu. N/B - ExUssd menu are stateful unless using ExUssd.new/2 with :name and :resolve as arguments;

    data = %{name: "John Doe"}
    # stateful
    menu
    |> ExUssd.set(data: data)
    |> ExUssd.add(ExUssd.new(&check_balance/2))
    menu
    |> ExUssd.set(data: data)
    |> ExUssd.add(ExUssd.new("Check Balance", &check_balance/2))
    # stateless
    menu
    |> ExUssd.add(ExUssd.new(data: data, name: "Check Balance", resolve: &check_balance/2))

• :delimiter Set's menu style delimiter. Default- :

• :default_error Default error shown on invalid input

• :name Sets the name of the menu

• :nav Its used to set a new ExUssd Nav menu, see ExUssd.Nav.new/1

• :orientation Sets the menu orientation. Available option;

  • :horizontal - Left to right. Blog/articles style menu
  • vertical - Top to bottom(default)

• :resolve set the resolve function/module

• :should_close Indicate whether to USSD session should end or continue

• :show_navigation Set show navigation menu. Default - true

• :split Set menu batch size. Default - 7

• :title Set menu title

Use ExUssd.to_string/2 to get menu string representation and should close value which indicates if the session. ExUssd.to_string/2 takes a menu and opts.

Example:

    iex> defmodule AppWeb.ProductResolver do
    ...>  use ExUssd
    ...>  def ussd_init(menu, _) do
    ...>   menu =
    ...>      menu 
    ...>      |> ExUssd.set(title: "Product List")
    ...>      |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
    ...>      |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
    ...>      |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
    ...>   {:ok, menu}
    ...> end
    ...>  def product_a(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product a")}
    ...>  def product_b(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product b")}
    ...>  def product_c(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product c")}
    ...> end
    iex> menu = ExUssd.new(name: "HOME", resolve: AppWeb.ProductResolver)
    iex> # Simulate the first time user enters the menu
    iex> ExUssd.to_string(menu, [])
    {:ok, %{menu_string: "Product List\n1:Product A\n2:Product B\n3:Product C", should_close: false}}
    iex> # To simulate a user selecting option "1"
    iex> ExUssd.to_string(menu, [simulate: true, payload: %{text: "1"}])
    {:ok, %{menu_string: "selected product a", should_close: false}}

NOTE: If your ussd_init/2 callback expects data field to have values, Use init_data.

Example:

    iex> defmodule AppWeb.ProductResolver do
    ...>  use ExUssd
    ...>  def ussd_init(%ExUssd{data: %{user_name: user_name}} = menu, _) do
    ...>   menu =
    ...>      menu 
    ...>      |> ExUssd.set(title: "Welcome " <> user_name <> ", Select Product")
    ...>      |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
    ...>      |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
    ...>      |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
    ...>   {:ok, menu}
    ...> end
    ...>  def product_a(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product a")}
    ...>  def product_b(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product b")}
    ...>  def product_c(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product c")}
    ...> end
    iex> menu = ExUssd.new(name: "HOME", resolve: AppWeb.ProductResolver)
    iex> # Simulate the first time user enters the menu
    iex> ExUssd.to_string(menu, init_data: %{user_name: "John"})
    {:ok, %{menu_string: "Welcome John, Select Product\n1:Product A\n2:Product B\n3:Product C", should_close: false}}

ExUssd.to_string/3 is similar to ExUssd.to_string/2 The only difference is that it takes a menu, atom and opts. Its used to test the menu life cycle.

Example:

  iex> defmodule AppWeb.PinResolver do
  ...>  use ExUssd
  ...>  def ussd_init(menu, _) do
  ...>    {:ok, ExUssd.set(menu, title: "Enter your PIN")}
  ...>  end
  ...>  def ussd_callback(menu, payload, _) do
  ...>    if payload.text == "5555" do
  ...>       {:ok, ExUssd.set(menu, resolve: &success_menu/2)}
  ...>    end
  ...>  end
  ...>  def success_menu(menu, _) do
  ...>   menu = 
  ...>      menu
  ...>      |> ExUssd.set(title: "You have Entered the Secret Number, 5555")
  ...>      |> ExUssd.set(should_close: true)
  ...>   {:ok, menu}
  ...>  end
  ...> end
  iex> menu = ExUssd.new(name: "PIN", resolve: AppWeb.PinResolver)
  iex> # Get `ussd_init/2` menu string representation
  iex> ExUssd.to_string(menu, :ussd_init, [])
  {:ok, %{menu_string: "Enter your PIN", should_close: false}}
  iex> # Get `ussd_callback/2` menu string representation
  iex> ExUssd.to_string(menu, :ussd_callback, payload: %{text: "5555"})
  {:ok, %{menu_string: "You have Entered the Secret Number, 5555", should_close: true}}

ExUssd.to_string!/2 gets the menu string text from ExUssd.to_string/2 See ExUssd.to_string/2 for more details.

Example:

    iex> defmodule AppWeb.ProductResolver do
    ...>  def products(menu, _) do
    ...>    menu = 
    ...>      menu 
    ...>      |> ExUssd.set(title: "Product List")
    ...>      |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
    ...>      |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
    ...>      |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
    ...>   {:ok, menu}
    ...> end
    ...>  def product_a(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product a")}
    ...>  def product_b(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product b")}
    ...>  def product_c(menu, _payload), do: {:ok, ExUssd.set(menu, title: "selected product c")}
    ...> end
    iex> menu = ExUssd.new(name: "HOME", resolve: &AppWeb.ProductResolver.products/2)
    iex> # Simulate the first time user enters the menu
    iex> ExUssd.to_string!(menu, [])
    "Product List\n1:Product A\n2:Product B\n3:Product C"

ExUssd.to_string!/3 gets the menu string text from ExUssd.to_string/3 See ExUssd.to_string/3 for more details. Example:

  iex> defmodule AppWeb.PinResolver do
  ...>  use ExUssd
  ...>  def ussd_init(menu, _) do
  ...>    {:ok, ExUssd.set(menu, title: "Enter your PIN")}
  ...>  end
  ...>  def ussd_callback(menu, payload, _) do
  ...>    if payload.text == "5555" do
  ...>       {:ok, ExUssd.set(menu, resolve: &success_menu/2)}
  ...>    end
  ...>  end
  ...>  def success_menu(menu, _) do
  ...>   menu =
  ...>      menu
  ...>      |> ExUssd.set(title: "You have Entered the Secret Number, 5555")
  ...>      |> ExUssd.set(should_close: true)
  ...>   {:ok, menu}
  ...>  end
  ...> end
  iex> menu = ExUssd.new(name: "PIN", resolve: AppWeb.PinResolver)
  iex> # Get `ussd_init/2` menu string representation
  iex> ExUssd.to_string!(menu, :ussd_init, [])
  "Enter your PIN"
  iex> # Get `ussd_callback/2` menu string representation
  iex> ExUssd.to_string!(menu, :ussd_callback, payload: %{text: "5555"})
  "You have Entered the Secret Number, 5555"