CSSDelyrium

A TM Language bundle for Textpattern

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

Textpatterns flexibility and its extensibility features are fine, but one big problem with this has always been some lack of integration possibilities with all the rest of your development tools. TextMate seems to be the perfect choice to fill the gap between the Textpattern backend,the database and your subversion repositories.(if any)

TM didn’t have a bundle for Textpattern yet, so I decided to make one.

After almost two weeks and this, the third version (beta) of the bundle, it’s finally there. With almost 3000 lines of code this bundle will give you Syntax highlighting for all of the approximately 110 known Textpattern tags.

If you are unfamiliar with the concept of scopes in Textmate, then it is a good Idea to study the manual first. I spent almost one week just for that and another one to generate the Language Grammar.

It is worthwhile to mention, that I haven’t even explored 10% of the powerful tools, that TM has to offer.

Before I lay out the details below, a few introductory reminders.

It might be possible, that you hear people saying something like this: What are all these colors good for, if it is just to see the code better and have some colored spots ?Fortunately, this is a misaligned conception and can be killed right on the spot. The concept of Scopes in TM will allow you later on to unlock the real powers of TM.

For instance, you could build a custom set of snippets or commands, that would insert something based on the scope, where the caret is currently in and apply the same key equivalents or tab-triggers to the whole set, but each element could have different scopes assigned in the Bundle editors scope selector field

Then TM would recognize the scopes you are in and insert only the item that is relevant for the scope that it has been designed for, while using the same key equivalent or tab-trigger. E.g.: command-shift-M for the whole set. Whenever you build something for your needs in TextMate,either a snippet, macro, command or drag command, you can assign both tab triggers or/and key equivalents.

This is a similar concept like for example with the specificity of CSS Selectors that target various HTML elements.

Currently though the scopes that the Language Grammar provides are only scopes for inside Texpattern tags, except for the PHP tag which is a special case and will provide you with a scope that spans its start and closing tags, so it is available for Textpatterns peculiar and special taghandler PHP code. Note, that this feature is currently not included in the Bundle, so you have to wait for the update, to get the desired results.

This problem and the extension of scopes that span their corresponding start and closing container tags will be addressed in future versions of the bundle,much in a simular fashion, that it has been done for the experimental XHTML bundle.

Scopes are working properly in par with HTML, CSS and javascript, except in a couple of unusual cases. These are mainly bugs of other bundle items, that greedily match things, that they are not supposed to,and interfere with the TXP scopes, and not of the Textpattern bundle. To get at the current scopes, just press ⌃⇧P and they will pop-up as a tool tip.

In the screenshot above is an example of interference from the CSS bundle. You can see, that the scope that the tool tip shows, has nothing to do with the tags that the caret is on. In such cases, you could either disable the interfering bundle in the bundle Editor, or comment the appropriate repository include statement in the Language Grammar, although I will probably export this in to a preference item.

What does the bundle feature ?

1. Syntax highlighting for all known Textpattern tags, attributes and values through customized scopes.
2. Auto Completions while you type.
3. Quick Tag selections through the symbol list.
4. Syntax checking on tags, values and attributes while you type
5. A customized Textpattern theme
6. Integration with other bundle items, tested for XHTML, CSS, PHP and javascript.
7. Identification of plugin, container, single and conditional tags,with individual scope values for all of them.
8. A small sample set with tag snippets.
9. Tag manual help command and quick lookup.
10. Auto-recognizing of Textpattern forms and pages files, Naming conventions and a couple of side-notes

Syntax highlighting for all known Textpattern tags, attributes and values through customized scopes.

The syntax highlighting works on all known Textpattern tags, and let you easily distinguish between single tags, container tags, weather they are conditionals, or plugin tags. The customized Theme, that is provided as a download below, gives a specific color to single tags and another one to container tags. If you accidentally close a starting container tag with a single tag ending slash before the bracket,the Theme warns you about that and the corresponding closing container tag immediately changes its color.

Auto Completions while you type.

