DiasporaJS refactor

[Dan Hansen (ohaibbq)]

Hey everyone,
recently I've been working on rewriting a bunch of our javascript and
I wanted to get some feedback from you guys. There were many problems
we had recently noticed with our old 'widget' system. I took a stab at
trying to fix these issues.

Problems with the old widget system:
- Widgets were singletons
- Widgets weren't helping us clean up the codebase, we still ended
up throwing javascript in some file in a document ready callback
- Widgets weren't helping us separate business logic from DOM
manipulation


Here is our plan for the new DiasporaJS:

Page classes handle what widgets need to be instantiated on that page.

Widgets are javascript classes (functions that you construct) that are
tightly coupled to a small piece of markup.

Widgets subscribe to a widget/ready event with a callback that takes
an event and all of the arguments you pass it. e.g. I can instantiate
a StreamElement widget and give it a jQuery object. It can do whatever
it needs to do to the jQuery object

Widgets can instantiate other widgets. e.g. a Stream widget can
instantiate many StreamElement widgets

Widgets have both local events (these are only triggered and bound to
by a widget instance) and global events (these are bound on an
instance of a page class and can be used in any widget with the
globalSubscribe/globalPublish methods).

Our code needs to be able to be understood by newcomers to the
project. I feel like what I'm working towards won't be too magical
that people won't understand it.

I feel like this is still a work in progress and our community can
help make it even better. Thoughts about all of this?
Dan

[Tom Scott]

I would love to help out with this. What is your plan of action? As in, which widgets are you reforming first, so I can work on other ones?

-T

[Dan Hansen (ohaibbq)]

Hi Tom, we're current on the branch "js-refactor-merged". We have
about 7 failing cucumber tests left before we're going to merge into
master. Our plan is to fix those tests and get this merged as soon as
possible. All the widgets have been rewritten. What I feel like we
really need right now is to go through our old js and find things that
can be made widgets. Just providing a list of widgets we could be make
would be super helpful.

Thanks,
Dan

[Amirouche Boubekki]

Hi Dan,

Is there a gentle introduction to DiasporaJS that can answer the following questions or maybe you can git it a try ;)

 - which libraries do you use ?

The other questions might be answered by the first but then if you use custom code it's not clear so the remaining questions might get their own answers:

 - Which pattern do you use MVC or something more custom ? From the description it looks like it's widget centered. But do evey widget have to pull their data from the server ? or data retrieval is managed by a custom class maybe with a single API for ressource description.
 - Do you plan to do a signle page mode for Diaspora ? If yes, how is it reflected in the client side code architecture.

More questions (where I try to build a conversation...)

Page classes handle what widgets need to be instantiated on that page.

Could you enumerate the page Classes ?
 

Widgets are javascript classes (functions that you construct) that are
tightly coupled to a small piece of markup.

Is it template based, classic DOM construction, or something in between like what can be achieve with an API like HTMLBuilder [1] or lxml E factory [3]. I heard of JS based language that does the same, can't find it right now.

e.g. I can instantiate
a StreamElement widget and give it a jQuery object. It can do whatever
it needs to do to the jQuery object

This is inheritance or I'm missing something ?
 

Widgets can instantiate other widgets. e.g. a Stream widget can
instantiate many StreamElement widgets

 
You are spawning widget in cascade, is that it ? Won't be that too hard to read in code perspective ? I'm not used to all the callback stuff, but maybe this is regular UI construction in JS.

Same question as above about resources. If we take the Stream widget, does it take the a list of StreamElementData or does it have a way to pull at the right time the data it needs.
 

Widgets have both local events (these are only triggered and bound to
by a widget instance) and global events (these are bound on an
instance of a page class and can be used in any widget with the
globalSubscribe/globalPublish methods).

How do you manage publish/subscribe|events, with Jquery mechanics ? Or something else ?
 

Our code needs to be able to be understood by newcomers to the
project. I feel like what I'm working towards won't be too magical
that people won't understand it.

Good point.

Amirouche

[1] Flask-htmlbuilder pypi page http://goo.gl/3Rh0o
[2] E-factory documentation on lxml website http://goo.gl/VzD9b (buggy right now try google cache: http://goo.gl/zkqH3

[Dan Hansen]

Sorry about the late reply. I've been super busy.

 Is there a gentle introduction to DiasporaJS that can answer the following
 questions or maybe you can git it a try ;)
 
  - which libraries do you use ?

DiasporaJS just uses jQuery

 The other questions might be answered by the first but then if you use
 custom code it's not clear so the remaining questions might get their own
 answers:
 
  - Which pattern do you use MVC or something more custom ? From the
 description it looks like it's widget centered. But do evey widget have to
 pull their data from the server ? or data retrieval is managed by a custom
 class maybe with a single API for ressource description.

As of right now all widgets are for are adding functionality to an element somewhere in the DOM.

  - Do you plan to do a signle page mode for Diaspora ? If yes, how is it
 reflected in the client side code architecture.

I'm not sure about this.

 More questions (where I try to build a conversation...)
 
 Page classes handle what widgets need to be instantiated on that page.
 Could you enumerate the page Classes ?

Here's an example page:

Diaspora.Pages.ContactsIndex = function() {
  var self = this;
  this.subscribe("page/ready", function(evt, document) {
    self.instantiate("Header", document.find("header"));
    self.hoverCard = self.instantiate("HoverCard", document.find("#hovercard"));
    self.infiniteScroll = self.instantiate("InfiniteScroll");
    self.timeAgo = self.instantiate("TimeAgo", "abbr.timeago");
    self.directionDetector = self.instantiate("DirectionDetector");
    self.flashMessages = self.instantiate("FlashMessages");
  });
};

All the page class is doing is saying "I need these widgets in order for my page to work, so let's instantiate them"

 > Widgets are javascript classes (functions that you construct) that are
 > tightly coupled to a small piece of markup.
 
 Is it template based, classic DOM construction, or something in between like
 what can be achieve with an API like HTMLBuilder [1] or lxml E factory [3].
 I heard of JS based language that does the same, can't find it right now.

As I said before, right now, widgets just add functionality to elements that are in the DOM when you load the page.

  

 e.g. I can instantiate
 

  a StreamElement widget and give it a jQuery object. It can do whatever
  it needs to do to the jQuery object
 

 This is inheritance or I'm missing something ?

 

 Widgets can instantiate other widgets. e.g. a Stream widget can
 instantiate many StreamElement widgets

 
 You are spawning widget in cascade, is that it ? Won't be that too hard to
 read in code perspective ? I'm not used to all the callback stuff, but maybe
 this is regular UI construction in JS.

I don't think so all we do to instantiate a widget inside of a widget we just go:

this.widgetName = this.instantiate("WidgetName", $(".widget-name"));

 Same question as above about resources. If we take the Stream widget, does
 it take the a list of StreamElementData or does it have a way to pull at the
 right time the data it needs.

Let's say we have the following markup:

<div id="main_stream">
  <div class="stream_element"></div>
  <div class="stream_element"></div>
</div>

The stream widget will be instantiated with a jQuery object containing the main stream div. Inside of the widget/ready event in the stream widget we find all the divs with the class "stream_element" and instantiate widgets for them.

 How do you manage publish/subscribe|events, with Jquery mechanics ? Or
 something else ?

Yes, we just bind/trigger events on a jQuery object.

Once again sorry about the late reply, I arrived back in Iowa from California a few days ago and have been busy.

Thanks,

Dan