paf31 / purescript-jquery

Type declarations for jQuery

purescript-jquery

PureScript type declarations for jQuery. See module documentation on Pursuit.

Example

main = ready do
  -- Get the document body
  body <- body

  -- Create a text box
  div   <- create "<div>"
  input <- create "<input>"
  appendText "Your Name: " div
  append input div
  append div body

  -- Create a paragraph to display a greeting
  greeting <- create "<p>"
  css { color: "red" } greeting
  append greeting body

  -- Listen for change events on the text box
  on "change" (handleChange input greeting) input

  where
  handleChange :: JQuery -> JQuery -> JQueryEvent -> JQuery -> Effect Unit
  handleChange input greeting _ _ = unsafePartial do
    val <- getValue input
    for_ (runExcept (readString val)) \name -> do
      log $ "Name changed to " <> name
      setText ("Hello, " <> name) greeting

(from test/Main.purs).

Installation

bower i purescript-jquery

purescript-jquery's Issues

Change signature of on

Is currently

forall eff a. String -> (JQueryEvent -> JQuery -> Eff eff a) -> JQuery ->
         Eff (dom :: DOM | eff) JQuery

Seems like it could be changed to

forall eff a. JQuery -> String -> (JQueryEvent -> JQuery -> Eff eff a) -> 
         Eff (dom :: DOM | eff) JQuery

such that you could more easily write the on-action at the end, like

selector `on` "click" $ \event _ -> do
  someThing

or possibly

on "click" selector \event _ -> do
   someThing

Any rationale for the current order of arguments, it seems really awkward?

Use DOM effect from purescript-dom

Control.Monad.JQuery.create too permissive?

Context

First off I'm not sure what the long term goal of this library is, whether it is to provide an API that mirrors JQuery's close as possible (if so this is all me), or it's suppose to raise the abstraction to one that better suits Purescript and it's typesystem. Either way thanks for the library. Secondly I'm just getting started with purescript and I figured I'd mention some struggles I had when first using this library.

My struggle

Anyways so when I first started with this library I just looked at the types, and in particular the type for create which is...

create :: forall eff. String -> Eff (dom :: DOM | eff) JQuery

Looks simple enough, except I hadn't realised that even though the function was called create, I still need to include angle brackets in the string you passed to it, for it to create a tag, so my chain of thought was to use the function like this

main = ready do
  heading <- J.create "h1" >>= J.setText "Hello World"
  appBody <- select "#app"
  J.append heading appBody

How it should have been written is like so

main = ready do
  heading <- J.create "<h1>" >>= J.setText "Hello World"
  appBody <- select "#app"
  J.append heading appBody

Function definition

But judging by the definition of the functions select & create it wouldn't have made difference if I had chosen either, as long as I formatted the string correctly

foreign import create
  """
  function create(html) {
    return function () {
      return jQuery(html);
    };
  }
  """ :: forall eff. String -> Eff (dom :: DOM | eff) JQuery

foreign import select
  """
  function select(selector) {
    return function () {
      return jQuery(selector);
    };
  }
  """ :: forall eff. String -> Eff (dom :: DOM | eff) JQuery

So what happened in my original example was I actually selected all the h1 tags on the page changed their text to "Hello world" and inserted them into $("#app"), but since I had no h1 tags on the page, my page remained blank.

Possible alternative type

Would if be worth while creating an abstract data type like this to used in the place of the string in create?

-- I'm not sure what purescript's equalivent of newtype 
-- is, but I'd write it like this in haskell
newtype TagName = TagName { getTagName :: String }

h1 = TagName "<h1>"
p = TagName "<p>"
a = TagName "<a>"
-- lots of boilerplate!!!

So the definition stays the same, and the type of the function becomes

create :: forall eff. TagName -> Eff (dom :: DOM | eff) JQuery

I guess the draw back with this is you can't throw in arbitrary html, like <p>Hello World</p> like you can do with JQuery. But the function is called create, so maybe that's the job of a completely different function?

Anyways, Obviously I've solved the problem for my original code, but I figured due to confusion I had first starting out with this library maybe it's worth modifying the API for other new comers? Either way thanks again for writing this library!