When you insert Textpattern tags in your templates, even using snippets and hit sequentially the escape key, TM will let you cycle through a list of all possible tag-names, when the caret is in a tag-name scope and attribute names, when it is in an attribute name scope.

Quick Tag selections through the symbol list.

When you work on very large documents, you can select a tag from a list that is accessible from the toolbar right next to the gear menu icon.

Syntax checking on tags, values and attributes while you type

While you type along and insert attributes and values,TM will warn you if you use illegal attributes or attribute values. This is visible in your code through the intense violet scope highlighting. In certain cases this might not function as expected, and it is of course not possible to recognize your custom form names or numerals, that TM does not know about,it will warn you though,in case you use illegal characters and even checks for valid strf time format for your custom date formats as shown in the screenshot below:

Therefore, if such a value as one of your custom form names is not recognized it will still have a scope of invalid.illegal, but with the suffix of value unknown-unrecognized, and you can change that in the theme editor. NOTE:The bundle is not able to distinguish, weather an attribute value belongs to the correct attribute of one specific tag, this might be addressed in future versions of the bundle, and in some cases it will fail to correctly match the scopes, if it finds empty quoted strings. Ideally all possible attribute names and values should be grouped first in other repository group items and and included in a recursive manner. Hopefully this might be possible one day, so that each attribute name will know about it’s allowed values. Below is an example of custom attribute values with their scopes recognized as unrecognized/unknown.

A customized Textpattern theme

Although it is basically not necessary to have an own individual custom User Theme, I just made one, since it helped me a lot during testing and debugging the bundles major quirks.

Note, that the scope names, from the viewpoint of a programer do not always really make sense, this is because the major purpose of those names is not classification but proper integration with other bundles and the purpose of their compatibility.

In that sense, any Theme could be used with any bundle Language, might it be HTML,Smarty,Markdown or CSS.

Integration with other bundle items, tested for XHTML, CSS PHP and javascript

The regular expressions that drive the Bundles Language Grammar are fine-graded enough, to distinguish Textpattern code from HTML, CSS and even javascript code or embedded PHP, though it is currently not possible to match tags, if they are provided as an argument for example as attribute values of HTML tags. In this case, it will have a scope of string.quoted.double, and is colored differently. According to Allan Odgaard, the possibility to match those cases as well, will be addressed in future version of TextMate, but is currently not possible to work properly without interference problems of enabled third party bundles in your editor.

Identification of plugin, container, single and conditional tags,with individual scope values for all of them.

When TM finds a plugin tag, you will realize, that there are some additional scopes available, that make it possible, not only to distinguish the plugin author id, but the extended name part of it.

Note also, that in some rare instances, where plugin developers do not comply with the naming conventions for TXP plugin tags, the bundle fails to recognize any of them

The naming convention says, that the three first symbols of the plug-in’s name part must be lowercase letters (from a to z) and either other like underscores or such are not allowed.

This was done for a specific reason,for example:If you would have a plugin tag set, that would have the following name structure: One with:txp:zem_contact_radio and another one with: txp:zem_contact_email, this then would allow you to target the whole set, while still having the possibility to target them individually.

At the current version of the Bundle, the plugins are matched in a generic fashion,while conventional TXP tags can be matched by their names, much like it does in the experimental XHTML bundle.

For instance a permlink-tag used as a container tag, will have the scopes: TXP.container.tag.permlink and entity.name.tag.permlink.txp,while used as a single tag the scopes are: meta.tag.single-no-atts.txp and entity.name.tag.single.permlink.txp.

A plugin tag on the other hand, since it does yet only have generic scopes, has: entity.name.tag.plugin.single and meta.tag.plugin.generic.txp , plus the extended generic scopes.

For the purpose of extensibility on this concept, the scopes for plugin tags can be customized through preference files in the Bundle and each of them can be matched individually when a new repository module gets inserted in the preference file. More on that in the next article about the Bundle.

A small sample set with tag snippets.

Commands and snippets in TM let you easily customize your needs and generate all sorts of intermingled Textpattern and HTML code constructs, using variables holding tab stops placeholders, that can also perform mirroring , transformations or even conditional insertions through the use of regular expressions.

