Herteby / url-builder-plus / UrlBuilderPlus

This module is identical to Url.Builder found in elm/url, except that it has been extended with the following functions:

Builders

absolute : List String -> List QueryParameter -> String

Create an absolute URL:

absolute [] []
-- "/"

absolute [ "packages", "elm", "core" ] []
-- "/packages/elm/core"

absolute [ "blog", String.fromInt 42 ] []
-- "/blog/42"

absolute [ "products" ] [ string "search" "hat", int "page" 2 ]
-- "/products?search=hat&page=2"

Notice that the URLs start with a slash!

relative : List String -> List QueryParameter -> String

Create a relative URL:

relative [] []
-- ""

relative [ "elm", "core" ] []
-- "elm/core"

relative [ "blog", String.fromInt 42 ] []
-- "blog/42"

relative [ "products" ] [ string "search" "hat", int "page" 2 ]
-- "products?search=hat&page=2"

Notice that the URLs do not start with a slash!

crossOrigin : String -> List String -> List QueryParameter -> String

Create a cross-origin URL.

crossOrigin "https://example.com" [ "products" ] []
-- "https://example.com/products"

crossOrigin "https://example.com" [] []
-- "https://example.com/"

crossOrigin
  "https://example.com:8042"
  [ "over", "there" ]
  [ string "name" "ferret" ]
-- "https://example.com:8042/over/there?name=ferret"

Note: Cross-origin requests are slightly restricted for security. For example, the same-origin policy applies when sending HTTP requests, so the appropriate Access-Control-Allow-Origin header must be enabled on the server to get things working. Read more about the security rules here.

custom : Root -> List String -> List QueryParameter -> Maybe String -> String

Create custom URLs that may have a hash on the end:

custom Absolute
  [ "packages", "elm", "core", "latest", "String" ]
  []
  (Just "length")
-- "/packages/elm/core/latest/String#length"

custom Relative [ "there" ] [ string "name" "ferret" ] Nothing
-- "there?name=ferret"

custom
  (CrossOrigin "https://example.com:8042")
  [ "over", "there" ]
  [ string "name" "ferret" ]
  (Just "nose")
-- "https://example.com:8042/over/there?name=ferret#nose"


type Root
    = Absolute
    | Relative
    | CrossOrigin String

Specify whether a custom URL is absolute, relative, or cross-origin.

Queries


type QueryParameter

Represents query parameter. Builder functions like absolute percent-encode all the query parameters they get, so you do not need to worry about it!

string : String -> String -> QueryParameter

Create a percent-encoded query parameter.

absolute ["products"] [ string "search" "hat" ]
-- "/products?search=hat"

absolute ["products"] [ string "search" "coffee table" ]
-- "/products?search=coffee%20table"

nonEmptyString : String -> String -> QueryParameter

Same as string, except if the string is empty, the parameter is omitted

absolute ["products"] [ string "search" "hat" ]
-- "/products?search=hat"

absolute ["products"] [ string "search" "" ]
-- "/products"

int : String -> Basics.Int -> QueryParameter

Create a percent-encoded query parameter from an Int.

absolute ["products"] [ string "search" "hat", int "page" 2 ]
-- "/products?search=hat&page=2"

float : String -> Basics.Float -> QueryParameter

Create a percent-encoded query parameter from a float.

absolute ["products"] [ string "search" "hat", float "maxprice" 9.99 ]
-- "/products?search=hat&maxprice=9.99"

bool : String -> Basics.Bool -> QueryParameter

True becomes "true" and False becomes "false"

absolute ["products"] [ string "search" "hat", bool "discounted" True ]
-- "/products?search=hat&discounted=true"

maybe : (String -> a -> QueryParameter) -> String -> Maybe a -> QueryParameter

Takes a -> QueryParameter function, for example float, and a value. If the value is Nothing, the parameter is omitted

absolute ["products"] [ string "search" "hat", maybe float "maxprice" (Just 9.99) ]
-- "/products?search=hat&maxprice=9.99"

absolute ["products"] [ string "search" "hat", maybe float "maxprice" Nothing ]
-- "/products?search=hat"

list : (String -> a -> QueryParameter) -> String -> List a -> QueryParameter

Make a comma-separated list. If the list is empty, the parameter is omitted

absolute ["products"] [ string "search" "hat", list int "sizes" [1,2,3] ]
-- "/products?search=hat&sizes=1,2,3"
-- actually it becomes "/products?search=hat&sizes=1%2C2%2C3" since it's url-encoded, but don't worry about it

absolute ["products"] [ string "search" "hat", list int "sizes" [] ]
-- "/products?search=hat"

bracketedList : (String -> a -> QueryParameter) -> String -> List a -> QueryParameter

Make a comma-separated list surrounded by brackets (in case your API uses this alternate syntax). If the list is empty, the parameter is omitted

absolute ["products"] [ string "search" "hat", list int "sizes" [1,2,3] ]
-- "/products?search=hat&sizes=[1,2,3]"
-- actually it becomes "/products?search=hat&sizes=[1%2C2%2C3]" since it's url-encoded, but don't worry about it

absolute ["products"] [ string "search" "hat", list int "sizes" [] ]
-- "/products?search=hat"

toQuery : List QueryParameter -> String

Convert a list of query parameters to a percent-encoded query. This function is used by absolute, relative, etc.

toQuery [ string "search" "hat" ]
-- "?search=hat"

toQuery [ string "search" "coffee table" ]
-- "?search=coffee%20table"

toQuery [ string "search" "hat", int "page" 2 ]
-- "?search=hat&page=2"

toQuery []
-- ""