How to use (plates on the server)?

[Rob Koberg]

OK, I am new to nodejs (a few days), so these might be an off topic
questions for a project like flatiron and its sub/standalone projects.
How do I reinstall? I haven't done much yet and I can just blow away
the webapp and start fresh. However, if I had a good chunk of work
done and I needed to do a reinstall my guess is that I would need to
rename my project (e.g. flatiron-test.bak), then do:

$ flatiron create flatiron-test

and copy over my custom code. Or this is a very rare thing because it
is dealing with the package.json and npm update would normally handle
things?

This brings up other issues (I can create separate threads if you
like):

* what are or where do I find the boilerplate types (create myproj
<type>)? It is not readily apparent what types are available.
* is there a 'kitchen sink' create boilerplate type?
* Are there more complete examples of how to use the flatiron projects
together rather than the standalone, simplistic examples in the sub
projects? I have read the nodejs docs, but surely there are best
practices for a project like flatiron in setting up a real world app.
* when I first started with nodejs (a few days ago) I quickly found
expressjs and then expressling. expressling was an extremely helpful
project in seeing how to work with node and the express project. But I
did not like any of the template engines. Your plates projects is
exactly what I am looking for (Did you know there is a plate project?
https://github.com/chrisdickinson/plate which caused me some initial
confusion when doing some general searches about how to integrate with
express). Anyway, how do you use plates within flatiron? (I only see
examples for the browser)
* I would be happy to work off the latest git master and provide
feedback. What is the best way to do that? (and have other released
node modules in my projects handled by npm update)

I really liked what I read in your blog posts. For example
http://blog.nodejitsu.com/introducing-flatiron :
"In Node.js we have npm, which has allowed a diverse ecosystem of
modules to develop. This has fostered a philosophy of creative
experimentation, but not made it any easier to make these choices."
and
"A full-stack web application development framework which packages
these tools together to make isomorphic and stream-based application
development easier." -- how?

So far, and again it is probably just my inexperience with nodejs, but
it is not clear how to take advantage of flatiron (only a few hours).

Any links or tips would be greatly appreciated.

best,
-Rob

[Joshua Holbrook]

Hi Rob!

Welcome to the mailing list, first of all. You asked a lot of
questions, so I'm going to just go through them as best I can:

## Version Control

First, you should use a version control system, such as git or svn, to
manage your code. If you're not familiar with the concept of version
control, it's basically a way to keep a log of incremental changes
you've made to a project, with the ability to roll back to previous
commits, manage branches and a whole bunch of other stuff. If you're
new to the idea of version control, I'd recommend git and github, if
for the social aspects and documentation alone.

Once you have some git on that, there are a few different levels of "nuking it":

1. Delete non-bundled dependencies in the ./node_modules folder
(recursively) and re-run `npm install` to reinstall project's
non-bundled dependencies.
2. Running `git stash` to clean up files you haven't staged for commit
temporarily
3. Running a soft git reset to un-stage files
4. Running a hard git reset to start over at a given commit.
5. Deleting your local copy and re-cloning from master.
6. Force-pushing a fixed version on top of whatever monstrosity you
accidentally pushed to master at 3:00am.

You can probably think of more. Get creative! ;) The point is, once
you figure out a version control system you can use, you're going to
ask yourself where it's been your entire life.

If you use git, working off a project's master branch is easy:

    % git clone g...@github.com:user/project.git
    % cd project
    % sudo npm link

## Boilerplates

Unfortunately, the current flatiron cli tool isn't well-documented.
There are two types of templates: http and cli. The "create" command
will treat the type specification as the fourth argument, or default
to http. No bigger ones yet, but I'm sure they'll come in time!

I remember expressling now that I see it. The boilerplate's a little
big for my taste, but I do like it a lot better than express's
built-in boilerplate! We should see about getting it added to
node-apps/boilerplates at least.

## Flatiron

Unfortunately, the base flatiron project is not very well-documented.
Basically, flatiron/flatiron is a broadway injection container with a
few base plugins (for configuration and logging) pre-loaded, so a lot
of the documentation for broadway also applies to flatiron.