In it’s most simple form, these can just be $nas tab stops.I have explored only a small fraction of these features.(Not to think even about the Shell variables or any kind of scripts that you could collect) and used mirrors and transformations mostly in another Bundle called TXPGrammartech, that was used to generate the Language Grammar for the Bundle. More on that later.

The Bundle contains two snippets, that let you generate a generic container and single tag. While you tab through, you can insert the attributes and values and the corresponding closing tag mirrors the value of the first insertion variable.
Here is a basic example:

<txp:article form="${1:my_article_form}" listform="${2:my_listform}" id="${3:article_ID}" status="${4:value}" />

$0

It is also possible to make use of TM’s dynamic variables, for instance TM_current_word would insert the current word , the caret is on. For example to get it wrapped by something else. The snippets can be either triggered through tab triggers or key equivalents.

For instance, if you type art and then press tab, a TXP article tag gets inserted and you can then tab through the placeholders to insert and/or skip attributes and name values.

Tag manual help command and quick lookup.

When you press control H and the caret is located on a Textpattern tag, a popup window will look up this tag from the Textbook manual and provide you with all the necessary information about the specific tag.

Note, that this currently fails, when the tag is a single tag, that is, because of the URL structure on the Textpattern Site, and I could not yet figure out how to make the command conditional. The other command will query the XML-RPC service and look up the support documentation as available from your backend.

Auto-recognizing of Textpattern forms and pages files, Naming conventions and a couple of side-notes

TM will automatically, recognize your forms and pages, provided, they have the proper file extensions. To have the most flexible concept on this, there are actually three of them, although there is currently no direct gain in the use of the last two. This was done with the prospective thought of extensibility in mind and for any further enhancements of the Language Bundle that might occur.

For instance, I was thinking even about additional scopes, that would warn you , weather a tag is disallowed in an article form or page form context, something that is currently not yet possible. Then in this case, I would need the additional file extensions to make the distinction possible.

TXFML

for forms

TXPML

for pages

TXAML

for articles

In case you are using Mike West’s mcw_templates plugin, you can set your export file extensions from within the plugins preferences inside the editing field of the plugin.

So those should be changed from text to TXPML for pages, and TXFML for forms accordingly.

Now there you have it, combining the most excellent of all publishing Tools with the elegance of a TM swiss army knife.

Finally go and get this Bundle below, and let me know if you find any bugs, that need to be eliminated.

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: 2070 times

Version v0.5

TextMateBundle     Ⓧ   DOWNLOAD for Textpattern NEW VERSION

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

Total amount of downloads: 2070 times

You probably also want to take advantage of the customizable theme, that in reality is nothing but another Theme from Thomas Aylott called Twilight, that I modified and renamed to TXP Safari. It has all the Textpattern scopes styled as shown in the screenshots of this article.

TextMate Theme     Ⓧ   DOWNLOAD TXP Safari

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

Total amount of downloads: 2070 times

To load the bundle just put it in :~/Library/Application Support/TextMate/Bundles. , since it is not available from the Subversion Repository yet. When you first load it, you will notice that it takes approximately 3 seconds to render, the same holds true for the experimental XHTML Bundle as well, since it has approximately about 4500 lines of code and performs a lot of recursive matches, so make sure you have enough memory installed on your MAC. 1GB would be perfect.

And in case you haven’t noticed it yet. Any bundle that you have customized or developed according to your needs can just be dragged out of the bundle editor to your desktop, so you can easily compress and share it with your fellow mates around the community, to get the best out of both of the three worlds.

Note also, that the conditional plugin module is currently missing from the bundle downloads language Grammar, so if you see no scopes and colors on them this is due to the fact, that I need to do some debugging on this one before I can include it in the next update.

Textile borks the validation again with its silly br-tag insertion, there is nothing that I can do now about it, I’ll have to rewrite all the TXP image tags to XHTML before I can switch textile off. I’m glad I have TM, to ease the pain on this.

Posted ·2006-06-14 · by · marios ·

© 2006-2008 marios buttner

send this article to a friend