jordanmartinez/learn-halogen

Learn purescript-halogen using a bottom-up apporach via this "clone-and-play" repository

Learn Halogen

This repo has been archived. Feel free to fork it and continue maintaining it provided you abide by the license restrictions below. This repo has NOT been updated to compile on PureScript v0.14.0, nor Halogen v6.0.0, nor any PureScript or Halogen releases made after those. The last versions on which this repo compiled correctly was PureScript v0.13.8 and Halogen v5.0.0-rc.5.

See Archiving my 'Learn Halogen' repo for more details.

---

Learn purescript-halogen, (v5.0.0-rc.5) from a bottom-up approach

Requirements

Before learning Halogen via this project, you will need to install the following. (If you don't have them already installed, see my purescript learning repo's Install Guide

• purescript (v0.13.6)
• spago (v0.14.0)
• parcel (v1.12.4)

Or, to install them in one line

npm i -g [email protected] [email protected] parcel

Or, instead of install globally, install relatively to this project

npm i

If you choose this approach, all aftermentioned commond like spago ... and parcel ... shall be prefix with npm run. e.g.

• npm run spago bundle-app -m ...
• npm run parcel serve ...

Target Audience

Required: You are already familiar with...

• PureScript's "Basic" syntax. (If not, see my Basic Syntax overview)
• PureScript's "Module" syntax. (If not, see my Module Syntax overview)
• the purescript-prelude library. (If not, see my Prelude-ish folder)
• "smart constructors." (If not, read my explanation on Smart Constructors)
• the Effect and Aff types and how they work. (If not, see my Effect and Aff folder)

Helpful, but not absolutely necessary: You are already familiar with...

• the philosophical foundations of Functional Programming. (If not, see my FP Philosophical Foundations Overview)
• PureScript's "Type-Level Programming" syntax. (If not, see my Type-Level Programming Syntax overview)
• "do notation." (If not, see my overview on Do Notation. Specifically, Discard.md to Reading Do as Nested Binds.md)
• monad transformers and how they work. (If not, see my Application Structure folder. Specifically, the MTL folder.)

Instructions

1. Git clone this project
2. Run spago build
3. Run spago docs --open
4. Read through each folder using the same rules that I use in my learning repo (described in the third bullet point here).

Don't want to clone-and-play? Then read through this repo using the Table of Contents file.

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license: (Human-readable version), (Actual License)

learn-halogen's Issues

Update project to use PureScript 0.13.3 release

Upgrade project to v5.0.0-rc.6 Halogen release

spago docs failing

spago docs failed with the following error

Generating documentation for the project. This might take a while..
Error found:
in module Halogen.Query.EventSource
at .spago/halogen/v5.0.0-rc.4/src/Halogen/Query/EventSource.purs:32:8 - 32:66 (line 32, column 8 - line 32, column 66)

  Type class instances for type synonyms are disallowed.

in type class instance
                                                         
  Data.Newtype.Newtype (EventSource m a)                 
                       (m                                
                          { finalizer :: Finalizer m     
                          , producer :: Producer a m Unit
                          }                              
                       )                                 
                                                         

See https://github.com/purescript/documentation/blob/master/errors/TypeSynonymInstance.md for more information,
or to contribute content related to this error.


spago: Docs generation failed.

Link to 'Styling Question' and its links

thomashoneyman/purescript-halogen-realworld#46 (comment)

Change Travis CI configuration to build with multiple versions of Node

The way to specify specific versions of Node to test on Travis CI https://docs.travis-ci.com/user/languages/javascript-with-nodejs/ is like:

node_js:
  - '7.5'
  - some other version
  - etc

Link to 'Questions regarding the development of the Purescript Halogen library`

I don't think I ever linked to the Discourse thread where I asked Gary about how the Halogen internals actually worked. Might be helpful to include that here.

https://discourse.purescript.org/t/questions-regarding-the-development-of-the-purescript-halogen-library/236

Update Halogen Flowchart to include HalogenIO.dispose

This was updated in latest commit to development, but I still need to make a release for it.

Suggestion: Generate a PDF file containing the ToC and contents of this repo

Is there a way to generate a PDF with the entire content outlined in the table of contents?

Update project Purescript 0.13

Might be a few days or even longer before all dependencies compile on this release.

use forall instead of Void for empty queries, messages, inputs

from #65

it's also possible to use forall like

-- approach is used here 
-- https://github.com/purescript-halogen/purescript-halogen/blob/bb715fe5c06ba3048f4d8b377ec842cd8cf37833/examples/higher-order-components/src/Harness.purs#L43
-- https://github.com/purescript-halogen/purescript-halogen/blob/bb715fe5c06ba3048f4d8b377ec842cd8cf37833/examples/components-inputs/src/Container.purs#L39

simpleChildComponent :: forall query input messages . H.Component HH.HTML query () input messages Aff

-- and render using `unit` for values and `absurd` or `const unit` for functions

let index = unit -- or some integer
let input = unit -- or some datatype. On first render passed to `initialState` and to `receive` on subsequent renders if `input` is changed
let messageHandler = absurd -- or `Just <<< HandlePanelMessage`
HH.slot _proxy index simpleChildComponent input messageHandler

instead of

type MyQuery = Const Void
type MyInput = Void
type MyMessages = Void
simpleChildComponent :: H.Component HH.HTML MyQuery () MyInput MyMessages Aff

Suggestions

1. this guide is hard to read because I always have to check the exact definition of functions in src/Scaffolding folder, Ideally I would like this folder to be deleted and util functions should not be used. Each example should be self-sufficient. If you dont want to tell about something beforehand - you can just write "More about this field later."

2) I would be good to have the results of compilation to be included in project, near the examples