The extension model is centered around broadway. Basically, the idea
is that instead of middlewares (like in express), we'll use broadway
plugins to evolve our simple container into whatever we need. For
example, check out this component for cli applications:
https://github.com/flatiron/cli-config

Many of the sub-projects have much longer histories than broadway or
flatiron proper. For instance, director's first commits are from
roughly two years ago (then the project was named sugarskull and
client-side only), and director was also heavily influenced by an
older server-side router called 'journey' of similar age. The point is
that these projects have been around longer and therefore have had
more time to collect documentation.

For now, I would suggest trying to read some of Nodejitsu's code,
since many of our projects are based on flatiron/flatiron and its
sub-components. nodejitsu/haibu, for example, uses broadway
extensively, and nodejitsu/jitsu is currently going through a refactor
to use flatiron. I'd also recommend checking out flatiron's cli-config
library to get an idea of how plugins can be written.

## Plates

You can use plates like so:

    var Plates = require('plates');

Then use Plates exactly like you would in the browser!

(Also, I did not know about Plate, but someone else may have.)

## npm

You'll want to read http://npmjs.org/doc/ .

Cheers,

--Josh

--
Joshua Holbrook
Engineer
Nodejitsu Inc.
jo...@nodejitsu.com

[Rob Koberg]

Thank you for the detailed reply. I will be spending some time over
the weekend digesting/attempting.

I do have experience with version control, first with cvs and later
svn (spent most of the time in java apache land) (and XSL - <duck/>).
Lately I have switched over to git. I definitely have more learning to
do with git and dependencies.

My "How do I reinstall?" was out of context when I pasted and did not
edit enough. It was related to this issue:

https://github.com/flatiron/flatiron/issues/23

where a version number change in the package.json required a reinstall.

Thanks for the nodejitsu reference. I think that is exactly what I am
looking for as a full code example (obviously it is more than an
example) and a potential hosting source. We mostly manage our own with
rackspace dedicated and cloud servers. It is good to see you eat your
own dog food.

best,
-Rob

[Rob Koberg]

Hi,

Thanks again for your time.

Perhaps I am misunderstanding the goals of flatiron. Is flatiron for
building webapps? Or is it a framework to support nodejs webapps
created in some other system? Or perhaps it is meant to send json data
to static html pages for client side assembly? Or perhaps I am just
hitting the project in its early stages and need to check it out again
in a few months?

It looks like it is going to take more effort and time than I have to
evaluate in its current documented/exampled state. For me at least, it
would be helpful to have a flatiron best practices webapp like a blog
(or whatever) connected to a DB using some type of json schema
equivalent /ORM/ to see how a webapp works in flatiron. In other
words, use that best practices webapp to recursively learn the
internals of flatiron. There is a lot there. A guide (webapp) would
speed things up and lead me in the right direction to speed
understanding.

I have been looking around and I can't find an example of
assembling/transforming templates into a page on the server to send to
the client. Again, expressling allowed me to do that for express (and
found I did not fall in love with it). What I have read from the blog
entries is very much what I am looking for in architecture. I just
don't see how to use it to create a web page in a scalable way.

From what I can determine so far for plates, I would need to load
template files from the file system into strings (or heaven forbid,
write the HTML into the code) to assemble into an HTML page (creating
my own caching scheme), send that string to the response stream while
writing all the headers I need for each response. Is that the case?

The unobtrusive templating approach is very appealing to me and very
important. CSS/HTMLers can create templates with example content (for
sign off before it gets to development) to be replaced at runtime
without them having to know variables or do any kind of conditionals
or looping. Development uses the example content as a guide for the
runtime content assembly/transformation. We do A LOT of web sites
ranging from simple static pages to large hierarchical group
role-based sites (e.g. state, county, school district, school, class).

fwiw,
-Rob

[Nick Baugh]

I'd love to port over Expressling.  Maybe we could Skype or something? I'm on IRC too, I'd really like to help out :)

I'm also going to be porting Bootstrap to Stylus -- so that is something we could include too if wanted.

[bradley.meck]

