Abstract out the actual mercury editor

[balupton]

Really the mercury editor should be it's own project, and be included as a submodule or something into the rails cms.

[jejacks0n]

I agree entirely, but this isn't on the roadmap just yet.. During the heavy development phase it will likely stay within the rails project -- but I do plan to add a build task that will compile the coffeescripts into a release javascript.

[balupton]

I'm available on the weekend. Let's make this happen.

The most urgent thing is to get the mercury [coffee+java]script sub-moduled out into it's own project, once that is done then we or I can work right now into incorporating it into other backends as forks or whatever.

Until it's submoduled, contributors and implementors hands are tied.

[jejacks0n]

After talking this over with some colleagues we decided that the best approach, for now, is to create a build task that builds the javascript and css (toolbar images will be data encoded into the css), and provide that as a download from github and the demo site. To help others build out the back end functionality in whatever language/framework they'd like we'll write up a spec of what the javascript is expecting.

[jejacks0n]

Until it's submoduled, contributors and implementors hands are tied.

Too true. I did add some build tasks and a distro package (that can be downloaded from the project now), and updated the installation docs to reflect this. I know it's not exactly what you're looking for just yet, but it'll give us a good starting point.

I've got the kids this weekend, so I don't know how much time I'll have to dedicate with you, but you can try out the distro and give it a first pass and let me know how it goes. Just download the zip from github and grab the distro.html from /public (also where the distro files are built) and you can have a go at it. I'm interested to hear your thoughts about this approach, understanding that after development slows we'll consider other options like a submodule etc.

PS. The snippet features won't work with the distro, but I think the image handling and snippet interfaces can be specified on the wiki, as I believe they're the only things that truly need a back end (besides save of course).

Seriously, I really appreciate the help! =)

[balupton]

Cheers, the distro copy works beautifully! :)

Though without that submodule, my hands are still tied if I would like to make modifications to the code - knowing that if I do want to do so properly I would have to fork the mercury project as is with rails etc.

The only difficulty that I see with the current structure is the way mercury is handled as an asset: https://github.com/jejacks0n/mercury/tree/master/app/assets

The directory structure would have to have the following changes:

• app/assets/stylesheets/mercury/ -> vendor/mercury/stylesheets/
• app/assets/javascripts/mercury/ -> vendor/mercury/javascripts/
• app/assets/images/mercury/ -> vendor/mercury/images/

With vendor/mercury being the submodule.

In regards to compiling the project for distribution for me this is a non issue as different backends would want to load mercury differently. For instance, perhaps instead of pre-compiling the coffeescript into javascript, that can be handled on the fly by including coffee-script.js in the browser, or by rendering .coffee files as javascript server-side.

For instance with the submodule in place, I'd happily provide and be able to provide a node.js backend which implements it, as well as a plain static .html file which includes the coffee-script rendering client side.

Thoughts? And thank you a lot for the efforts too, the appreciation goes both ways :)

[jejacks0n]

Yep.. I'm about to head out for the evening, but I'm starting to agree with you. Your points are valid and well taken.

The idea of using the coffee-script.js is interesting and a great suggestion, though I'd prefer to have it broken out such that this wouldn't be needed -- but primarily because I don't know what the performance hit might be.

I haven't seen this problem being approached by very many projects yet. I know ruby and that toolset well, but I'd have to say that node seems like it might be a better option for the submodule bit, just because it may have a simpler project structure. Let me check out some node stuff tomorrow and I'll try and meet up with you on sunday. I may try to setup a little stub project in both node and ruby to see what feels best there.

Also, I added a wiki page for server integration points: https://github.com/jejacks0n/mercury/wiki/Server-Specification

[jejacks0n]

which would you prefer? node, or ruby?

[balupton]

Node

[balupton]

I decided I couldn't really wait, and went ahead and started work on abstracting mercury out of the rails project. You can follow its progress on this branch: https://github.com/balupton/mercury/tree/dev-abstract

[jejacks0n]

That's great man, thanks for the help! I'll check out what you're doing and work it in when you have something for it. If you have any questions about how the project is using the rails asset stack let me know -- I will be doing a little work today, but it'll all be pretty light.

[balupton]

I've been able to make progress but could do with your help (I've added you as a collaborator for my fork):

git clone git@github.com:balupton/mercury.git
cd mercury
git checkout dev-abstract
cd vendor/mercury
npm install -g simple-server
sise

Then open: http://localhost:3000/src/demo/

For some reason the styling is messed up - it looks like there are two content areas with one ontop of the other.

You can find the current status here: https://github.com/balupton/mercury/blob/dev-abstract/vendor/mercury/TODO.md

[jejacks0n]

Nice man! I didn't realize you'd done that much already. I took a look at this and it was a pretty simple adjustment, but there's a few things I should mention because the load order is a little off.

You probably already know this, but I'm making this a brain dump and I may use it for some documentation later.

Mercury uses an iframe to load the page that you want to edit, and this choice was made to provide the least impact possible to the document that it's editing (but it can also be a bit of a pain). I added a loader script that does a lot of this work, so you should check the mercury_loader.js file because that's where a lot of how we make this feel seamless is hidden away, and here's a quick rundown of what happens.

1. A request is made to a document that includes the mercury loader.
2. The loader determines if it should include mercury scripts and css:
   • If the window is the top window then before the document has time to display we clear it's contents and remove all the styles that have been defined thus far. Then we add in the mercury css and javascript and instantiate a new PageEditor , which builds the iframe, toolbars etc. Building the iframe loads the document again, but this time Mercury isn't loaded.
   • If the window is not the top we fire an event to tell Mercury that the iframe document has loaded so it can initialize the regions before the user sees anything (this avoids load delays with tracking scripts and large images etc).

I should mention that this hasn't been entirely tested in real world conditions, so there could be issues with this, but I don't think they're deal breakers and may just require some tweaks to the loader.

So, the issue you're seeing is primarily because the load order is happening a little differently than expected.. instead of loading all the dependencies and mercury on request, it should only happen if the window is the top, so that way it does all the parsing after you've already hidden the document and cleaned the css -- instead of the other way around. Does that all make sense? And then on the second request (the iframe load) we don't load anything, which keeps the load time down and performance better.

Seriously, I'm absolutely impressed by what you've done. I'll definitely help out with this aspect when I get some more time -- I've been focusing on some other things at work the past few days, which means I don't get to work on this stuff.

Cheers!

[balupton]

Mercury uses an iframe to load the page that you want to edit, and this choice was made to provide the least impact possible to the document that it's editing (but it can also be a bit of a pain). I added a loader script that does a lot of this work, so you should check the mercury_loader.js file because that's where a lot of how we make this feel seamless is hidden away, and here's a quick rundown of what happens.

Yeah... that iFrame would kinda make using mercury for inline editing more or less impossible. So how hard would it be for me to remove that iFrame? Can you provide some steps?

Pretty much my goal is to get the abstraction done by/on Thursday.

Also thanks a lot for the feedback, definitely do appreciate it :) You've done some really great work.

[jejacks0n]

Yeah... that iFrame would kinda make using mercury for inline editing more or less impossible. So how hard would it be for me to remove that iFrame? Can you provide some steps?

Actually no, it handles inline editing just fine, and works nicely. I'm a bit confused why you disagree with the architectural choice because it's actually nicer this way.

As far as changing it, I'd ask that you don't, but if you'd like to write an alternative you could inherit from PageEditor and not build the iframe, instead using the current document. But again, I've made this choice specifically because I don't want CSS or JavaScript pollution in the projects it's used on.

[balupton]

Actually no, it handles inline editing just fine, and works nicely. I'm a bit confused why you disagree with the architectural choice because it's actually nicer this way.

No worries, so would it still work say if I have an item page, and I want to have the item's content and description as contenteditables if the user is the owner of the item? As it seems the iframe would only benefit an editing the entire page type thing, rather than particular fields.

Perhaps we could make the iframe an option? So you can either have it or not.

I don't want CSS or JavaScript pollution in the projects it's used on.

Why would their be pollution? You can namespace the CSS and the JavaScript can be loaded once and stays in the background?

Please let me know if any of my thinking is incorrect :) Happy to understand this better :) If you're on Skype we could have a call - I'll be on for the next 5 hours or so, except for one of those hours I'll be in another call.

[balupton]

Alright.

Latest news:

1. vendor/mercury is now root, this means that the rails setup should be pulled from the original repository, then pushed into a new repository called mercury-rails
2. Using an iframe is now optional via Mercury.config.useIframe
3. dev-abstract is now the default branch on my fork, so you can just go here: https://github.com/balupton/mercury
4. Rails project found here: https://github.com/balupton/mercury-rails - this will be updated for the abstraction changes

[gvarela]

Having had first hand experience working with Jeremy on the Midas version of this editor concept, I can say that the iframe is a must. It is impossible to completely namespace all the css / js in both the editor and the site in a way where there is no pollution. The iframe solves this completely and you no longer have to worry about whether the css / js is namespaced, freeing you from that concern.

[balupton]

Thanks guys, I definitely can see the good points of an iframe configuration.

Though it does have its bad points:

• Some websites just won't work inside iframes
• Some HTML5 features don't play nice with iframes - such as the HTML5 History API
• Ajax navigation based websites and RIAs won't play well - as bookmarking a page can't be done anymore
• Adblockers sometimes like to block iframes
• Debugging the the page isn't as straightforward as it was, instead you have to debug the iframe

In fact, no-iframes is one of the major driving points of Aloha Editor, and the big thing which is getting people to move to it from iframe editors.

I'm really happy keeping the iframe in there, but I do believe the ability not to use the iframe should be left in there too.

[jejacks0n]

I agree.. and it will be merged in, so thanks for that.. =) Instead of adding it to the configuration though, it might be pretty easy to inherit from PageEditor (let's say an InlineEditor class), and just change the parts that build and load the iframe. When I merge it in I may investigate this -- because I plan to build other controllers like "RegionEditor" for single regions where the toolbar is attached to each region (like TinyMCE for instance), and something potentially that creates a floating toolbar like in Aloha Editor -- my point being that there may eventually be one base controller, that all of these inherit from, and PageEditor would just be one of those.

[balupton]

Interesting idea :)

[balupton]

Hey guys - made massive progress today and merged dev-abstract into master on my fork.

You can get it up and running, compiled (out) and source (src) versions by following the instructions included here: https://github.com/balupton/mercury

I've also added support for local file drag and drop, so it doesn't need to upload to the server if you don't want it to.

[lvanderree]

Great work guys!

I am integrating a contenteditable editor in Django - FeinCMS, and I think Mercury is currently the best edtior available. The work you have done to make it independed from Rails is greatly appreciated, first things are starting to work...

I was first using aloha first, but didn't like it for several reasons (jumpy pop-up, image plugin hard to use, no way to see the html in the edtior, no way to apply styles, build process broken). Currently I am looking at Mercury and even though this isn't finished either, it suits my needs much better!

I am first trying out some stuff locally, but am willing to join the development process

[jejacks0n]

Thanks for the kind words Leon. We're always happy to have someone willing to contribute or help identify issues integrating with other frameworks.

[lvanderree]

I am working on creating a community of Django-FeinCMS and Mercury users, it looks like the main-developer of FeinCMS is liking the idea as well: https://groups.google.com/group/django-feincms/browse_thread/thread/9db5707478a012a2

I will keep you posted!

[JeanMertz]

wow, massive confusion after reading this issue.

So which "mercury" repository is the "main" one to use? This one by @jejacks0n seems to be the first, but the one by @balupton seems to be more bare-bone (which I like) and offers the ability to not use iframes (which I like even more). Although development on the @balupton fork seems to have slowed down lately.

Any thoughts on this? The readme doesn't mention anything of this, and the readme of @balupton seems almost identical, so I couldn't gather any information from there either.

[jejacks0n]

Yes, this is the primary one. You can always see that from the fork graph.

And yes, balupton did some pretty cool stuff with it. I'm not sure that no iframe thing is true though -- it seemed like he stopped before getting it fully working (bugfixes etc)

I'd say give his fork a try though, I could be wrong, and it would help me know. :).

On Sep 29, 2011, at 3:49 AM, Jean Mertzreply@reply.github.com wrote:

wow, massive confusion after reading this issue.

So which "mercury" repository is the "main" one to use? This one by @jejacks0n seems to be the first, but the one by @balupton seems to be more bare-bone (which I like) and offers the ability to not use iframes (which I like even more).

Any thoughts on this? The readme doesn't mention anything of this, and the readme of @balupton seems almost identical, so I couldn't gather any information from there either.

Reply to this email directly or view it on GitHub: https://github.com/jejacks0n/mercury/issues/4#issuecomment-2236088

[benneq]

Any progress in here? The iframe thing sucks!

1. If I click 'Edit' somewhere the whole page has to reload because of the iframe
2. The iframe will stay everywhere, because I use lots of "remote: true" in my links
3. If I try to edit multiple pages, each page creates its own iframe. At the end I have 3 or 4 Mercury Editor panels at the top of my browser.

Is there any way to make it suck less?

[jejacks0n]

You're using it wrong, and don't understand the problems that the architecture solves.

And you're rude.

On Apr 10, 2012, at 6:56 AM, benneqreply@reply.github.com wrote:

Any progress in here? The iframe thing sucks!

1. If I click 'Edit' somewhere the whole page has to reload because of the iframe
2. The iframe will stay everywhere, because I use lots of "remote: true" in my links
3. If I try to edit multiple pages, each page creates its own iframe. At the end I have 3 or 4 Mercury Editor panels at the top of my browser.

Is there any way to make it suck less?

---

Reply to this email directly or view it on GitHub: https://github.com/jejacks0n/mercury/issues/4#issuecomment-5045053

[benneq]

I'm sorry, had a really bad day...

Let's try it again: What's the right way of using it? Suggestions:

1. Is my application supposed to have the mercury editor always running and the real application only runs inside the iframe?
2. Is there a way to disable the iframe thing and load Mercury on demand?
3. Something else...

And: I'm really sorry for my last post...

[gvarela]

It really depends on your use case. Mercury isn't trying to be a CMS. It is an editing tool that you can use however you like. The iframe is required as otherwise the css and js cross pollute between the site and Mercury.

[benneq]

Ok, then it must be possible to hide and show the Mercury Editor via JavaScript? I mean just the panel at the top and disable the highlighting of the fields of course

[gvarela]

Open: window.location.href = '/editor' + window.location.pathname

Close: window.location.href = window.location.pathname.replace('/editor','')

[benneq]

As I said above I have lot's of "remote: true" links. So is it possible to hide the Mercury Editor panel, when no 'editable' field is present?

The function calls you wrote reload the whole page. That's the point I'd like to avoid. Or may I have to switch to Aloha Editor?

[jejacks0n]

Thanks for the apology.

Ok, so we don't spam everyone else in this issue how about you create a new issue "Usage questions" or something and I'll take some time to try and walk you through it.

[sopitz]

sorry for warming this old issue up again but i'd really be interested in leaving out the iframe even tho I read all the arguments FOR this approach (and i kinda like it, it just doesnt fit my needs). can you give me a hint how I could go for that without rewriting too much of the code?

[gvarela]

It's not possible in the current version without a major re-write. @jejacks0n is in the process of re-writing Mercury and is going to attempt to make Mercury not require the iFrame but, there are no guarantees as it really does cause a lot of problems with how the application that is using Mercury is implemented. Without the sandbox of the iFrame it is really easy to shoot yourself in the foot. And this isn't just speculation as everytime @jejacks0n has re-written this editor he tries the non-iFrame approach and ends up abandoning it because of issues it causes.

[sopitz]

i totally understand that. but i'd make mercury a core part of my personal cms and therefore should be able to handle the css/js issues. but when @jejacks0n is already working on a new version i'll just wait for that and see how things turn out. btw @jejacks0n: good job! that editor is by far better than anything else out there!

[jejacks0n]

Cheers!

---

Jeremy Jackson

On Mar 13, 2013, at 11:21 AM, sopitz notifications@github.com wrote:

i totally understand that. but i'd make mercury a core part of my personal cms and therefore should be able to handle the css/js issues. but when @jejacks0n is already working on a new version i'll just wait for that and see how things turn out. btw @jejacks0n: good job! that editor is by far better than anything else out there!

— Reply to this email directly or view it on GitHub.

[pasupulaphani]

Hi All,

This is one of the amazing tool I use for in context editing for rails apps. But when I tried to integrate with node it is a bit of mess. Any plans in making mercury an easy integrate-able module irrespective of framework ?

Phani