`--no-minify` is not supported by `serve` action of `parcel`

In the Learn Halogen there is a compilation instruction:
parcel serve assets/path/to/corresponding/HTML_File.html -o HTML_File--parcelified.html --open --no-minify
However, parcel serve does not support --no-minify, only parcel build suports it.

Correct Halogen Flowchart's Input flow

On FP Slack:
@garyb: I’m not sure that flowchart is quite right when it comes to input values. There’s nothing in Halogen that checks whether the input value differs at all, the user has to do that in the receiver - the receiver will be triggered for every child every time the parent renders. Also changing the input value does not reconstruct the component - that’s kinda the whole point 😄I’ve written a bunch about the lifecycle in the new Halogen docs, I’ll push it somewhere so you can have a look and see if it matches your understanding, if that’d be useful?

me: Oh! Ok. I'll need to update that then...

Feature Request: convert to mdBook

What:

• convert this repo to an mdBook.

Why:

• I have been consuming the mdBook from JordanMartinez/purescript-jordans-reference#511.
  • This has been much easier to use.

Add Travis badge?

I saw a Travis build file but there is no badge on the README.

Add Select/Formless Component Template files

Not all values and functions from these components are shown, but they're enough to get most people started:

• Select: JordanMartinez/purescript-halogen-select@209a111
• Formless: JordanMartinez/purescript-halogen-formless@47f8ad7

Change `purescript-jordans-reference` links to use its `latestRelease` branch?

The ReadMe.md has links to your reference site such as https://github.com/JordanMartinez/purescript-jordans-reference/tree/ps-0.13.x-v0.17.1/11-Syntax/01-Basic-Syntax but maybe should be linked to the latestRelease branch instead of ps-0.13.x-v0.17.1? I noticed the discrepancy when see comments about issues that have since been resolved in latestRelease.

Update project to 0.13.4 PS release

Add tip from Gary for rendering valid/invalid input data

If one reads through Text Input not tracking state and, more specifically, Gary's comment about using Either String ValidatedValue, this can help with knowing how to deal with uncontrolled components.

Link to statebox's fork of halogen-svg

Update halogen-svg link to point to this fork: https://github.com/statebox/purescript-halogen-svg

This is the most up-to-date repo full of SVG elements. There are some issues, but it's better than nothing and/or linking to the original repo that's outdated.

Recommend spago's --watch feature in automatic reload instructions

In https://github.com/JordanMartinez/learn-halogen/blob/latestRelease/src/01-Static-HTML/01-Static-HTML.md#automatic-reload there's a recommendation of using watchexec tool for automatic rebuilding of purs source files. Instead of introducing another external tool, it might be better to recommend spago's --watch feature which achieves the same without requiring external tool. I can make a PR if you agree with my proposal.

Add exercises for each example

How do you feel about adding a section with one or more exercises to each example?
I'm happy to contribute exercises as I work through each section.

It may also be helpful to have exercise solutions. To include those, should I just shift the numbering prefixes?

src/01-Static-HTML/01-Static-HTML.md
src/01-Static-HTML/02-Static-HTML.purs
src/01-Static-HTML/03-Static-HTML-solutions.purs  <--- New file
src/01-Static-HTML/04-Adding-Properties.md
etc.

Link to 'template repo' for Halogen

https://github.com/purescript-templates/halogen

See Featured Templates for more context.

Generate ToC for latest release

I just realized I haven't been regenerating the ToC in these past 2 releases...

Scaffolding Obscures Actual Types

I am going through some of the lessons and there seem to be a lot of types aliases that obscure the actual type. Thus I go to the scaffolding module and find what it actually is and then flip back and forth between the pages until I memorize what the alias actually is.

Would it not be better to use the actual types, put the aliases in the same file, or use a comment for the aliases?

Example StateActionMessageComponent:

learn-halogen/src/03-Parent-Child-Relationships/01-Childlike-Components/04-Message-Only.purs

Line 28 in 951f7c3

textAndButtonComponent :: StateActionMessageComponent State Action

Which to cover first? Halogen Hooks or Halogen Components?

While components are what Halogen actually understands, hooks are easier to read and use. I also think hooks don't require a template because they "just work." I'm not sure whether compiler errors are any worse than components.

Anyways, the question is, should this repo cover hooks first, which are likely easier to use, more powerful/flexible than components, and otherwise just better practically everywhere? Or should they be covered after components because that understanding is still the foundation of Halogen?

Add CI build for local-based installation

Following up from #55, add a CI build that verifies the local installation and all of its commands work properly.

purescript-halogen-svg not maintained

In It does not appear that purescript-halogen-svg will be upgraded for halogen 5. kwohlfahrt/purescript-halogen-svg#7

From lesson src/01-Static-HTML/01-Static-HTML.md

What’s best practice/pattern for cross component communication

1. for figure 1, how component A talks to C (Query or Input)? Do I have add intermittent data in component B?
2. for figure 2, how B and C communicate with each other
3. for figure 3, sort of real use case. when I update user name in ‘User Profile Form’, how I can update ‘Header information’ where displays user name.

port from https://discourse.purescript.org/t/whats-best-practice-pattern-for-cross-component-communication/1066

log element's text?

Thanks for this great tutorial. Enjoy reading it!

https://github.com/JordanMartinez/learn-halogen/blob/latestRelease/src/02-Dynamic-HTML/06-Referring-to-Elements.purs#L39

handleAction :: HandleSimpleAction State Action
handleAction = case _ of
  PrintExample -> do
    -- Here, we use this reference to do something with the element
    H.getHTMLElementRef (H.RefLabel "my-button") >>= traverse_ \element -> do
      -- in this situation, we'll just state that the element exists
      -- and could be used here
      -- todo: get infor from element
      liftEffect $ log "We can now do something directly to the \
                         \button HTML element.

delete the line of H.getHTMLELEMENTRef still get the same behaviour. maybe log the element's text to show the element is the 'my-button' element?

I tried to get the text out of the button element, but seems not as easy as I thought.

Upgrade project to PS 0.13.5

launchAff_ vs runHalogenAff

I noticed the official halogen examples use runHalogenAff, while your examples use launchAff_.
Both seem to behave identically, but perhaps that's only in situations where no exceptions are thrown.
How do you feel about converting your examples to be more consistent with the other learning materials out there?
Should there be a note added describing the differences and situations where one would be preferred over the other?

Learning curve

First up, this is absolutely excellent (along with your general purescript guide). Thank you so much for putting it online.

I'm not a purescript or halogen beginner, but I have been using your guide to refresh my understanding of halogen and improve the gaps in my purescript. One thing that springs out at me is that like the issues raised in #36 I found when I moved through your examples, I quickly got to the point where I wanted to build an extremely simple real halogen component and start to construct an app with it, and to do that I had to kind of pore through the scaffolding code (very easy to do) and reconstruct the call to mkComponent myself. Not terribly difficult for me to do, but I can't imagine it'd be easy for a beginner, or intermediate.

One thing I find difficult about the halogen docs themselves (and I'm using your docs as surrogate docs) is that the types are huge. I feel like everyone would have said this, so I'm not complaining at all here, it's what you need to have if you want a good component system.

However, the standard component type hardly fits in my short-term memory, and it's positional (ie not using a record). Your scaffolding really makes it a lot easier at first, but it suffers from the problem of it being harder to learn "the real way", if that's what you're after later — so I'm advocating for gradual ramp-up with simple real-world components of increasing complexity.

So I suppose what I'm suggesting is... keep the scaffolding, and also add non-scaffolded versions of each. This would clear it up and make the parent/child communication section a lot clearer, I think, too. I'm suggesting a more gradual ramp-up, both with the training wheels on, and off at the same time, so that when someone is interested in taking the training wheels off, they can go back to the simple examples and try the variants without the training wheels.

(So on the one hand, we've got the complexity level of the examples, which ratches up slowly, and on the other hand we have the "training wheels" (scaffolding), which can be on and off both at the same time, to allow someone to learn with or without independently of the complexity of the examples — naturally certain levels of complexity will only have the traning wheels off, at which point you can say go back to "X" point and learn with the training wheels off now please)

Thank you again so much for writing this, and I'm happy to help if you'd like some help.

Update Halogen Formless template link to point to official version in Formless repo

https://github.com/thomashoneyman/purescript-halogen-formless/releases/tag/v1.0.0-rc.1

This would replace the link in the 'where do we go from here' file

Upgrade project to Spago 0.12.1

Const Void or Const Unit for unused Query

If queries are ignored, should QueryType be Const Void or Const Unit?
Are they interchangeable? I see both types used in different places in the docs.

Generate Docs with spago-docs-search

Hi, thank you for this nice project.

In reading the projects, it always include some looking up definitions through ./generated-docs/index.html. https://github.com/spacchetti/purescript-docs-search provides a nice search box to easy the search process.

Perhaps it is nice to add the docs-search in the project.

Integrate examples with `halogen-storybook`

Coming from #71, specifically this comment, update this repo's examples to use purescript-halogen-storybook.