CSSDelyrium

TMBundle for Textpattern Reborn

NOTICE: Not all of the information corresponds to the latest Bundle version, please refer to TXP bundle version 07

After the first User complaints about HTML not showing up properly, which I found a pharmacy for and some minor Bugs, that I discovered myself and after the last nightly attack from the anonymous bushes, (which aren't at all so anonymous to me), I decided to improve the Bundle even more.

Packed now with 27 Items, which include also some more commands and snippets, this should give you ample possibilities to poke out many different workflow strategies and code with style and finesse your favorite Textpattern Templates. See also the release Notes below.

Because not all Users have SVN installed, or necessarily do want to get involved with it, the updated download version now will display your HTML tags in your Templates, regardless which Bundle Items are present or disabled in the Bundle Editor.

I did use however a rather non-conformant solution, which I should not have been doing, but this was done , so it is possible to get the first evaluation results, about how the Language Grammar finally behaves in real world conditions.

I also performed a latest test by randomly downloading a Template set from the Textgarden Site and it showed, that all HTML and TXP tags show up with their proper scopes as shown in the Article Image above.

If you can not see your Bundle Items after you have installed the Textpattern Bundle, for example by double clicking on it, see below for Details in the Section Installation Instructions.

Support Article main Index

1. Installation Instructions
2. Release Notes, Changes to the previous version
3. How to handle the Bundles prefernces and alter their settings ?
4. Usage Examples for Snippets,Commands and Macros
5. A simple workflow example
6. The Language Grammar,Bugs Limitations and observations
7. The next Generation of the Language Grammar
8. Resources
9. Downloads

TextMate versions, Default Bundles, SVN Bundles and Third Party Bundles

back to top

TextMate has generally three different locations for Bundles:

The details are described in section 5 of your TM Help Manual,but as a favor. Those are:

Bundle locations
∼/Library/Application Support/TextMate/Bundles	Bundles that you create, modify, duplicate, double click and so on
/Library/Application Support/TextMate/Bundles	Bundles under SVN control
∼/Library/Application Support/TextMate/Bundles/PristineCopy	For Third party Bundles
/path/to/TextMate.app/Contents/SharedSupport/Bundles	Only for default assorted Bundles (To be left alone)

I hope I'm not mistaken on some of those, since it is a little confusing, as TM keeps track of even deleted bundles in different locations,which means they are not really deleted in reality.

Note, that all this no longer really concerns you, if you are using the latest cutting Edge version of TM since then, any Bundle, that you received from third parties, gets automatically installed in their proper location, once you double click on the Bundle Lego Icon.

It might be possible, that you are not able to see your Bundle Items, once you have installed the Bundle. Basically, this would happen, if you are using on older TM Build, that has not been updated. In that case the best solution at hand, would be to update your TM Install to a post r948 version of TextMate. Since the Bundle is a Latest Cutting Edge version, it is not compatible with TM Builds prior to r948. Fortunately this can be done automatically from the preference menu by Choosing Software Update and altering the corresponding Settings.

This is according To Allan Odgaard a small Incompatibility Issue with the file extensions between the old XML plist syntax and the new one and updating to latest cutting Edge solves all of these problems.

Note also, that the Bundle is incompatible with the XHTML Grammar version of the Experimental HTML Bundle, so it can either only be used with the normal HTML Bundle or the XHTML Bundle which are already included in this Bundle version.

New Features, Changes and Capabilities of the Bundle

back to top

The new version of the Bundle now no longer requires, that SVN Bundles are present in your Bundle Editor. Note also, that you can always enable or disable Bundles from within the Bundle's Filter command at the bottom of the Bundle list. This seems to be especially useful,if you are experimenting with different version/clones of your Bundles, that have the same scopes and file matches,or if you do not wish to extend the scopes of an existing Language Bundle. Since it is yet not available in any other fashion than as third party download and also, because there was no solution at hand to eliminate Interference problems from the default assorted HTML Bundle,I included a patched version of the HTML Bundle, and I also included a default version of the XHTML Bundle, this was done as per User request, so yo can choose between HTML and XHTML strict, which AFAIK is only available from the SVN repository.

So far the changes to the previous version contain the following:

1. Help commands are now correctly working on both TXP container and single tags
2. Additionally the commands are context sensitive and return wiki man pages on non plugin tags and plugin entries from the Textpattern resources Site on plugin tags using the same MAC OS conventional command H shortcut
3. Likewise they return W3C pages on HTML tags
4. Plugin tag modules of the Language Grammar no longer interfere with each other overriding their proper scope categories
5. Attribute names and values of plugin tags now have their proper scopes,although a Syntax scope distinction is not available for them.
6. Performed a find and replace on TXP container tag scope names for better scope name handling and also to eliminate a scope interference,although the whole naming concept might eventually be completely reworked, so don't count on those scope names yet.
7. NEW.:A special comment toggling is now enabled, that makes use of the anc_hide plugin, accessible through the default command slash shortcut.(Very useful, read detailed instructions below.)
8. NEW.:Article form attribute completions command lets you cycle through a list of all your article forms
9. NEW.:Example commands and MACRO for auto TOC insertion
10. NEW.:Oniguruma Tabbing Macro, see details below

How to handle the Bundles preferences and alter their settings ?

back to top

The first three Items of the Bundle define its Language Grammar rules, the latter two of those have been included to circumvent the previous HTML interference problems. This is basically not the correct way to do this, but it will give you also a basic advantage over the normal way. So I just patched the basic HTML Grammar item, altered the default scope name and changed the Include rules on the core Language Item. What that means is, that you no longer need to get the other SVN Bundles, and also you can leave the original HTML Bundle as is on your install. I did so only for the Language Item of the Bundle,which means in order to use all its commands and snippets (The HTML ones), you have to drag them over from the original HTML bundle to the Textpattern Bundle,so they are available if you want to work on documents with both HTML and TXP tags without switching languages.

It is a little silly to do it that way, but it was only done as a temporary solution, until the assorted HTML Bundle Grammar gets a SVN update, so it no longer matches Textpattern tags.

I have yet not assigned any key equivalent to the Bundle, since it is difficult to find a good one that is not already taken by another Language. Perfect would have been control option shift T, but that was already taken by Brad Choates version of Textile

The first preference Item, which is also a gray smartie with a P in it, handles comments in TXP Documents and is especially useful but it needs a litte explanation. Normally , when you comment out code blocks, that contain TXP tags in your templates, it is not possible to comment them out, without having them visible from the HTML source code of the public side. That is useful when you have a site to develop, that has already gone through production status, and you still want to leave a lot of stuff like other code blocks, comments and so in your templates.So instead of using the normal default HTML comment style, I made the Toggle command use a plugin, anc_hide, which lets you hide both HTML and TXP code portions.

This command is toggled with the default command slash and toggles either a selection or the current line, if there is no selection. Required for this to work on your TXP Install as expected is, that you have this plugin first installed and enabled. You can still make Use of the default HTML comment style, it just can not be toggled with command slash.

The next preference Item is just a default TM set of Indent Patterns that rules what the tab key should do when you author your templates, and I haven't spend any time on this one yet.

The next smartie (P), Smart Typing Pairs defines, which characters should be mirrored after the insertion position of the caret, There is not much that needed to be changed there, since the TM default behavior for those is, that if you have a character, that gets matched by those rules and you don't want to have it mirrored, you just press (forward) delete afterwards, and the mirrored part gets discarded.

The next preference Item in the Bundle handles Spellchecking for normal text in your templates, you can enable or diable Spellchecking by altering the key value to either 1 or 0.

The symbol list preference Item decides whether your tags are accessible from "Show in Symbol List" or not. Again it can be disabled or enabled with 1 or zero, and you can adjust which tags would show up by refining the scopes in the scope Selector field.

It is also possible to customize the scopes in the Bundle Editors Scope selector field, for example to have it show HTML tags as well.

The last three preference Items handle completions in your TXPBundle and in an experimental manner there is now a completion on your custom attribute values available, that cycles through all available article forms in your project by sequentially pressing the escape key. This currently only works on article tags, but you can easily adapt this concept for your other forms and tags as well. This requires you to keep a special naming convention on your forms, so you have the possibility to allow any new preference Items of this kind to make a distinction based on their names.

To enable or disable Grammar include rules, you have to either comment or un-comment the relevant include values after the single quote, at line 158 of the first Language Grammar Item. CSS,Javascript, HTML, XHTML can be enabled or disabled to your linkings. Note, that it is more convenient to use the Edit in External Editor command to do this, since then it will automatically open in its own default Language scope, as shown in the screenshot below. (Only if you have the plist bundle)

Usage Examples for HTML, a minimal case

back to top

Oniguruma tabbing:

I found this example on the web and could not find the original resource anymore to give credit to the author of the original tip. This is quite useful,if you want to tab through all your attribute values, regardless what they are and it is bound to the enter key on your numeric keypad. It uses Oniguruma style RE syntax, that instead of specific strings matches zero width positions.

The context sensitive help lookup commands for Tags,accessible through the standard ctrl H shortcut now also work for plugin Tags, but for that latter kind of Tags it is required, that the caret is located on the plugin Authors ID part of the tag(The first three digits of the Plugin name). That is because of the special way the scopes in plugin tags are split up, since the generic method they are matched with by this version of the Plugins Language Grammar make them use a different Set of regular expressions, so they don't interfere with each other, and the default Set of TXP tags.

Included in the Bundle is also a special snippet/macro set, that lets you easily generate a TOC like the one that was used in this set of articles.

It is not directly related with the bundle, but since all my time was completely used up by the difficult task to make the Language Grammar behave as expected, I didn't have anything else at hand to come up with. So I just give the below as a general example on how mirrors, substitutions and transformations are used in TM snippets to customize your code.

Here is how to use this:Just type TOC and then press tab to start the snippet insertion TOC and then you should see something like that:

<li id=""><a href="#"></a></li>
<h3><a id=""></a></h3>

A small mistake (The underscores on the li IDs) ,produces invalid XHTML and will mistakenly link back the source anchors to their parent elements, so here is a corrected code version for the snippet, in case you want to replace the faulty one.

You can also have this as a download below.

Code snippet     Ⓧ   DOWNLOAD TXP Safari

Here the Section Headers of the TOC are mirrored with their corresponding list element contents while you type, and a transformation and substitution is performed on the source and target anchors accordingly by stripping off the whitespace, replacing it with underscores and discarding everything after the first four words and finally by lowercasing those variable transformations,while the list IDs get uppercased and discarded their whitespace. This assumes, that you only use spaces and no commas, and that you type at least four words.(I also didn't make the regular expression, so it matches numbers as well, so no numbers in this example). In any other case, the snippet will not give you the desired results. What you then can do, after the second TOC snippet insertion in your document, is to make use of the corresponding macro to reorder the header and list elements, so they show up in the right sequence. The macro is bound to ctrl shift command R, if you want to execute it. (Note, that it only works, if insertion happens on an empty line)

There are also two snippet commands.(The green smarties)The first one wraps your selection with TXP conditional tags, and the second one also generates a TOC, but ist uses perl for that. I found it from a User submission of the MacroMates Resources Site. The difference is,that it can use multiple lines from a list of text Items in your document, but it is not capable to transform the anchor parts.

A simple workflow example

back to top

An easy way to take advantage of all those features without getting frustrated is to make use of Mike Wests mcw_templates plugin This very useful admin-side plugin lets you import and export your forms and pages from the database easily,and as a safety measure a backup version of the latest export set is kept in your install after reimporting. The plugin relies on a special folder named _Templates inside your Textpattern Folder, so if you have a set of changes on your local Site you can use Transmits Docksend to mirror the _Templates Folder and then reimport back all your forms and pages into the database. There are definitely other and more effective solutions at hand to deal with this, but the above is the most foolproof method available.

Don't forget, that if you want your forms and pages be recognized automatically, that you have to define the correct file extensions in Mike West's plugin, from your Back-ends edit plugin window at the beginning of the plugin code.

Those file extensions are TXFML for forms, and TXPML for pages,while the additional option TXAML, for articles is optional and meant for future versions of the Bundle(Not available as an export feature anyway)

For details refer to the last section of the original article Conventions

The Language Grammar evaluation,Bugs Limitations and observations

back to top

One thing that is not working at all at this stage are the folding start markers and folding stop markers. What ever I tried, I couldn't make them work, so I suspect, that they rely on some TM inherent key settings and I did yet not have the time to look into that problem. Lately I thought, that for TXP tags, that those only would make sense with the conditional group of container tags, since in most of all the other cases, there isn't much to fold considering the way, the tags are intermingled with HTML in forms and pages.

If you are using the special open in TM command shortcut ctrl cmd E, it might be , that in article documents you don't get any sopes working as expected. I have yet to figure out, why that is, but since those documents have the file extension .safari, and those documents do neither have doc-type info nor usually TXP tags in them, it must have something to do with how I have set up the scopes for for the Language Grammar.

What I strongly suggest is, that in any cases that TXP or plugin tags do not get matched by the Language Grammar, or in cases where you get Interference problems, that you keep notice of those, or collect this information and give feedback on the contact page of this blog, so I have the possibility to evaluate the collected Data, before I elaborate on the next version of the bundle. Another thing, that would be possibly desirable,is the inclusion of a Language extension or preference Item for: Yes,you guessed it right: all the global variables of Textpatterns special Tag-handler code. This then could be handled in a simular fashion as it does for embedded PHP in HTML.

The next Generation of the Language Grammar,Future thoughts and general Ideas

back to top

As already mentioned in the previous article most inspiration to construct the Language Grammar was taken from the experimental XHTML Bundle. This Monster Bundle with a Language Grammar that spans approximately 4500 lines of code has the ability to match a complete DOM Tree with recursive matching on all valid element and attribute names and for HTML tags resolves to one exclusive root node, which represents the HTML element. Textpattern tags on the other hand do not have this requirement inside form or page documents, so for that reason the TXP container tags at this stage of the plugin do not have the ability to define a scope for their corresponding start and end tags, something I would like to have for the next version of the Bundle for at least all conditional container tags.

XML-RPC API Integration. Unfortunately, since the Bundle kept me busy, i did yet not have the chance to inspect in Detail Kusors new Testing release of the XML-RPC API, and to find out what can be done with it from within TM, but it seems to work with Ecto, as I saw, scratching it on the surface.

drag commands and Templates.(On the TODO list)

One thing I haven't looked into yet, is the whole concept of Project Handling in Textmate and this could possibly include the Use of custom scripts, that help to detect your Section and category names and other such, like attribute values. Unfortunately I totally lack behind in Expertise on this area, so Ideas and Suggestions on this subject are welcomed.

There is also a Blogging Bundle available through your TM Install via SVN (maintained and created by Brad Choate), but I didn't have time to take a look at it yet. Here is an article with a screen-cast about what the blogging bundle can do. It would be wonderful of course, to have that working for Textpattern as well.

Useful Resources, Credits

back to top

This Bundle would not have been possible, if there would not have been Alan Odgaards excellent documentation in the first place. So thanks to him for putting this wonderful application together and for the very concise and detailed documentation, that I would recommend to everyone, even as an interesting read.

I also consider it as a special honor to got linked to this set of articles by one of the Greatest and finest artists on the web today, Ion Hicks, from his favorite side-link section.(Thanks Ion) Therefore I consider, that even in its infant stage, the Bundle must have been of some use for some folks out there.

Thanks to Mike West for making this wonderful plugin, based on Ben Bruce original versions and Ideas. For detailed Installation instructions consult the relavent entry on his Blog.

The anc_hide plugin for Textpattern which is quite useful as well has been written by Andy Chase

Thanks to Robert also and Matthew for their positive feedback and helping hands.

Thanks also to Ace of Dubs who gave me the final motivation kick to mix the appropriate pharmacy together for all the code-handling problems in Textpattern, that we have been suffering from for all too long now.

Downloads

back to top

Latest version of the Bundle below and the Textpattern Theme in case you need it

Download latest Version 07.beta Archive

TextMateBundle     Ⓧ   DOWNLOAD for Textpattern NEW VERSION

Last modified:    Tue 20 Feb 03:32:39 2007

Total amount of downloads: 2746 times

---

Posted ·2006-06-19 · by · marios ·

---

© 2006-2008 marios buttner

send this article to a friend

send article