Naming conventions for template authors TODO
Unofficial Working Draft for a Textpattern Templating Naming Convention
Purpose and Intention of this Document
- This is a Draft for a proposed Naming Convention, to name, structure and package up Template Files
- the Purpose of this document is to help Template Authors and Porters to:
- Provide Template Packages, that are compatible with:
- Current versions of Textpattern of the 4.0.x Branch
- Helper Plugins and Texteditors that handle either/or/and
- Textpattern Page template, Form template and CSS files
- Textpattern source Code
- Providing both forwards and backwards compatibility, also towards a possible Implementation of a Theme Engine] is desired from the large User Base of Textpattern, allthough not defined yet as a concrete concept.
- Users and Developpers are encouraged, to provide Idias, correct mistakes towards a useful and thoughtful planning of this Naming Convention.
- A possible sample Download Package, that Template Authors can download would be ideal, to have consistent results, once all involved Parties have agreed upon a convention, that does not cause any problems, with any further evolution of the Textpattern source code.
Background and current Base Implementations of Templating work
- The basic need for a naming convention has partly emerged, after various Tools, to work with template files have been created from the Textpattern userbase.
- These Tools do exist in various forms and for different reasons, either in the form of plugins, modifications of the Source code and as extensions of External TextEditors to also ease the work on Source code in general.
Understanding templating workflows with mcw_templates
- Import and Export Session.
- To maintain compatibilty with mcw_templates for example, we have to distinguish between Import and export Sessions.
- Performing an export session, mcw_templates already prepends the form type delimiter on all form files that successfully got exported, while the file extension is configurable in the plugin itself.
- An Import Session of a Template Set can not be performed, if the form type delimiter prepended to the extension is missing. (That is how it works)
Current Convention Proposals
- The following convention Proposals already have been made
- File Naming Convention, Proposal 1
- Form files could have 4 distinct parts.
- File Naming Convention, Proposal 1
An example for an article form file (As a packaged derivative)
- The first part (xxx) is the creator code, that would identify the Template author, in the same fashion, as it is already handled for plugin files.Here it is followed by an underscore, that suits the general syntax structure of a Textpattern tag. 1. The second part (yyyy) (after the underscore delimiter) is the part that could identify the structural and functional aspect of the form file.It is followed by a dot delimiter. 2. This second part, can by itself have a subpattern, that could naturally follow any mental pattern a Template Author prefers. Example:
- - The third part identifies the form category (article, comment, link,
file or misc.)
The forth part, the file extension could be altered, from txt, to
something else, to also make it possible, to distinguish between forms,
pages and CSS files.
- txfml for forms.
- txpml for pages.
- css for styles.
- The forth part, the file extension could be altered, from txt, to something else, to also make it possible, to distinguish between forms, pages and CSS files.
= What to take in to account ? =
- Of particular importance is cross platform compatibility on
different Operating Systems:
- Do double extension values work on these.
- And if so , with how many digits ?
- Is it managable in most of the used Texteditors ?
Things, that generally should be avoided:
- White space characters in file and folder-names
- Arbitrary and unnecessary Information in File and Form-names (Those can easily go inside the files themself as comments)
- UTF characters that are not part of the ASCII ANSI range
- Braces, hyphens, quotes or any other non_word or non_numerical characters
- Files, that are not properly UTF-8 encoded and old-style ISO doctype meta declarations in Page Templates.
- Uppercasing,Titlecasing and Camelcasing of file and folder names. Lowercase file and folder names should be the prefered format, to avoid confusion and inconsistencies accross different OS platforms.
= Proposed Folder Structure =
- All names lowercase.
- No spaces
- The folder names can simply be :`css`,`pages`, and `forms` and should be sibblings where the parent-folder could have the template name as folder-name.
- It has been suggested, to move the textpattern folder outside of the textpattern directory, to make maintenance of the Textpattern source code easier and more reliable. This example can be seen in a modified version of mcw_templates here]
A Folder and File structure and convention like the one mentioned above, does successfully perform an Import session with mcw_templates. If part of the conventions mentioned in section one are not met, it fails.