mewhit / prismicio / Prismic

An Elm SDK for Prismic.io.

Initialisation

init : String -> Model

Initialise the Prismic model with the URL for your Prismic repository. Save this in your application's Model somewhere.

type alias Model =
    { prismic : Prismic.Model }

init =
    { prismic =
        Prismic.init "https://lesbonneschoses.prismic.io/api"
    }

initWith : String -> Options -> Model

Initialise with custom options.


type alias Options =
{ defaultRef : String }

defaultOptions : Options

Initiating a request


type Request

Represents a Prismic request.

api : Model -> Task PrismicError ( Model, Api )

Go and fetch the Prismic Api metadata, if it has not already been fetched.

The Api is cached in the returned Model, so we don't have to fetch it next time.

You start every Prismic request with this function.

form : String -> Task PrismicError ( Model, Api ) -> Task PrismicError Request

Choose a form on which to base the rest of the Prismic request.

bookmark : String -> Task PrismicError ( Model, Api ) -> Task PrismicError Request

Convenience function for fetching a bookmarked document.

Customising the request

ref : String -> Task PrismicError Request -> Task PrismicError Request

Override a Form's default ref

lang : String -> Task PrismicError Request -> Task PrismicError Request

Override a Form's default lang.

query : List Predicate -> Task PrismicError Request -> Task PrismicError Request

Override a Form's default query.

See the section on Predicates below for how to construct a Predicate.

Sending the request

submit : Decoder Document docType -> Task PrismicError Request -> Task PrismicError ( Model, Response docType )

Submit the request.

Pass this function a Decoder to decode each document in the response into your own Elm document type.

Handle the response


type alias Response docType =
{ license : String
, nextPage : Maybe String
, page : Basics.Int
, prevPage : Maybe String
, results : List docType
, resultsPerPage : Basics.Int
, resultsSize : Basics.Int
, totalPages : Basics.Int
, totalResultsSize : Basics.Int
, version : String 
}

Represents a Prismic response.

This type is parameterized by docType, which is determined by the Decoder you pass to submit.

cache : Model -> Model -> Model

The submit Task returns an updated Prismic Model with the request and response cached.

In your app's update function, you should merge this with the existing cache using cache.

update msg model =
    case msg of
        MyPrismicMsg (Ok ( prismic, response )) ->
            { model
                | prismic =
                    cache model.prismic prismic
            }

Predicates


type Predicate

The type representing Prismic query predicates.

at : String -> String -> Predicate

at fragment value matches documents having value at fragment.

atL : String -> List String -> Predicate

atL fragment values matches documents having a list of values at fragment.

any : String -> List String -> Predicate

any fragment values matches documents having any of values at fragment.

fulltext : String -> String -> Predicate

fulltext fragment value matches documents with a full text search at fragment.

Types

Models


type Model

The Prismic Model keeps track of configuration and holds the response cache.

Errors


type PrismicError
    = FormDoesNotExist String
    | RefDoesNotExist String
    | BookmarkDoesNotExist String
    | FetchApiError Http.Error
    | SubmitRequestError Http.Error
    | DecodeDocumentError String

The possible errors elm-prismicio raises.

Api


type alias Api =
{ refs : List RefProperties
, bookmarks : Dict String String
, types : Dict String String
, tags : List String
, version : String
, forms : Dict String Form
, oauthInitiate : String
, oauthToken : String
, license : String
, experiments : Experiments 
}

The Api for your Prismic repository.

Your app can look things up in this if you need to (for example, to resolve links using the bookmarks Dict).


type alias RefProperties =
{ id : String
, ref : Ref
, label : String
, isMasterRef : Basics.Bool 
}

Properties representing a Prismic ref.

Most of the time you will be working with the master ref, which is added to all requests by default.


type Ref

A type to disambiguate Refs from other Strings.


type alias Form =
{ method : String
, enctype : String
, action : String
, fields : Dict String FormField
, rel : Maybe String
, name : Maybe String 
}

Properties representing a Prismic form.

These are used to construct a default query.


type alias FormField =
{ fieldType : FieldType
, multiple : Basics.Bool
, default : Maybe String 
}

A field in a Prismic form.

These are combined to construct query parameters for the eventual Http request.


type FieldType

The type of values for a Prismic form field.


type alias Experiments =
{ draft : List String
, running : List String 
}

TODO: Experiments are not Strings. Fill out this type.

Decoders

Helpers for decoding various parts of a Document.


type alias Decoder val a =
Internal.Decoder val a

Decoders are parameterized by the input type val (Document, Field, Group or Slice) and the result type a -- your type representing your custom Prismic document type.

Decoder combinators

The following combinators can be used with any Decoder.

succeed : a -> Decoder val a

fail : String -> Decoder val a

map : (a -> b) -> Decoder val a -> Decoder val b

Transform a decoder.

apply : Decoder val (a -> b) -> Decoder val a -> Decoder val b

andThen : (a -> Decoder val b) -> Decoder val a -> Decoder val b

Pipeline decoders

decode : a -> Decoder val a

Begin a decoding pipeline.

type alias MyDoc =
    { title : StructuredText }

myDocDecoder : Decoder Document MyDoc
myDocDecoder =
    decode MyDoc
        |> required "title" structuredText

custom : Decoder val a -> Decoder val (a -> b) -> Decoder val b

Use a standard decoder in a pipeline.

The following is equivalent to the example using required:

myDocDecoder : Decoder Document MyDoc
myDocDecoder =
    decode MyDoc
        |> custom (requiredField "title" structuredText)

Decoding documents


type alias Document =
Internal.Document

Holds the Prismic document.

Documents consist of basic Fields, Groups and Slices.

You will decode this into your own document type by passing a Decoder Document MyDocType to submit.

id : Decoder Document String

The document's ID.

href : Decoder Document String

The document's href.

linkedDocuments : Decoder Document (List Field.DocumentReference)

The document's linked documents.

slugs : Decoder Document (List String)

The document's slugs.

tags : Decoder Document (List String)

The document's tags.

uid : Decoder Document (Maybe String)

The document's UID.

Decoding custom fields

requiredField : String -> Decoder Field a -> Decoder Document a

Decode a field.

Pass this function a Decoder Field a from the Prismic.Field module.

optionalField : String -> Decoder Field a -> a -> Decoder Document a

Decode a field that might be missing.

groupField : String -> Decoder Group a -> Decoder Document (List a)

Decode a group.

Pass this function a Decoder Group a from the Prismic.Group module.

Groups can contain Fields, but not other Groups or Slices.

Here is an example with a document containing a group:

type alias MyDoc =
    { albums : List Album }

type alias Album =
    { title : String
    , cover : Field.ImageViews
    }

albumDecoder : Decoder Group Album
albumDecoder =
    Prismic.decode Album
        |> Group.required "title" Field.text
        |> Group.required "cover" Field.image

myDocDecoder : Decoder Document MyDoc
myDocDecoder =
    Prismic.map MyDoc
        (Prismic.groupField "albums" albumDecoder)

sliceZoneField : String -> Decoder Slice a -> Decoder Document (List a)

Decode a SliceZone.

Pass this function a Decoder Slice a from the Prismic.Slice module.

Slices can contain Fields and Groups, but not other Slices.

type alias MyDoc =
    { sections : List Section }

type Section
    = -- The "my-content" slice has a non-repeating zone.
      MyContent Field.StructuredText
    | -- The "my-image-gallery" slice has a repeating zone.
      MyImageGallery (List Field.ImageViews)
    | -- The "my-links-section" slice has both non-repeating and repeating
      -- zones.
      MyLinksSection LinksSection

type alias LinksSection =
    { title : Field.StructuredText
    , links : List Field.Link
    }

myDocDecoder : Decoder Document MyDoc
myDocDecoder =
    Prismic.map MyDoc
        (Prismic.sliceZoneField "sections" sectionDecoder)

sectionDecoder : Decoder Slice Section
sectionDecoder =
    Slice.oneOf
        [ Slice.slice "my-content"
            -- Decode the non-repeating zone and ignore the repeating zone.
            (Group.field "text" Field.structuredText)
            (Prismic.succeed ())
            |> Prismic.map (\( content, _ ) -> MyContent content)
        , Slice.slice "my-image-gallery"
            -- Ignore the non-repeating zone and decode the repeating zone.
            (Prismic.succeed ())
            (Group.field "image" Field.image)
            |> Prismic.map (\( _, images ) -> MyImageGallery images)
        , Slice.slice "my-links-section"
            -- Decode both the non-repeating and repeating zones.
            (Group.field "title" Field.structuredText)
            (Group.field "link" Field.link)
            |> Prismic.map
                (\( title, links ) -> MyLinksSection (LinksSection title links))
        ]

Pipeline decoders

required : String -> Decoder Field a -> Decoder Document (a -> b) -> Decoder Document b

Decode a required field.

optional : String -> Decoder Field a -> a -> Decoder Document (a -> b) -> Decoder Document b

Decode a field that might be missing.

group : String -> Decoder Group a -> Decoder Document (List a -> b) -> Decoder Document b

Pipeline version of groupField.

sliceZone : String -> Decoder Slice a -> Decoder Document (List a -> b) -> Decoder Document b

Pipeline version of sliceZoneField.