oui_flat (rah_flat fork) - Manage templates and prefs as flat files

Destry · 2016-12-21 10:37:19

NicolasGraph wrote #303328:

For these subfolders you can use native and/or custom form types as names.

Thanks. That is what I’ve since discovered. And defaulting to “misc” forms on a revert/off situation for any ‘custom’ named forms makes sense.

Destry · 2016-12-21 14:14:59

bici wrote #303321:

@destry I hope you get it working. And can use your editorial skills to document the process.

I got it working. The confusion, I think, probably comes from people having their own way of tackling the flat-file process (e.g. use different plugins, want different things, etc) so it gets confusing to follow instructions if you’re basing it on the this info and that from here and there.

Following is the nutshell of my attack. With these steps you won’t even need to read the plugin docs:

First, install and activate these two plugins: jcr_export_txp_templates and rah-flat. (I recommend these because they are the latest and actively supported.)

jcr plugin:

In your Txp installation directory, create a new folder called templates. Then create another folder inside that one called export — i.e. ../templates/export. (This is where the jcr plugin will export its initial templates to.)
chmod the export folder (755, 777, whatever you need to do).
In admin-side, go to Extensions > Export templates and hit the Export button. No need to add a name in the field. Your templates will land in /templates/export organized as follows:

- forms
- pages
- plugins
- sections
- styles
- variables

I don’t currently use the resulting plugins , variables , or styles directories, so I immediately delete these three folders. If you need or want them, that’s your homework. I explain styles below.

Also, the forms folder will contain all your forms in batch. You can tell what type they are by the name. You’re going to manually move the types into their own subfolders, but we’ll come back to that shortly.

(oui) rah plugin:

First, decide how you want to structure your templates in your Txp install tree and then create those folders. This is a subjective affair, of course, but I’ll show you how I do it as example… I actually don’t like using the term “templates”, because not all of those flat files are templates, technically speaking. I also prefer using external CSS files, as they don’t require being ‘sucked up’ by the CMS after changes. At the same time, I don’t want multiple extra directories in my root install, so I use a single parent directory (custom) for all static/flat files and split things from there…

custom
- css
- flatfiles
- js

In this case the target flat-file directory is: ../custom/flatfiles.

Now, copy the pages, sections, and forms directories from the jcr export folder over to the flat-file container you decide on. For me this is called flatfiles, which helps me remember this folder works in relation to the rah_flat plugin. So I have this:

flatfiles
- pages
- forms
- sections

Now we switch focus to the forms folder. Within that are the entire set of form files exported by the jcr plugin. As mentioned earlier, you’re going to create subfolders for each form type and move the form files accordingly. And as Nicolas clarified, you can use Txp form type names for folders, make up your own, or use a combination of both. For the time being, I simply went with Txp’s own form type names because the site in question is new and I don’t have many forms yet. Thus my forms folder is structured like this:

forms
- article
- comment
- file
- link
- miscellaneous
- section

I don’t like the label, “miscellaneous”, because it’s not suggestive of anything, so I know I’ll eventually use other folders in place of that one with names like external-code, static-content, modules, widgets, or whatever. If I ever have to kill rah_flat after that for any reason, forms in those custom folders would just drop back into Txp’s miscellaneous type. No big deal.

At this point your form files should be organized into their respective type folders, and they have file names in this pattern: {name}.{type}.txp. If we focus on the article folder from the above branch, for example, files inside will look like:

article
- article_listing.article.txp
- default.article.txp
- …

Manually edit each file names in each type folder to remove the ‘type’ piece from the name, which is now designated by the name of the containing folder. For example:

article
- article_listing.txp
- default.txp
- …

Finally, in the admin-side of Txp, go to Admin > Preferences > Template files (rah_flat) and add the relative Template path to the parent flat-file folder. Again, my target path is ../custom/flatfiles.

I also chose “Debugging, Testing” for the upload status option, which seems like a better way to hedge the bets of sucking up. :)

As soon as you click Save, the new flat-file process initializes. At this point you’re using your favorite text editor for all things markup/code. Make sure by doing a test on one of your flat files while in Debug or Test mode and see what happens. It should work barring any external factor.

Clean up

There’s not much to clean up, but you probably won’t need the jcr_ plugin folders anymore, unless you used its templates folder as your parent for final flat-files too. If not…

Delete the templates directory (and contents) from the root install.
Deactivate the jcr plugin.

NicolasGraph · 2016-12-21 14:28:17

Destry wrote #303333:

[…] With these steps you won’t even need to read the plugin docs […]

Thanks Destry for sharing your workflow with these two plugins; they should probably fusionate one day…

Destry · 2016-12-21 15:19:37

NicolasGraph wrote #303334:

Thanks Destry for sharing your workflow with these two plugins; they should probably fusionate one day…

Agree, a fusion would be convenient, and wouldn’t need much change in workflow, except…

Instead of the export files going to a fixed location (i.e. /templates/export), the Extension panel controls should allow you at that point to designate whatever location you wanted, which then gives you a ready-made path to copy/paste into the rah_flat preferences when ready.

That would eliminate needing to clean up folders between the two plugins.

The user would still have to manually fiddle with the child folders and files a bit, but the plugins would be merged at that point. ;)

And make sure you change the name to oui_flat at that point, or oui_jcr_flat.

Bloke · 2016-12-21 15:35:21

I like all this stuff, but bear in mind that Themes are-a-comin’ so the process will differ from the above. You won’t need plugins to do it, unless you want your plugin repo under VCS management too (which, btw, you could do with the plugin cache setting in prefs).

