Template Files and Naming conventions

marios · 2006-10-23 16:04:40

Hello again,

I am writing this post, because I downloaded randomly some templates for testing purposes.
However, the main purpose was to see, how well goes mcw_templates with some randomly chosen templates
and 4.0.4.
My overall impression was a frustrating experience, to see at least a dozen of different manners to name these files.
So here is my general suggestion about naming those files.

Example:
Form Templates
Article Forms:
<code>my_example_form.article.txt</code>
File Forms:
<code>my_example_form.file.txt</code>
Comment Forms:
<code>some_other_dummy_example_form.comment.txt</code>

etc… (Same for link and miscs forms, which should have prepended link and misc before the actual file extension.)

Whitespace and brackets or other non-word characters should be avoided,
and everything preferably lowercase.

Eg.:comments_Form Template my_form.txt
or: some_comment_form (comment).txt or such other Exotic breeds is not a good Idea.

(Whitespace characters in file names create all sorts of problems, anyway)

I have been using a convention like this below for quite some time.

eg.: xxx_my_form_article.txfml

(Where xxx is a creator code and txfml a special file extension used mainly to distinguish between page files and form files)

mcw_templates however, will not be able to distinguish what is what (for the form template files), if it doesn’t find the form type descripter
prepended with a period before the file name, and thus you will be unable to perform an initial import session for a form template set.

For the new version of Textpattern Bundle, which will be released shortly, I through together some
commands, which will do the file name conversion automatically, but only if the form name descripter is seperated by an underscore.
(not hyphen or other characters)

To compensate for the other cases as well (white space and such), would make it necessary to call some complicated perl scripts,
which I don’t want to waste my time for.

The Same goes for the Folder Names as well:

They should be:
-pages
-forms
-css

(all lowercase again)

Although those do cause you less headache as the file names.

Any opinions, suggestions about this topic ?

Regards, marios

hcgtv · 2006-10-23 16:26:49

Are you thinking in terms of using something like mcw_templates to install new themes?

marios · 2006-10-23 16:36:42

I’m talking about the 4.0.4 world where we use this excellent plugin to install new template sets.
(I use it all the time for my own templates, and it’s working great if you keep your files in order)
But a general Naming convention guideline, that we could publish somewhere would make:

A) a lot of sense even without using the plugin
B) our lives a lot easier
C) Our workflows more productive

I am also working on a new Bundle Version for TextMate where this plugin becomes even more useful.
(No mysql stuff yet, Bastian Teerhorst has done a sql Bundle for TM, that can be used also)

regards, marios

(The forum doesn’t like html anymore)

Last edited by marios (2006-10-23 16:38:15)

jm · 2006-10-24 00:02:07

Personally, I prefer single file templates. Like for my template, I just made one .txt file, named much like a plugin with the version # in it.

Something like this:

//------------------Pages
	//-------------page: stuff
	<txp:if_article_list>
		...
	</txp:if_article_list>

//------------------Forms
	//-------------form: single
	<txp:article_image />
	<txp:body />

//------------------Style/CSS
	//-------------style: default
	body {}

	//-------------style: ie
	html {
		display: none;
	}

Last edited by jm (2006-10-24 00:02:43)

Ace of Dubs · 2006-10-24 00:56:42

interesting jm…but sounds like a heck of a lot of scrolling

yikes!

jm · 2006-10-24 02:06:23

Yeah, but I’d much rather scroll than have 20 files open. In my case, it was only ~200 lines. When I was starting with Textpattern, I tried a template, but ran screaming, after seeing tons of “p_default.txt, p_special.txt, f_this.txt, f_comments.txt”.

Ace of Dubs · 2006-10-24 09:28:22

That’s why I use TextMate.. having 20 documents open really isnt that big a deal. If it works for you then kudos, but my CSS files alone would make the one-page template a nightmare!

Still I could see this being somewhat useful on a different scale. Having a doc for pages, another one for forms and a third for CSS might be the move

Thanks 4 sharin

Last edited by Ace of Dubs (2006-10-24 09:30:10)

marios · 2006-10-25 01:46:45

To reiterate on this Idea, When you for example download a Template Set from the Textgarden Site, then
you will most likely find three Folders: Pages, Forms and css, which are used by mcw_templates to determine
the import path names used for the sql query that does it.
When you perform an export session, also you will have noticed , that the files, that spill out into the form Target Folder have the format : My_form.article.ext, my_form.comment.ext, my_form.file.ext, etc.

Template sets however, that name their files eg. my_form_comment.txt, or my_form (Article Form Template) front.txt, or article-my_form.txt, or such, are useless for an initial import session,
since there is no way how the backend could know which form is an article form and which is a file form etc.
In those cases then, it would be either necessary to modify the plugin code, (which is the last thing I would do to poke around in mikes excellent code) or to perform a find and replace on the file names.

So for my own needs, I wrote a command in TM, that does mainly three things:

1) it looks for the correct Folders and
2) renames all forms in the forms folder to the form mentioned above
3) adapts the file extensions.

(Note, that both folder names and file extensions can be adjusted in the plugin code ,prior to an export session)

The most important point though is, that the form type descriptor, which: is xxx.formtype.ext,
where formtype can have the 5 possible values of forms used
be present at a determined position in the filename, whether you work with TM or not.

The other conventions that I mentioned above, are also important, but don’t cause you that much trouble.
What will you do, if you want to make an initial import session, and you have 80 forms with exotic file names ?

regards, marios

Last edited by marios (2006-10-25 01:48:02)

marios · 2006-11-10 02:38:58

Is there any interest still in this one, or shall we ditch it ?
(It was meant to save us all a lot of time and hassle)