Flatiron is a framework that supports Web Applications, but that is not the sole role. Flatiron is a very modular framework unlike the STL, Java Standard Lib, etc. As such, each component can function independent of the other components. Special care has been given to give each component a purpose while avoiding them requiring each other as much as possible. This allows applications to use only relevant parts of Flatiron instead of bringing in all of Flatiron all the time. As such, Plates does not directly have magic methods attached to Union, but given the nature of simple string passing, setting it up is as easy as calling Plates inside of a route to Union's HTTP handler.

I agree that there may be some need to create a step by step example project. What exactly are you looking for in an example that is difficult to find right now?

[Rob Koberg]

On Sun, Feb 12, 2012 at 12:51 PM, bradley.meck <bradle...@gmail.com> wrote:

> I agree that there may be some need to create a step by step example
> project. What exactly are you looking for in an example that is difficult to
> find right now?

From my previous post:

"From what I can determine so far for plates, I would need to load
template files from the file system into strings (or heaven forbid,
write the HTML into the code) to assemble into an HTML page (creating
my own caching scheme), send that string to the response stream while
writing all the headers I need for each response. Is that the case?"

Say I have a page wrapper template and a list of blog entries for one case:

file system path/to/templates/wrapper.html:

<html>
<head>
<title>Change to current page title | This site's static name</title>
</head>
<body>
<header>
<h1>Current page title</h1>
</header>
<div id="page-content">
<p>Current page content replaces this</p>
</div>
<footer>
<p>&#169; <span class="site-name">Site's static name</span>
<span class="current-year">Current year</span></p>
</footer>
</body>
</html>

And a request is made for /blog (list of blog entries), where the
(wrapper sub) template for the 'Current page content' is:

file system path/to/templates/blog.html:

<ol id="blog-entries">
<li class="blog-entry" role="template">
<h2>Example entry 1</h2>
<div class="authoring">
<img src="http://placehold.it/30x30"/>
<span class="author">Some author</span>
<span class="last-edited">Some date format</span>
</div>
<div class="blog-entry-content">
<p>Lorem ipsum...</p>
</div>
<div class="links">
<a class="read-more" href="some/path">Read more</a>
</div>
</li>
<li class="blog-entry">
<h2>Example entry 2</h2>
<div class="blog-entry-content">
<p>Lorem ipsum...</p>
</div>
</li>
</ol>

How does the response get assembled? *not how to fill in the content
of the templates* I understand how to replace the placeholder content
based on the page structure, IDs, and classes. I would use Plates's
way to get to the #blog-entries>li[role='template'] to use as an blog
entry template and fill in the replaceable parts with plates way of
selecting page elements and attributes, repeating for each blog entry
on the page and return that wrapped in the <ol id="blog-entries"/> to
the wrapper template's div#page-content. (I would actually break the
above blog-entries out into several sub-sub-templates.)

If I am understanding correctly, I need to load those two files from
the file system in my custom code based on some convention of my own
making. Those files need to be read into strings. I would need to
cache the strings for the two templates, checking for file changes in
a dev environment and provide a way to clear that cache in a
production environment in my custom code. Then I would need to
determine the appropriate headers to send along with the assembled
string (probably setting up a caching system for that fully
assembled/transformed/rendered page).

Did that make sense? Am I missing any conveniences flatiron provides
along the way so I don't have to come up with all the custom code?

Thanks,
-Rob

[jesusabdullah]

Hi Rob,

> Did that make sense? Am I missing any conveniences flatiron provides
> along the way so I don't have to come up with all the custom code?

I don't think you're missing anything, no. You may have noticed that
in another thread on this list we've been talking about building this
out; it may interest you.

--Josh

On Feb 12, 6:28 pm, Rob Koberg <r...@koberg.com> wrote:

[Rob Koberg]

On Mon, Feb 13, 2012 at 7:01 PM, jesusabdullah <josh.h...@gmail.com> wrote:
> Hi Rob,
>
>> Did that make sense? Am I missing any conveniences flatiron provides
>> along the way so I don't have to come up with all the custom code?
>
> I don't think you're missing anything, no. You may have noticed that
> in another thread on this list we've been talking about building this
> out; it may interest you.

I am following it with interest :)

best,
-Rob