This module is identical to Url.Builder found in elm/url, except that it has been extended with the following functions:
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"
Specify whether a custom
URL is absolute, relative, or
cross-origin.
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 []
-- ""