Tip: If you're just getting started, it's usually better to start by creating a chapter (checkout the ElmBook.Chapter
module).
Check out the "Books" guide for more examples.
This module is used to create your books main output. You need to list your book's chapters here and also provide any global options you may want to define.
main : Book ()
main =
book "My Book"
|> withChapters
[ firstChapter
, secondChapter
]
book : String -> Internal.Book.BookBuilder state (Html (Msg state))
Kickoff the creation of an ElmBook application.
withChapters : List (Internal.Chapter.ChapterCustom state html) -> Internal.Book.BookBuilder state html -> Internal.Application.BookApplication state html
List the chapters that should be displayed on your book. Checkout ElmBook.Chapter
if you want to create a chapter.
Should be used as the final step on your setup.
withChapterGroups : List ( String, List (Internal.Chapter.ChapterCustom state html) ) -> Internal.Book.BookBuilder state html -> Internal.Application.BookApplication state html
Organize your book's chapters into groups.
Should be used as the final step on your setup.
book "MyApp"
|> withChapterGroups
[ ( "Guides"
, [ gettingStartedChapter
, sendingRequestsChapter
]
)
, ( "UI Components"
, [ buttonsChapter
, formsChapter
, ...
]
)
]
You can pipe any of the customization functions on your book's creation. Just make sure you're passing these functions before you call withChapters
or withChapterGroups
functions.
withThemeOptions : List (ThemeOptions.ThemeOption html) -> Internal.Book.BookBuilder state html -> Internal.Book.BookBuilder state html
You can customize your book with any of the options available on the ElmBook.Theme
module. Take a look at the "Theming" guide for some examples.
main : Book x
main =
book "My Themed Book"
|> withThemeOptions
[ ElmBook.ThemeOptions.globals [ myCssReset ]
, ElmBook.ThemeOptions.background "slategray"
, ElmBook.ThemeOptions.accent "white"
]
|> withChapters []
withChapterOptions : List ChapterOptions.Attribute -> Internal.Book.BookBuilder state html -> Internal.Book.BookBuilder state html
By default, your chapter will display its title at the top of the content. You can disable this by passing in chapter options.
book "My Book"
|> withChapterOptions
[ ElmBook.Chapter.hiddenTitle True
]
|> withChapters []
Please note that chapter options are "inherited". So you can also override these options on a particular chapter and that will take priority of book-wide options. Take a look at ElmBook.ChapterOptions
for all the options available.
withComponentOptions : List Internal.ComponentOptions.Attribute -> Internal.Book.BookBuilder state html -> Internal.Book.BookBuilder state html
By default, your components will appear inside a card with some padding and a label at the top. You can customize all of that with this function and the attributes available on ElmBook.ComponentOptions
.
main : Book ()
main =
book "My Book"
|> withComponentOptions
[ ElmBook.Component.background "black"
, ElmBook.Component.hiddenLabel True
]
|> withChapters [ ... ]
Please note that component options are "inherited". So you can override these options on a particular chapter and even on an specific component.
withStatefulOptions : List (StatefulOptions.Attribute state) -> Internal.Book.BookBuilder state html -> Internal.Book.BookBuilder state html
Stateful options are useful for interactive books. With them you can set your book's initialState or even give it your custom subscriptions. Take a look at the "Stateful Chapters" guide for more details.
Attributes for this function are defined on ElmBook.StatefulOptions
.
Internal.Application.BookApplication state (Html (Msg state))
Defines a book with some state and some type of expected html.
If you're working with something other than elm/html
(e.g. elm-css or elm-ui) then check out the ElmBook.Custom
module.
If you're creating a stateful book, you will need to pass your custom SharedState
as an argument as showcased below.
import FirstChapter
import SecondChapter
type alias SharedState =
{ firstChapter : FirstChapter.Model
, secondChapter : SecondChapter.Model
}
initialState : SharedState
initialState =
{ firstChapter = FirstChapter.init
, secondChapter = SecondChapter.init
}
main : Book SharedState
main =
book "MyApp"
|> withStatefulOptions
[ ElmBook.StatefulOptions.initialState
initialState
]
Internal.Msg.Msg state