Can not use purescript-jquery with <$>

 -- can not work
 void $ on "click" (deleteArticleHandler) <$> select "a[data-delete]"

-- following code will work
menuLink <- select "#menuLink"
void $ on "click" (menuLinkHandler) menuLink

It will compile to the following code.

Prelude["void"](Control_Monad_Eff.functorEff)(Prelude["<$>"](Control_Monad_Eff.functorEff)(Control_Monad_Eff_JQuery.on("click")(deleteArticleHandler))(Control_Monad_Eff_JQuery.select("a[data-delete]")))(); // function didn't run in this statement

var _0 = Control_Monad_Eff_JQuery.select("#menuLink")();
return Prelude["void"](Control_Monad_Eff.functorEff)(Control_Monad_Eff_JQuery.on("click")(menuLinkHandler)(_0))();

`on` Parameters

It seems quite plausible to me that on ought to be defined like this.

foreign import on
  "function on(evt) { \
  \  return function(act) { \
  \    return function(ob) { \
  \      return function() { \
  \        return ob.on(evt, function() { \
  \          act($(this))(); \
  \        }); \
  \      }; \
  \    }; \
  \  }; \
  \}" :: forall eff a. String -> (J.JQuery -> Eff eff a) -> J.JQuery ->
        Eff (dom :: J.DOM | eff) J.JQuery

With the original definition, something like

J.select ".foo" >>= J.on "click" (J.appendText "bar")

will add "bar" to every "foo" element. The proposed definition allows both this behavior and clicked-element-specific behavior.

Use browserify to "require" jQuery?

The FFI code relies on the jQuery global var which makes it difficult to bundle all the deps with browserify. If one of your dependencies has require('jquery') in there and you use browserify to bundle those deps, you will end up with two jquerys on the page: one included with a script tag (to have jQuery available as a global) and one in the bundle. There may be hacks to get around this (setting jQuery as global somewhere at the top level), but I wouldn't want to do that. I think this day and age, one should bundle all the deps anyway.

So, what I suggest is we add var jQuery = require('jquery') in the FFI code.

The setAttr has wrong type

The $(..).attr(String, String) is the right type for this function.
setAttr :: forall eff a. String -> a -> JQuery -> Eff (dom :: DOM | eff) Unit
should be
setAttr :: forall eff. String -> String -> JQuery -> Eff (dom :: DOM | eff) Unit

Writing an object generates an attribute att="[object Object]"

Any objection?

Looking for new maintainer

I'm not sure what is the best direction to take this library, and I don't have a use for it right now, so it would probably be better if someone took over maintainership.

on function issue with new row rules

The on function can lead to duplicate labels in rows.

What is on' for?

It takes an extra parameter, sel, but doesn't seem to use it.

Add $(..).data

Would it make sense to include $(..).data?

Add $(..).attr

I see there is no a getAttr function, but there is a setAttr
is there a reason for this? or just pending feature?

AJAX functionality?

There are some great DOM wrappers here -- any chance for getting wrappers for the AJAX stuff as well?

find children?

Is there a function to find children of a given JQuery (ala .find())? I don't seem to see one... but I've been wrong before ;)

Selecting document, window, HTMLElements, et.c.

It looks like the only thing you can us as a selector is String, but it's heavily overloaded in jQuery. e.g. $(document).ready, $(window).on("popstate"), $(document.body), $($("why")). Has anyone given this any thought?

I'd suggest that special operations be completely separate functions, such as ready already is for $(document).ready, and we could have selectWindow and selectDocument for $(window) and $(document) respectively. This way it is possible to use these objects as normal elements, but you can certainly misuse these. Another option would be adding a type parameter to JQuery, that way we may be able to be more granular in type signatures.

In fay-jquery we chose to only allow elements, strings, and jquery objects as input to select.

Should have a function to select element from page

Ala

foreign import select
    """function select(selector) { return function() {
        return jQuery(selector);
    }}""" :: forall eff. String -> Eff (dom :: DOM | eff) JQuery

getValue returns Foreign?

Can the value of a field ever be not a string?

Any chance of updating purescript-dom to version 2.0.1?

Old purescript-dom conflicts with more newer used in other libraries