search

ghcjs / ghcjs-dom

Make Document Object Model (DOM) apps that run in any browser and natively using WebKitGtk
74 stars 40 forks source link

documentation (on-boarding) #64

Open mango314 opened 7 years ago

mango314 commented 7 years ago

I have been looking into the ghcjs set of tools as a way to build web sites. However, the documentation is very sparse. I had started looking at ghcjs but they informed me that is merely the Haskell to JavaScript compiles and if I actually want to interact with the DOM, I should look here

https://github.com/ghcjs/ghcjs/issues/568

There is a little bit of documentation on the other page, but none here. So I am offering to contribute as I learn. One of my colleagues is using reflex-frp but I ready to commit to that just yet. Especially since reflex depends on ghcjs, I wanted to start by learning to manipulate the DOM from Haskell in any capacity.

My basic "Hello World" example proved to be a challenge for many people. Obviously I want to build something more complicated, but many languages have some type of on-boarding. Elm is really good about emphasizing it's architecture, and front-end web development. ghcjs I have noticed is much more ambitious in scope, has more types and is not necessarily about front-end or back-end.

My question on StackOverflow (nearly closed) is about getting started with ghcjs and the conclusion seem to be that I need ghcjs-dom and that, since I am complaining I should be the one to write the docs.

http://stackoverflow.com/questions/42254610/how-to-code-h1-tags-with-ghcjs

Certainly I am willing to help out and make pull-requests as I learn more. For starters I use JSFFI to go with GHCJS? That should be made clearer from the start. Here is the example that tripped everyone up:

<h1>Hello World</h1>

<p>This is my test document.</p>

with Cascading Style Sheet (in general Haskell is going to manipulate the CSS and possibly the DOM tree itself, right? Inserting or removing tags, changing colors etc as the user clicks around)

h1 { font-family: Helvetica; }

p {font-family: Helvetica; color: blue; }
hamishmack commented 7 years ago

If you have time to write documentation and examples that would be great. We have fairly little of that right now. There is a very basic ghcjs-dom-hello but we could use more.

It might be a good idea to update the ghcjs-examples repository.

You could start by moving the out of date code into a directory called outdated (we can move them back if we fix them). The things I am sure are out of date are:

@luite will be able to advise on what to do with threads, try-purescript and threading, but my guess is that these should still work (or at least be fairly easily fixed.

Move the README.md to outdated/README.md as well and add a disclaimer explaining that the examples were designed to work with early versions of ghcjs and are now out of date and unlikely to be useful unless significant work is done to bring them up to date.

Then feel free to add some new examples or fix up any of the old ones.

tonyday567 commented 7 years ago

Maybe this repo might help a bit: https://github.com/tonyday567/ghcjs-testing

No testing is actually happening yet, but it is an end-to-end process for developing a page; from ghcjs code to publish.

And I agree with your aversion to framework commitment: vanilla dom is very important to understand before heading off to fancy.

mango314 commented 7 years ago

@hamishmack this was one of my first points of confusion. What exactly the relationship between ghcjs and fay? Do I use it instead of fay, with fay or both? And the role of Webkit.

A big one, is what is the relationship between ghcjs and reflex? They both uses JS and Haskell, but folks on StackOverflow and Github say they are totally different.

Lastly, as a beginner, should I worry about uses of ghcjs without the DOM? Perhaps the .js file exposes functions that are uses by other libraries and do not manipulate the DOM in any way. FFI seems very important.

That one example ghcjs-hello could be split into several examples, which I am currently trying to do. That looks like the most important.

cdsmith commented 7 years ago

@MonsieurCactus I'll try to give you answers here.

You would use GHCJS instead of Fay, not with it. Fay is a different approach to translating (a subset of) Haskell into JavaScript. The main differences are that GHCJS focuses on compiling as much practical Haskell as possible, including all language extensions, and most of the libraries on Hackage. Fay, on the other hand, compiles only a subset of Haskell, and almost no existing libraries; but the JavaScript it generates is quite a bit smaller and cleaner.

Reflex (http://hackage.haskell.org/package/reflex) is an FRP engine, and doesn't necessarily use JavaScript or HTML at all. The reflex-dom package (http://hackage.haskell.org/package/reflex-dom) uses Reflex to build an FRP approach to manipulating HTML DOM. It is a library rather than a compiler, and programs written with that library can be compiled using GHCJS. So you can use the two together nicely. But you can also use Reflex without GHCJS (if you're working on a non-web project), and you can use GHCJS without Reflex.

You should absolutely be interested in uses of GHCJS without the DOM. You can do plenty of interesting things in JavaScript without changing the DOM - even write server-side code with node.js. But more importantly to you, as a beginner, you should get the language and compiler bits down before you jump into a huge library, so I'd recommend you make sure you're basically comfortable writing ordinary Haskell code using GHCJS, before you try to tackle the library.

hamishmack commented 7 years ago

@hamishmack this was one of my first points of confusion. What exactly the relationship between ghcjs and fay? Do I use it instead of fay, with fay or both? And the role of Webkit.

No relation really, it was just a cool example that GHCJS could compile Fay (itself a compiler for a haskell like language). The try-purescript example does something similar and does it better (so no need to fix the Fay exmple).

A big one, is what is the relationship between ghcjs and reflex? They both uses JS and Haskell, but folks on StackOverflow and Github say they are totally different.

ghcjs compiles Haskell to JavaScript

ghcjs-base JavaScript interaction and marshalling (only compiles with ghcjs)

ghcjs-dom wrappers for almost all browser features (not just DOM). It has two implementations (automatically selected when you depend on ghcjs-dom):

reflex fully-deterministic, higher-order FRP interface and engine (compiles with ghc and ghcjs).

reflex-dom facilitates the development of web pages (uses reflex and ghcjs-dom)

reflex-platform an easy way to get all of these up and running using nix.

When you compile with ghc (instead of ghcjs) you also need a jsaddle runner package to provide the browser features:

jsaddle-webkitgtk and jsaddle-webkit2gtk use a WebKitGTK WebView for UI.

jsaddle-wkwebview uses a WKWebView for UI (for Mac OS or iOS).

jsaddle-warp will runs a mini web server and when a browser connects to it your application will run on the server but its UI will be in the browser (commands are sent over a websocket to a small interpreter).

jsaddle-clib for Android (coming soon).

That one example ghcjs-hello could be split into several examples, which I am currently trying to do. That looks like the most important.

Cool!

3noch commented 7 years ago

@MonsieurCactus If it's helpful, ghcjs is just a compiler, like gcc (for C), or javac (for Java). ghcjs is like ghc in that it compiles Haskell source code. ghc compiles Haskell to native machine code, whereas ghcjs compiles it to JavaScript. reflex is just a library written in Haskell, just like libcurl is a library written in C. reflex is a library for FRP. reflex-dom is another library that uses reflex and targets some specific features of ghcjs in order to build FRP webpages. Whereas Elm is a language (with its own compiler) for web pages, reflex-dom is nothing more than a Haskell library but it relies on ghcjs to produce JavaScript which can run in the browser.

mango314 commented 7 years ago

@3noch thank you for clarifying

@hamishmack you are the author, right? I just noticed that.

I am interested in using Haskell for web design (while at the same time learning Haskell), but I don't care too much about the DOM. With ghcjs, sounds like I'm able to achieve very deep computations in the browser... that might be clumsy to express in JavaScript.

Do I care too much about DOM or web development? No. Only enough for Haskell to communicate with the outside world. Then it becomes an exercise in pure Haskell, here compiled with ghcjs rather than ghc.

3noch commented 7 years ago

@MonsieurCactus Ah, if you simply want to write a Haskell web server that produces web pages, you don't need ghcjs at all. It would be similar, in spirit, to using Ruby on Rails or Python's Django. They don't generate JavaScript. They only allow you to write web servers which respond to requests with HTML web pages. If that's what you want to do, I recommend that you not use ghcjs at all and just start with a Haskell web framework like one of the following: