[meta] Convert the API site to Backdrop

[quicksketch]

I'd like to get the API site upgraded to Backdrop ASAP, and give it a theme-refresh at the same time. Considering the shabby appearance of the site, I'd like to get this one upgraded with priority greater than the flagship site (see backdrop-ops/backdropcms.org#38).

Fortunately the number of modules needed on the API site are fairly limited:

• Code filter
• API
• BUEditor (or similar)

[quicksketch]

I ported CodeFilter a few days ago: https://github.com/backdrop-contrib/codefilter

And I've got a very good start on API module.

@sirkitree ported CodeMirror, which might be a nice addition if we're going to be typing a lot of HTML by hand: https://github.com/backdrop-contrib/codemirror

[docwilmot]

I'd like to get the API site upgraded to Backdrop ASAP

Fantastic news. Will work on BUE then.

[docwilmot]

https://github.com/docwilmot/bueditor

[quicksketch]

❤️

That's excellent. I'll start working on the API site itself this weekend. I don't think it's going to take long to do the conversion.

[quicksketch]

I have API working to the point that it's functionally complete (https://github.com/backdrop-contrib/api). I didn't build in an upgrade path, but for something like this, I think we'll be okay. I'll work on building this out locally with all the pieces.

[quicksketch]

I think we're good enough for starters here, and it's going to be better than our current API site just with the fixes to Code Filter. I'm going to work on putting this up.

@docwilmot, have you made any documentation changes in the past oh, 36 hours? It'd be easiest if I didn't have to re-run the upgrade path again.

[docwilmot]

Nope, go for it.

[quicksketch]

Initial site is up now at https://new-api.backdropcms.org/

@docwilmot, could you give it a spin?

[sirkitree]

This looks really nice. Tested out hook_form_alter in the search, checked out the change records and it's dropdown and search (all working), check out some links.

Generally, code blocks look a little funny.

vs

or

vs

And sometimes nothing at all:

vs

[quicksketch]

Thanks @sirkitree! That inconsistent formatting is something I'll take a look at. It might just be a text format configuration issue.

[quicksketch]

Gar, I hadn't uploaded the codefilter.module in the Git repo. That would cause a problem. 😉

It should look much better now. 😄

[sirkitree]

OMG so much better!

[docwilmot]

This is beautiful!
Tested node edit, add, menu. Everything works. Well done!

[quicksketch]

Excellent! I'll retire the old API site later this evening.

I'd like to work on making the search more effective by unifying the function/class/file search with the normal site-search, so we could mix together content-based documentation with phpdoc-based documentation, but we can handle that after the initial launch.

[docwilmot]

When you get to fixing search, #8 still happens.
I also ported IMCE today so we can have diagrams in the docs. Please give that a spin for me.

[docwilmot]

And a vote for converting the main site to the same/similar theme. A nice image splash on the front page maybe, but this would work for me.

[quicksketch]

And a vote for converting the main site to the same/similar theme.

Ha! The new theme is actually Bartik, with a black background and no primary navigation (so no "tab" links at the top). But I do think it looks nice as well. I also expanded the maximum width to help prevent lines of code from shooting off to the side. It's now the same max-width (approximately) as php.net.

Flipped over the site. I can put up the old site if needed again in the future, but for now we don't have a subdomain pointing to it (though it is still on the server).

When you get to fixing search, #8 still happens.

I'll look into that.

I also ported IMCE today so we can have diagrams in the docs. Please give that a spin for me.

I'm not really a fan of IMCE because it doesn't do any kind of association between files and the nodes that use them. I also don't like it's behavior of saving into per-user directories (though that can be changed). Let's talk about possible options in a followup issue.

[cellear]

@quicksketch: You probably know this, because you're probably doing this, but both api.backdropcms.org and new-api.backdropcms.org are down at the moment. Looks like an apache misconfiguration? It's downloading index.php rather than executing it.

[quicksketch]

Hi @cellear! Yes, sorry I broke things pretty bad in futzing with nginx configs. It should be back up now. Sorry about that!

[cellear]

I think we need the API navigation block back; without it, there's no way to browse the api docs.

(I'm happy to make changes rather than just suggest them, but I've been out of the kitchen for a bit, and I'm not certain what's cooking.)

[docwilmot]

I'm not really a fan of IMCE

Too bad. I should have mentioned it before starting. I like IMCE though. What media browser would be your preference?

[quicksketch]

I think we need the API navigation block back; without it, there's no way to browse the api docs.

Let's just add the links that are needed directly in the main navigation block for now.

What media browser would be your preference?

@herbdool ported Insert module (https://github.com/backdrop-contrib/insert) that is a simple tool for using the built-in file fields to insert images/files. Would that work? It doesn't have a file browser unless you combine it with File Field Sources (which ironically integrates with IMCE).

[docwilmot]

Not familiar with Insert, but I guess all we need is some way to get images uploaded and inline, sounds about right.
But I was actually curious about your personal preference. You dont like file browsers generally or just IMCE?

[quicksketch]

I think file browsers in general are important and useful. The only thing I don't like about IMCE is it doesn't maintain any kind of relationship between images and the content that uses them. So if you upload a file but never use it, it just hangs out on the server forever. If you upload an image for one piece of content, but then later delete that content, the images aren't deleted along with it. IMCE also doesn't handle private content, or content that isn't hosted locally (e.g. S3). Also worrisome, IMCE allows you to delete or manipulate files that are in use by other pieces of content, but since it doesn't keep track of which content uses what files, you'd have no way of knowing that.

However, all that said, I know people like IMCE because it works and it's easy. I worry about it because it's sloppy file management and is usually too permissive.

The Drupal 8 implementation of CKEditor includes inline uploading of files (one of the last things I wrote before Backdrop). The file references are then maintained with data attributes in the markup. That allows for private file access and proper cleanup of unused files or deleted content. Long-term, instead of having a file-system based browser, the plan is to use a View-based browser, like the content administration, to organize and find files.

[quicksketch]

Ah, and it's not clear from the above, the "Upload" dialog in D8 is powered by the dialog API, so it's a Drupal-provided dialog to upload (and eventually browse) images. That's one of the reasons we made sure to include dialogs in Backdrop, because it sets us up for file management in WYSIWYG in 1.1.x.

[docwilmot]

Good points all, hadnt thought of that. Thanks.

[docwilmot]

Let's just add the links that are needed directly in the main navigation block for now.

Done, but
https://api.backdropcms.org/api/backdrop/files needs some CSS help. The table is too wide to fit.