Assuming I can get the import/export working reliably then you’ll be able to natively pull and push Theme bundles comprising Pages, Forms and Styles so you can apply them to your Sections as you see fit. There may be the ability to handle prefs too, but it depends on adoption of a patch by makss, which is awaiting ratification.

The core implementation of the file system follows the rah_flat methodology, except for having Form type first in the filename. And, of course, instead of a single folder for your template subdirectories, you’ll have one subfolder per theme, with your template subdirectories beneath each.

NicolasGraph: If you want to help out with the flat-file side of things in core, feel free to pull the themes branch down and let me know. I’ll then share the core flat-file code I have so far, which is currently uncommitted.

bici · 2016-12-21 19:12:14

NicolasGraph wrote #303334:

Thanks Destry for sharing your workflow with these two plugins; they should probably fusionate one day…

Thanks Destry and a vote for a FUSIONATE – lovely word i think

will be giving this a go once the holidays clear

phiw13 · 2016-12-22 00:39:23

@Destry – good write-up, thanks. This will come in handy for some project next month.

@Bloke – looking forward to your Themes work. Makss patch(es) sounds very interesting, although wee bit hard to follow from here.

jstubbs · 2016-12-22 02:22:05

Very nice write up Destry – thanks and time to try out flat files again! Care to post the tutorial to Textpattern Tips?

NicolasGraph · 2016-12-22 08:58:36

Bloke wrote #303339:

I like all this stuff, but bear in mind that Themes are-a-comin’ so the process will differ from the above. You won’t need plugins to do it, unless you want your plugin repo under VCS management too […]. If you want to help out with the flat-file side of things in core, feel free to pull the themes branch down and let me know. I’ll then share the core flat-file code I have so far, which is currently uncommitted.

@Bloke, You are right, I should take a look deeper in the core work. I’m not sure if and how I can help but I’ll take a try in 2017, you can send me the uncommited changes.

I’ll also try to fusionate the two plugins if I find enough time but it probably won’t be released promptly ; meanwhile, I’ll update the rah_flat doc with Destry’s tip.

Last edited by NicolasGraph (2016-12-22 09:09:20)

NicolasGraph · 2016-12-22 09:44:24

@Destry, I went back to the rah_ prefix because I think that we can considrate the original plugin as orphan, and even if I’m not as good as Gocom was, I really think that the improvements I made should make v0.5 the official last release, so I just adopted the plugin as Bloke did for zem_contact (I should remove “fork” in the thread title). Keeping the same prefix when adopting is a way to keep plugin users on the track. And having two or three plugins with the same name but a different prefix wouldn’t be confusing? How would you know what is the consistency between them?

Last edited by NicolasGraph (2016-12-22 11:15:28)

mrdale · 2016-12-28 16:20:39

Still agitating for a pony even though Xmas is over with.

pony = rah_flat extended to handle articles in either textile (even though I consider it a very silly puppy) or html.

Bloke · 2016-12-28 16:28:51

Your pony might be closer than you think. If we can figure out a way to tweak this patch by makss it has the ability to load articles from flat files.

Combined with the themes work, it might deliver a pretty good interpretation of a pony at some point. At the moment, it’s arguably not a full pony. Maybe with three legs. Or one leg made of wood.

mrdale · 2016-12-28 21:33:58

Bloke wrote #303425:

Combined with the themes work, it might deliver a pretty good interpretation of a pony at some point.

That sounds incredible. Having messed around with kirby I can tell you that putting together a new site where you can simply move around and edit text files is an incredibly fast workflow.

Gocom · 2017-03-13 22:08:48

NicolasGraph wrote #303365:

if I’m not as good as Gocom was

You known I’m not dead, right? ;-)

rah_ prefix

I like that some of you folks been continuing my work, but when it comes to prefixes could you please use your own prefixes when it comes to releasing your forks? I mean, to not confuse people or creating the issue where we have two (or more) plugins with the same name, but incomparable code bases.

Whether it has my original plugin’s name, or not, doesn’t make it any more or less official, or less useful. It’s a thing whether it’s name is blp_imports or rah_flat and users can find it regardless.

I mean, would you want to use a plugin prefix that allegedly is short for “racist asshole” (is it!?) or some nice and cuddly such “Billy’s lucky ponies”.

bici · 2017-03-14 00:06:45

Rah-plugins | What? I’m a little confused… again :-)
?/ me three

how come RAH_FLAT is not in your repo of plugins? have you abandoned it to the internets?

Textpattern CMS support forum

#46 2016-12-21 10:37:19

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

NicolasGraph wrote #303328:

#47 2016-12-21 14:14:59

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

bici wrote #303321:

jcr plugin:

(oui) rah plugin:

Clean up

#48 2016-12-21 14:28:17

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

Destry wrote #303333:

#49 2016-12-21 15:19:37

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

NicolasGraph wrote #303334:

#50 2016-12-21 15:35:21

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

#51 2016-12-21 19:12:14

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

NicolasGraph wrote #303334:

#52 2016-12-22 00:39:23

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

#53 2016-12-22 02:22:05

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

#54 2016-12-22 08:58:36

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

Bloke wrote #303339:

#55 2016-12-22 09:44:24

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

#56 2016-12-28 16:20:39

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

#57 2016-12-28 16:28:51

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

#58 2016-12-28 21:33:58

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

Bloke wrote #303425:

#59 2017-03-13 22:08:48

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

NicolasGraph wrote #303365:

#60 2017-03-14 00:06:45

Re: oui_flat (rah_flat fork) - Manage templates and prefs as flat files

Board footer