README

Download | Packagist | Donate to the original author

This plugin makes your Textpattern CMS database more flat, manageable and editable. Edit templates, forms, pages, preferences and sections as flat files. Use any editor, work in teams and store your website’s source under your favorite version control system.

Warning: this plugin will permanently remove some of your current templates when activated.

Installing

Using Composer:

$ composer require oui/oui_flat:*

Or download a plugin package.

Requirements

• Textpattern 4.6.0 or newer.
• PHP 5.3.6 or newer.

Basics

oui_flat imports normal, flat files from a specified directory to your Textpattern database. This, in essence, lets you to edit your database contents from any regular editor and store the source as flat files.

oui_flat comes with built-in support for a few essential content types: styles, forms, pages, preferences, sections and textpacks. It is also able to manage variables via plugin prefs. See the templates directory on GitHub for an example how this all works.

Your flat files are imported to the database:

• Automatically on the background when the site is in the production status selected via the related plugin preference.
• When the public callback hook URL is accessed. The URL can be used for deployment.

If you want to exclude a certain content type from importing, just don’t create a directory for it. No directory, and oui_flat will leave the database alone when it comes to that content type.

Preferences

The plugin has set of preferences you can find on Textpattern’s normal preferences panel.

Path to the templates directory

Specifies path to the root templates directory containing all the content-type specific directories. This path is relative to your ‘textpattern’ installation directory. For example, a path ../templates would point to a directory located in the same directory as your textpattern directory and the main index.php file.

Security key for the public callback

Security key for the public callback hook URL. Importing is done when the URL is accessed. The URL follows the format of:

http://example.com/?oui_flat_key={yourKey}

Where http://example.com/ is your site’s URL, and {yourKey} is the security key you specified.

Templates folder example

┌ templates
├── forms
├── pages
├── prefs
├── sections
├── styles
├── textpacks
└── variables

For most existing template subfolders, the related admin tab will be disable.
The Admin > Preferences tab will still be accessible, however saved preferences will be overriden by existing flat files while the /prefs folder exists
The admin Admin > languages tab will still be accessible and usable while the /pages folder exists.

Contained files can use whatever extension.

Forms

Form types can be defined by filename prefixes or /forms subfolder names.
misc type is used by default when no prefix is found in files stored directly in the /form folder.

┌ templates
├── forms
├──── article.example_1.txp
├──── example_2.txp
├──── …
├── …

or

┌ templates
├── forms
├──── article
├────── example_1.txp
├────── …
├──── misc
├────── example_2.txp
├────── …
├──── …
├── …

Pages

├── …
├── pages
├──── example.txp
├──── …
├── …

Prefs

Prefs files can contain a JSON tree or just the preference value as text.

├── …
├── prefs
├──── sitename.json
├──── site_slogan.txt
├──── …
├── …

Available JSON field is:

• val (string): preference value;

sitename.txt would just contain the preference related value.

Sections

Sections files are managed via JSON files.

├── …
├── sections
├──── example.json
├──── …
├── …

Available JSON fields are:

• title (string): section title;
• description (string): section meta-description;
• page (string): page in use;
• css (string): styles in use;
• is_default (bool): true makes it the default section;
• in_rss (bool): true includes section articles in feeds;
• on_frontpage (bool): true displays section articles on the frontpage;
• searchable (bool): true includes section articles in search results.

Styles

├── …
├── styles
├──── default.css
├──── …
├── …

textpacks

├── …
├── textpacks
├──── example.textpack
├──── …
├── …

Variables

Variables can be defined via JSON files as plugin prefs and used through the <txp:variable /> tag.

├── …
├── variables
├──── example.json
├──── …

Available JSON fields are:

• value (string): variable value;
• html (string): name of the function to use in the admin (if the /variables is removed). Natively available functions are: text_input, pref_long_text, yesnoradio.
• position (int): variable position.

Toolshed notice

This is a toolshed project. Experimental fork from rah_flat which is not part of the main supported product line of Rah. Not yet at least. Please use at your own risk.

Changelog

Version 0.7.0-beta (oui_flat from upcoming rah_flat-v0.4) – 2017/06/25

• Changed: requires Textpatern 4.6+
• Added: Do not delete pages or styles that are used by a section.
• Changed: variables use rah_flat_variables event only and are all visible or hidden as for other contents;
• Changed: preferences stay always visible.
• Improved: Uses original Textpacks format;

Version 0.6.0 (oui_flat) – 2017/03/14

• Changed: Back to oui_ plugin author prefix.
• Changed: Lighten compiled code by removing duplicated license infos.

Version 0.5.0 (oui_flat) – 2016/08/26

• Changed: Forms are stored by types in subfolders and don’t need prefixes anymore.
• Added: Custom form types are changed to ‘misc’ when the plugin is disable to avoid an error in the Forms tab.
• Changed: Preferences update affects values only.
• Added: Prefs are hidden in the admin if set via flat files and get back to visible when the plugin is disabled.
• Added: Custom prefs (in the variables folder) accept more paramters in .json files.
• Changed: Custom prefs (in the variables folder) now have a oui_flat_var_ prefix added to their name.

Version 0.4.0 (oui_flat) – 2015/11/29

• Added: Custom preferences can be created and use as Txp variables.
• Changed: Forms naming convention is now type.name.txp.

Version 0.3.0 (rah_flat) – 2014/03/28

• Added: Drop access to a admin-side panel only if the specific content-type is active and has a directory set up.
• Added: Invokable oui_flat.import callback event.
• Added: Sections and preferences get their names from the filename.
• Added: Preferences are always just updated, no strands are created.
• Added: Preference fields that are not specified in a file are kept as-is in the database.
• Added: French translation by Patrick Lefevre.
• Changed: Renamed confusing Oui_Flat_Import_Template interface to Oui_Flat_Import_ImportInterface.

Version 0.2.0 (rah_flat) – 2014/03/19

• Reworked.

Version 0.1.0 (rah_flat) – 2013/05/07

• Initial release.