Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nicolasgraph/oui_flat

Flat theme management plugin for @Textpattern (from rah_flat by @gocom)
https://github.com/nicolasgraph/oui_flat

flat-files templates textpattern textpattern-plugin theme themes

Last synced: about 11 hours ago
JSON representation

Flat theme management plugin for @Textpattern (from rah_flat by @gocom)

Awesome Lists containing this project

README 

        
h1. oui_flat



"Download":https://github.com/nicolasgraph/oui_flat/releases | "Packagist":https://packagist.org/packages/oui/oui_flat | "Donate to the original author":http://rahforum.biz/donate/oui_flat



This plugin makes your "Textpattern CMS":http://www.textpattern.com 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":http://en.wikipedia.org/wiki/Revision_control.



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



h2. Installing



Using "Composer":https://getcomposer.org:



bc. $ composer require oui/oui_flat:*



Or "download":https://github.com/nicolasgraph/oui_flat/releases a plugin package.



h2. Requirements



* Textpattern 4.6.0 or newer.

* PHP 5.3.6 or newer.



h2. 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":https://github.com/nicolasgraph/oui_flat/tree/master/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.



h2. Preferences



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



h3. 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.



h3. 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:



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



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



h2. Templates folder example



bc.. ┌ templates

├── forms

├── pages

├── prefs

├── sections

├── styles

├── textpacks

└── variables



p. 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.



h3. 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.



bc.. ┌ templates

├── forms

├──── article.example_1.txp

├──── example_2.txp

├──── …

├── …



p. or



bc.. ┌ templates

├── forms

├──── article

├────── example_1.txp

├────── …

├──── misc

├────── example_2.txp

├────── …

├──── …

├── …



h3. Pages



bc.. ├── …

├── pages

├──── example.txp

├──── …

├── …



h3. Prefs



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



bc.. ├── …

├── prefs

├──── sitename.json

├──── site_slogan.txt

├──── …

├── …



p. Available JSON field is:



* @val@ (string): preference value;



@sitename.txt@ would just contain the preference related value.



h3. Sections



Sections files are managed via JSON files.



bc.. ├── …

├── sections

├──── example.json

├──── …

├── …



p. 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.



h3. Styles



bc.. ├── …

├── styles

├──── default.css

├──── …

├── …



h3. textpacks



bc.. ├── …

├── textpacks

├──── example.textpack

├──── …

├── …



h3. Variables



Variables can be defined via JSON files as plugin prefs and used through the @@ tag.



bc.. ├── …

├── variables

├──── example.json

├──── …



p. 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.



h2. Toolshed notice



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



h2. Changelog



h3. 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;



h3. 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.



h3. 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.



h3. 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@.



h3. 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":https://github.com/cara-tm.

* Changed: Renamed confusing @Oui_Flat_Import_Template@ interface to @Oui_Flat_Import_ImportInterface@.



h3. Version 0.2.0 (rah_flat) - 2014/03/19



* Reworked.



h3. Version 0.1.0 (rah_flat) - 2013/05/07



* Initial release.