(Moderators? Admins?)

regards, marios

hcgtv · 2006-11-10 14:01:13

marios, I’m interested.

If we can have a standard naming convention where installing new templates would make it easier via a plugin and not trash existing ones already installed, I’m all for it.

hakjoon · 2006-11-10 16:28:59

I’ all for this too, but it seems that for any impact the standard would have to be enforced for Textgarden submissions. That way testing a theme becomes a matter of

export current one as backup
Import new one
If you hate it import the old one back

Much easier then how it’s currently done.

marios · 2006-11-10 18:58:28

What would you recommend, suggest , add, to set up a standard, that is both forwards and backwards compatible ?

There is also the concept of include headers, that can be inserted on each first line of those files as html comment.

Would it make sense to work to a commonly accepted standard ? Involve some more Core Developers, etc.

Zem had done a great job in the past for the plugin standards, and it proved itself useful. Even without a special mention , or a dedicated resource pointing to these conventions, the majority of the plugin developers did grasp this concept and it has worked until today.

A small comity, may be that’ll discuss these matters on a dedicated Blog / Site comes to my mind, ( Just as preliminary Idea)

regards, marios

Zarabadoo · 2006-11-10 20:00:40

One thing to consider is the sightings of theme support. If there is going to be such a thing, a solid standard for compiling them would be good. The sooner we can make a solid standard, the easier such a system would be to develop. It would also allow for a nice library of working template packages if/when such a system shows. It is definitely long term thinking, but it would probably be beneficial for the community to get it done.

Now, I am not a PHP/MySQL programmer by any means, so I do not know which would be simpler to deal with: multiple files or a single file. Either one should be fairly simple to deal with especially if you have an XML control file or something. The single file would work nicely since you could import it almost like a plugin. Just copy and past the code to the administration panel. Plus to the multiple files is that it does make it pretty easy for the developer to keep track of. Once done, he/she can just compile a simple XML control file to dictate what is what each file should be classified as (page, article form, link, form, etc.). It would also compensate for the images needed for a template since it would have to be zipped up anyway. You could still upload it via admin and just have it unpack and install on the server.

In nameing conventions, I always name my forms in the backend to reflect the project and never overwrite the default file short of the error page. I would like to see this sort of styling implemented.

Last edited by Zarabadoo (2006-11-10 20:02:27)

hcgtv · 2006-12-09 21:28:14

marios,

I’m ready to start cranking out Themes for Textpattern, but before I do…

Since you’ve worked on the Textmate bundle, I ask for you advice as to how best to name pages, forms and styles for these new themes.

Thanks.

PS. mcw_templates appears to be the best mechanism I’ve found for export and import.

marios · 2006-12-09 21:57:55

Great news, hcgtv. I am doing the same right now, working on a quite complex template port to be released under GPL.
(testing now and ironing out the glitches)
When you do an export session with mcw_templates, you will notice, that the forms all have the form type prepended before the real file extension.
That was a very clever move from mike’s side to include this feature in the second plugin version.
The file extension can be set at the beginning of the plugin code.
(In your backend, those are not visible of course , since when you reimport they are stripped off again)
(They must match of course for an import session)

So for instance, an article form then could be:

gen_default

For an export session mcw then appends .article.txfml to it, since I have set it like that in the plugin prefs.
IMPORTANT: For a user to be able to successfully import a template set, those respective form delimiters must be present
in your template form files, when you package them up:
blabla.file.ext, something.comment.ext, etc ( for the 5 different form categories )
(But since you are building your template sets right from TXP, there is practically no need for it)

File Extensions

Now, because the Bundle relies on custom file extensions for some of its commands, I had invented a convention for my own needs.
I don’t know if this is feasible but it did work for me.

.txfml for forms, and .txpml for pages, and .css for css.

Folders

Forms, Pages and CSS are in their respective folders (lowercase)
which are:
forms, pages, css.

I’m not that certain myself , what’s best, that’s why I opened this thread.
The Port’s Template name for instance, that I am working on right now, is called Generico.
I am integrating zem_contact and bab_newsletter into it, so for the corresponding Subscriber Submit Form, I made up
gen_bab_zem_subscribe.
(I’d rather have used a three character creator index, but there wasn’t any)

There’s more info available in the online documentation , if you are interested, for the file extensions:

regards, marios

Last edited by marios (2006-12-09 23:37:35)

Textpattern CMS

Textpattern CMS support forum

#1 2006-10-23 16:04:40

Template Files and Naming conventions

#2 2006-10-23 16:26:49

Re: Template Files and Naming conventions

#3 2006-10-23 16:36:42

Re: Template Files and Naming conventions

#4 2006-10-24 00:02:07

Re: Template Files and Naming conventions

#5 2006-10-24 00:56:42

Re: Template Files and Naming conventions

#6 2006-10-24 02:06:23

Re: Template Files and Naming conventions

#7 2006-10-24 09:28:22

Re: Template Files and Naming conventions

#8 2006-10-25 01:46:45

Re: Template Files and Naming conventions

#9 2006-11-10 02:38:58

Re: Template Files and Naming conventions

#10 2006-11-10 14:01:13

Re: Template Files and Naming conventions

#11 2006-11-10 16:28:59

Re: Template Files and Naming conventions

#12 2006-11-10 18:58:28

Re: Template Files and Naming conventions

#13 2006-11-10 20:00:40

Re: Template Files and Naming conventions

#14 2006-12-09 21:28:14

Re: Template Files and Naming conventions

#15 2006-12-09 21:57:55

Re: Template Files and Naming conventions

Board footer