yesod-gitrepo: Host content provided by a Git repo

[ library, mit, web ] [ Propose Tags ]

Please see the README and generated docs at https://www.stackage.org/package/yesod-gitrepo


[Skip to Readme]

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.1.0, 0.2.0.0, 0.2.1.0, 0.3.0
Change log ChangeLog.md
Dependencies base (>=4.9 && <10), directory, http-types, process (>=1.1), temporary, text, unliftio, wai (>=3.0), yesod-core (>=1.6 && <1.7) [details]
License MIT
Author Michael Snoyman
Maintainer michael@snoyman.com
Category Web
Home page https://github.com/snoyberg/yesod-gitrepo#readme
Bug tracker https://github.com/snoyberg/yesod-gitrepo/issues
Source repo head: git clone https://github.com/snoyberg/yesod-gitrepo
Uploaded by MichaelSnoyman at 2018-02-05T18:14:09Z
Distributions LTSHaskell:0.3.0, NixOS:0.3.0, Stackage:0.3.0
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 4024 total (17 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-02-05 [all 1 reports]

Readme for yesod-gitrepo-0.3.0

[back to package description]

yesod-gitrepo

Build Status Build status

yesod-gitrepo provides a means of embedding content from a Git repository inside a Yesod application. The typical workflow is:

  • Use gitRepo to specify a repository and branch you want to work with.
  • Provide a function that will perform some processing on the cloned repository.
  • Use grContent in your Handler functions to access this parsed data.
  • Embed the GitRepo as a subsite that can be used to force a refresh of the data.
  • Set up a commit handler that pings that URL. On Github, this would be a webhook.

This is likely easiest to understand with a concrete example, so let's go meta: here's an application that will serve this very README.md file. We'll start off with language extensions and imports:

{-# LANGUAGE NoImplicitPrelude #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes       #-}
{-# LANGUAGE TemplateHaskell   #-}
{-# LANGUAGE TypeFamilies      #-}
import           ClassyPrelude.Yesod
import           Text.Markdown
import           Yesod.GitRepo

Now we're going to create our foundation datatype. We need to give it one field: the GitRepo value containing our parsed content. Our content will simply be the text inside README.md, wrapped up in a Markdown newtype for easy rendering. This gives us:

data App = App
    { getGitRepo :: GitRepo Markdown
    }

instance Yesod App

And now let's set up our routes. We need just two: a homepage, and the subsite. Our subsite type is GitRepo Markdown (as given above). We replace the space with a hyphen as an escaping mechanism inside Yesod's route syntax:

mkYesod "App" [parseRoutes|
/ HomeR GET
/refresh RefreshR GitRepo-Markdown getGitRepo
|]

Next up is our home handler. We start off by getting the current content parsed from the repository:

getHomeR :: Handler Html
getHomeR = do
    master <- getYesod
    content <- liftIO $ grContent $ getGitRepo master

Then it's just some normal Hamlet code:

    defaultLayout $ do
        setTitle "yesod-gitrepo sample"
        [whamlet|
            <p>
                <a href=@{RefreshR GitRepoRoute}>
                    Force a refresh at
                    @{RefreshR GitRepoRoute}
            <article>#{content}
        |]

And finally, our main function. We pass in the repo URL and branch name, plus a function that, given the filepath containing the cloned repo, processes it and generates a Markdown value. Finally, we provide the generated repo value to our App constructor and run it:

main :: IO ()
main = do
    repo <- gitRepo
        "https://github.com/snoyberg/yesod-gitrepo"
        "master"
        $ \fp -> fmap Markdown $ readFile $ fp </> "README.md"
    warp 3000 $ App repo

Give it a shot. You should have a webapp hosting this very README file!