itravel-de / elm-thumbor / Thumbor

Core Functionality

url : Config -> List Attribute -> String -> String

Creates a new image URL based on the given Config, Attributes and original image URL.

Attributes can occur in any order. If an attribute is specified multiple times, the last occurrence wins - very much like how elm/html attributes work.

You might want to use currying to ease usage of this package:

thumbor : List Thumbor.Attribute -> String -> String
thumbor =
    Thumbor.url
        { host = "https://example.com:1138"
        , key = Just "thefutureishere"
        }

-- Prepare a common configuration for teaser images
prepareTeaserImage : String -> String
prepareTeaserImage =
    thumbor [ Thumbor.scale 200 300 ]

-- Actually use this package to create a modified image
view : Model -> Html msg
view model =
    img [ src (prepareTeaserImage "https://example.com/image.jpg") ] []

Configuration


type alias Config =
{ baseUrl : String
, key : Maybe String 
}

Thumbor server configuration. The baseUrl configures the base URL your Thumbor instance is hosted on. It must contain at least an URL schema and host and can contain a custom port or path.

key contains your key for URL signing. If Nothing is provided, URL signing will be disabled.

Important Security Notice: Since Elm is mostly used in front-end code, your key will be exposed in clear-text to all clients, nullifying the effect of this security measure.

Make sure you have an alternate concept to stop URL tampering!

Examples:

{ baseUrl = "https://example.com"
, key = Just "thefutureishere"
}

{ baseUrl = "https://example.com/thumbor"
, key = Just "thefutureishere"
}

{ baseUrl = "https://example.com:1138/thumbor"
, key = Just "thefutureishere"
}

Attributes


type Attribute

Represents a Thumbor attribute, controlling how images are processed. See below for a list of available attribute constructors.

Sizing

size : Size -> Size -> Attribute

Specifies the size of the image that will be returned by the service.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#image-size

sizeFixed : Basics.Int -> Basics.Int -> Attribute

Same as size, but always uses Fixed sizing for convenience.


type Size
    = Fixed Basics.Int
    | Proportional
    | Original

Cropping

manualCrop : { left : Basics.Int, top : Basics.Int, right : Basics.Int, bottom : Basics.Int } -> Attribute

Useful for applications that provide custom real-time cropping capabilities. This crop is performed before the rest of the operations, so it can be used as a prepare step before resizing and smart-cropping.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#manual-crop

horizontalAlign : HorizontalAlign -> Attribute

Controls where the cropping will occur if some width needs to be trimmed. The default is Center.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#horizontal-align


type HorizontalAlign
    = Left
    | Center
    | Right

verticalAlign : VerticalAlign -> Attribute

Controls where the cropping will occur if some height needs to be trimmed. The default is Middle.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#vertical-align


type VerticalAlign
    = Top
    | Middle
    | Bottom

Trimming

trim : TrimSource -> Basics.Int -> Attribute

Removes surrounding space in images based on its color. You can pass in the source where the color should be sampled with a TrimSource. In addition, you can specify a color tolerance with the second parameter. The tolerance value will be clamped between 0 and 442.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#trim

trimSimple : Attribute

Same as trim, but always uses TopLeft source and 0 tolerance.


type TrimSource
    = TopLeft
    | BottomRight

Fitting

fitIn : FitInMode -> Attribute

Specifies that the image should not be auto-cropped and auto-resized to be exactly the specified size, and should be fit in an imaginary box (given by the sizing argument) instead.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#fit-in


type FitInMode
    = NormalFitIn
    | AdaptiveFitIn
    | FullFitIn

Miscellaneous

filters : List Filter -> Attribute

Sets a list of filters as a chain to be used. See Thumbor.Filter for available filters and their usage.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#filters

smart : Attribute

Thumbor uses some advanced techniques for obtaining important points of the image, called focal points.

If you use this attribute, smart cropping will be performed and will override both horizontal and vertical alignments if it finds any focal points.

Thumbor docs: https://thumbor.readthedocs.io/en/latest/usage.html#smart-cropping