Docs: No examples for client side only coding

[tonytopper]

The examples I've seen working assume you are using Marko on the server side.

I ran npm install -g marko. Looked inside the node_modules directory and didn't see an obvious file or folder to look into for the right JS file to put in a script tag.

Would be great to have a dead simple process for getting started with Marko purely client-side.

[patrick-steele-idem]

Hi @tonytopper, you have probably already seen them, but there are various sample apps in the following Github organization: https://github.com/marko-js-samples

I went ahead and created a new sample app that more closely matches your use case: https://github.com/marko-js-samples/marko-widgets-client-rendering

That sample app uses Lasso.js to bundle up the required JS and CSS files and to inject the required <script> and <link> tags into a static index.html file. Does that sample app work for you or do you think it can be simplified or improved?

[tonytopper]

It seems to me that a pre-built distributable file is a must. Not that you need to use it for all use-cases but it's great to get started quickly. Think of the jquery distributable, you can pick it apart but most people probably just use the whole library.

In other words, auto injection and build scripts are great, but that shouldn't be required for your first experience.

[patrick-steele-idem]

A JavaScript module bundler is a required and I don't see any way around it (it doesn't matter if it is Lasso.js, browserify or webpack)... The Marko compiler produces CommonJS modules as output. Compiled Marko templates use require() to load dependencies such as custom tags. Marko Widgets is written using CommonJS and Marko Widgets resolves widgets that are bound to DOM nodes using require(). Therefore you will need a JavaScript module bundler to pull in all of the code that is required to make a page work.

I don't see this as a problem though. Globals are generally evil and pre-built JavaScript libraries tend to be bloated.

Are you trying to avoid using a JavaScript module bundler?

[tonytopper]

The problem is not how it works; it's the barrier to entry for the first time explorer to begin working with it.

The sample you created was very helpful, but I am feeling that if you want people to be able to dive into Marko quickly you should take this a step further. Look at React's, Dust's or Angular's home page; it's dead simple to get started. They all have one or two JS files that you include and you're done.

Developers can go back later and get involved in the build and auto-injection and tweaking it for their specific use case later.

Marko and Marko Widgets, to me, at this moment, needs a dead simple way to get started that is front-and-center.

Are there things in the examples bundle.js that couldn't be included in a marko.js distributable file?

[patrick-steele-idem]

Let me ask you this: if we made it possible for developers tinker with the source code for a Marko Widgets UI component in an online editor would that solve the problem? We could absolutely do that, and that is one of the things that I am working on. My goal is to create an online Marko Widgets playground where you can change the JavaScript, CSS and template and see the results immediately.

This would be very similar to what React has on their home page and it would also be similar to the Try Online feature for Marko.

[tonytopper]

That would be great to have but wouldn't be what I am looking for. Notably because I have an existing project I want to quickly try to see if I can run a Marko Widget in.

[patrick-steele-idem]

Of course your existing project can ran Marko Widgets in it :) You just need to use a JavaScript module bundler to generate the JS file to include...

I completely understand where you are coming from, but because Marko produces a CommonJS JavaScript module as output and because the Marko compiler needs access to the file system (for discovering custom tags), Marko template files must be compiled on the server and you must use a JavaScript module bundler to transport them to the browser. I wish I could give you a better answer, but that is a design constraint and with that design there are some pros (e.g. better modularity) and some cons (e.g. no prebuilt bundles). Since you are hopefully already using a JavaScript module bundler, the leap to using Marko and Marko Widgets should not be much more.

[tonytopper]

Fired up your example, which has bundle.js, a single js file. Why not turn this into a distributable? With the templates not included of course.

Tried using lasso. My config file and it just ignores my outputDir and urlPrefix settings. Seems like a bug.

atopper@LM-SJC-00871867:~/workspace/darkstar$ lasso --main src/components/components.browser.json --name marko-bun
dle.js --config config/lasso-config.json
Config:
{
    "outputDir": "/Users/atopper/workspace/darkstar/static",
    "urlPrefix": "%STATIC_PATH%",
    "minify": false,
    "bundlingEnabled": false,
    "fingerprintsEnabled": false,
    "plugins": [
        "lasso-marko"
    ]
}

Optimizing page "marko-bundle.js"...
Successfully lassoed page "marko-bundle.js"!
------------------------------------
Output for page "marko-bundle.js":
  Resource bundle files:
    static/raptor-modules-1.0.27/client/lib/raptor-modules-client.js
    static/src/components/components.browser.json.js
  HTML slots file:
    build/marko-bundle.js.html.json
------------------------------------

lasso-config.json

{
    "outputDir": "src/.tmp",
    "urlPrefix": "",
    "minify": false,
    "bundlingEnabled": false,
    "fingerprintsEnabled": false,
    "plugins": [
        "lasso-marko"
    ]
}

[patrick-steele-idem]

There were some bugs indeed. Please try with a new version:

npm install lasso-cli@1.1.14 --global

[magixx]

I too am looking for some super simple examples on how to use client side rendering or just marko in general as it seems interesting. Coming from just referencing a static library/file (jquery) in my HTML, the learning curve for this seems much steeper. My current use case is just loading/generating HTML into some part of my page (the content changes based on the request url but uses the same 'template'). Currently I'm using jquery-pjax which does the trick but actually populating the HTML takes some seconds (for ~4mb of text) as it does it all at once. I'd like my page to immediately show content as soon as it has some data and then just continue loading the rest. Am I correct here that I just need marko client side only?

[patrick-steele-idem]

Hi @magixx, it does require a different toolbox to use marko since you can't just drop a <script> tag into your page. Instead, you will need to use a JavaScript module bundler as described above. However, the payoff is worth it because any project will benefit from being built in a modular way.

For your use case, it is not required to use Marko client side, but that is an option. It can be a little tricky to do streaming over AJAX. You get progressive HTML rendering for free from the web browser when the initial HTML for the page is streamed from the server, but you don't get streaming for free with AJAX. You can do streaming with AJAX, but you will be responsible for handling the data as it fills the buffer. You'll need a way to delimit each chunk. You can choose to either stream chunks of data and render HTML for each chunk client-side, or you can choose to stream HTML and append each HTML chunk to the DOM as it arrives. Also, you will like want to avoid jquery if you plan on doing streaming over AJAX and instead you should use the XMLHttpRequest object directly so that you have access to the response text as it arrives from the server.

[patrick-steele-idem]

I'm going to go ahead and close this issue now. If you still feel like we are missing more specific samples please open a Github issue. Thanks!