| Re: [orion-dev] Observations on adding a new page / 'components' to Orion |
Ideally we'd have a wiki page talking about our page structure, but since we don't, please forgive a long email response which is my attempt to summarize our state.
I think there are a bunch of different issues we want to fix that are at play here, and to a newcomer it just looks like a huge wad of modules. They don't really differentiate themselves by their role. I also think the editor is kind of a "worst case" view of the world because it's the most complex page we have, and we have two versions of the editor page (normal and read only), so much of what we normally call "glue" code is in a separate common module (setup.js).
I would point a new Orion developer at a much, much simpler page to start with, such as sites.js or content.js. (We should have a sample page that just puts the common pieces together and has "YOUR CONTENT GOES HERE" ! ) But even with a simpler page, we have a number of issues we are concurrently working to improve:
1 - we've never come up with a "template" story for the common parts of the page, so we currently add common parts dynamically using a template fragment in one of the modules. So you can't even tell at a glance where the banner and footer comes from, because some module somewhere supplies the js (generateBanner) to get a banner. Contrast that to server side includes where we'd just construct the common parts before the page was ever served up. [1]
2 - our bootstrap code is repeated all over the place in our "glue" code. We know this is not smart, but we've never tried to solve it. As far as I know, we still don't really have a formal story for how the services are instantiated and passed into the components that need them. Ideally components could say what services they need to be on the page, but we don't have that story yet. [2]
3 - we don't have a consistent fragment/template story for our widgets, so things look pretty different depending on who wrote the code. Some folks prefer heavy dijit usage (that is going to change) and so you have HTML templating, typically in separate files. Our internal web components tend to define HTML fragments/templates either in their JS file (using a string that is parsed and dynamically inserted, much like the banner), or by calling a bunch of DOM manipulation code on the fly. The latter is hard to follow, but sometimes necessary:
a) we need to bind the i18n strings somewhere (it's not just text in a template).
b) if we are inserting any strings from plugins (which includes message catalogs) we can't just concatenate them in a template and parse as HTML. We have to use dom manipulation and things like setting text content of a node. This prevents scripts from being maliciously inserted into the DOM via a plugin "string." [3].
There is definitely room for discussing our state of the art and making things more consistent. We want to track other efforts w3c components, etc. and make sure that whatever we do models advances made in the browser. We definitely *do not* want to grow a framework. We want as much HTML/CSS to drive the behavior as possible and tack on js to manage more dynamic behaviors.
4 - our directory structure and naming does absolutely nothing to help with all the gobs of modules. It's relatively easy to find "glue code" by looking at the URL of the page in question and looking for the matching *.css, *.js, *.html. But beyond that, there are tons of modules, some are "plain UI widgets" with not much orion semantics (splitter, treetable, dropdown, tooltip, etc.), some represent "a box on a page" (outliner, navoutliner, task list, etc...), some are "utility methods," some are just a wad of code moved from a page, etc. etc. I know Szymon is trying to clean up the need for OSGi bundle directories on the client side, but I think we also need to look at fixing the directory structure beyond that and assigning some directories based on the role of the various modules...(utils go in one place, widgets somewhere else, higher level components elsewhere, etc.)
5. - we don't organize our CSS by visual component, so having the matching CSS file for a visual component as shown in your picture is not something we do consistently. But moving raw CSS around doesn't make a lot of sense vs. moving to LESS and having module-based LESS files that generate into common CSS.
It all adds up to be confusing to a new Orion developer, and we've never really documented the concepts like "glue code" vs. "components" though they are part of the vocabulary of the team. A good step besides an example page might be to draw a picture of what we have now so a new person would know where to look. Note this really applies to those developing Orion itself, not plugins. Plugins don't have to know about any of this, they have to know the API (with its own set of issues) and otherwise can create their own pages any way they wish.
The removal of dojo/dijit is changing a lot of what happens for #3, Szymon is working on #4, and I think you (Anton) are going to do some work on #5. I also know that Simon is working on a templating story that could help with #1. I really wish we'd address #2 but it's not bubbled up in the priority scheme yet.
To me, the best thing would be to create a sample simple page so one wouldn't be overwhelmed by the editor and then document the state of the world post 2.0 to help new Orion developers know where to look for stuff. I don't suggest a lot of effort to document before that because it's all in such flux.
susan
[1] https://bugs.eclipse.org/bugs/show_bug.cgi?id=334907
[2] https://bugs.eclipse.org/bugs/show_bug.cgi?id=337740
[3] https://bugs.eclipse.org/bugs/show_bug.cgi?id=392469 and https://bugs.eclipse.org/bugs/show_bug.cgi?id=387831
Anton McConville ---12/19/2012 09:59:39 AM---Hi, I started work on adding a new Projects page yesterday ( more details
From: Anton McConville <Anton.McConville@xxxxxxxxxx>
To: orion-dev@xxxxxxxxxxx
Date: 12/19/2012 09:59 AM
Subject: [orion-dev] Observations on adding a new page / 'components' to Orion
Sent by: orion-dev-bounces@xxxxxxxxxxx
