CSSDelyrium

TXP Bundle version 0.7 beta

The next version of the TXP Bundle is available for download. Version 0.7, because version 0.6 will remain unreleased. The only purpose of version 0.6 was to pile up in-house evaluation data, before then RE-factoring the Language Grammar, which is based on a little different concept.

In a nutshell, the concept is to follow the same shortcuts and Behavior as is in the HTML Bundle. so the typing becomes homogeneous with the former in one go.

Most shortcuts have been changed, but you will find it to be more convenient , once you get used to it.

Furthermore the scope names have been simplified and plugin tags are only matched in a generic manner for both single and container tags.

I am still working on a concept to refine the matching of the plugin tags, but this will take time.

If you still use older versions of this Bundle, it is recommended to through these away.

A last check shows, that there is no Errors in Console, however, it would be nice, if you could check the latter on yours and confirm that at some point.

The Language Grammar that drives this Bundle, spans more than 4300 lines of code and there are 86 Bundle items, where some of them interact with each other in some special manner, so I would recommend, to place your customizations in a separate Bundle, instead of this one.

It will be necessary to install the custom Theme as well, since there is currently no Theme other available that would give us the Syntax highlighting we need, and since I had to change the Scope names, the current Theme that you have, will not give you what you need.

You may wish to start off, calling the documentation,which is basically the same of what follows below, by just pressing ⌃ H, from any TXP scoped document window. I will transpose this article to an on-line documentation with Screenshots in the meanwhile, for more in-depth reference, but it is possible, that the permanent link for this page will change at some point.

The first Screencast, that is pretty trivial walks you through the Typing Basics. I used the H.264 Export settings, which means, you need Quicktime 7 to watch it (AFAIK). It's about 32 MB/ ~11minutes.I didn't bother much to get it down more in file size, since it will only result in ugly artifacts in most cases.

On-line Documentation

1. Introduction
2. Before
3. Naming Conventions
4. Compatibility Issues
5. Setup
6. Static Variables used by the Bundle
7. Shortcuts
8. Templates
9. Navigation
10. Textmate's Scoping Concept and TXP custom Scopes
11. Completions
12. Folding Start and Stop Markers
13. Tag automation
14. Tag Automation Helper Shortcuts
15. Helper commands
16. Drag commands
17. Synchronizing your back-end
18. Help, Troubleshooting and Bugs
19. Credits
20. Closing Note
21. Download

Introduction

Welcome. This Bundle has been created, to bridge the gap between the supreme Luxury CMS Textpattern (developed as a Publishing Tool by Dean Allan) and your mind, with the help of Allan Odgaards excellent Texteditor TextMate.

TextMate and Textpattern now are talking the same Language.

Textpattern can do many things already, but there is only one thing that TextMate can not do yet, and that is:

Automatically update your coffee machine.

Please read this documentation carefully prior using this Bundle, since you will only get frustrated, if you don’t.

This Bundle is compatible with TXP versions 4.0.3 and 4.0.4, which means, that it will match any known TXP tag, and any known TXP attribute, that is either valid or depreciated. It has not been tested with TXP versions prior to the ones mentioned above.

Before

To use the advanced features of this Bundle, it is imperative, that a special Folder named: _templates or templates be present in your Textpattern Root Folder. Inside this Folder, you can keep as many template sets as you like, and for each of them, the Bundle assumes the presence of at least three different Folders: pages, forms and CSS.A forth folder named article is optional, but required, if you want to make use of two of the experimental drag commands.

However, you can use all Tag automation features and Syntax help, even without the below documented Site setup procedure.

Here is an example for a common Site project:

Articles sometimes are used as Elements in Site Structures as well, but even if that is not the case, doing so has many advantages, like having access to Markdown for example, if you prefer that over Textile for instance.

In this case, here is an Example for a common Site project:

You can also Have individual article Sets for each Template Set, like this:

Usually, for a Site project, we want the same Structure both on disk and in the project, so it is best, to set those up on disk prior creating the project.

If you want to make use of Mike West’s excellent mcw_templates plugin, the plugin is included in the download. Mcw templates is based on Scott Woods-Fehr’s original code and Ideas. Later on, you will be able to import and export as many template sets you like and gain access to TextMate’s powerful editing features.

Installing and enabling the plugin is a no-brainer.

Furthermore,the root-folder of your Project Site should be the Root Folder of your Site Project as well.

The second plugin, that is used in par with this Bundle, is the anc_hide plugin provided by Andy Chase. It is a small helper plugin, that allows you to comment out any TXP or HTML code, without the danger of exposing various stuff in your front-end source code. A special comment toggling is available through the default ⌘ /

Naming Conventions

When you create a default set of form templates from within TextMate, make sure, that you keep the following Naming convention:

Later on, for existing template Sets, you will be able to add new Template Files to your Site project, using the create New File in Project, with the default Shortcut ⌘ ⇧ N as shown in the Screenshot below.

1. For form files

   • example_form.article.txfml
   • example_form.comment.txfml
   • example_form.file.txfml
   • example_form.link.txfml
   • example_form.misc.txfml

2. For page files

   example_page.txpml

3. For article bodies

   id.example-title.txaml

(where id is the id number of the article, and example-title the title of your article as it is in the back-end.)

The latter one, if you want to keep some of your articles under TextMate as well, but is optional.

Please note also, that the Folder names for page, form, and CSS templates MUST be : pages,forms and CSS. (lowercase) Some of the commands will not work, if this is not the case.

Compatibility Issues

The HTML Bundle that ships with TextMate is incompatible with this Bundle version. Sorry, but that is how it is. However, for those of you that don’t update their extra Bundles through SVN, a default version of the XHTML Bundle is included in the download. You don’t need to uninstall or change anything in the HTML default Bundle. (In fact, you must not.) TM’s scoping concept takes care of everything. Just install it by double-clicking on the uncompressed file.

The scope names of this Bundle version have been simplified, which means that if you had previous versions of this Bundle, some of your customizations might not work as expected.

The best thing to do in those cases, is the following. Drag out any customized stuff, that you would like to keep out of your old Bundle into a newly created Bundle. Then throuw the old Bundle away by deleting it from within the Bundle Editor. Next drag any item out one by one into the new Bundle, while carefully inspecting the scopes and adapting them to the new Language if necessary.

NOTE: The Experimental HTML Bundle is incompatible with this Bundle and can not be used with it.

Setup

Follow the steps above and adapt your Site root Folders for any existent or newly created Sites. In case you have some piles of template files with names as: my_example_form_article.txtor my_example_page.html, there are some helper commands included in the Bundle, that do the file name conversion auto-magically.

However, this does currently not work, they contain whitespace or hyphens or use other naming conventions.

Those commands can be triggered with ⌃ ⇧ U after you have selected at least one specific file in either a page or form folder from within the Project drawer.

You can choose to convert either file extensions or/and a whole form template set from the context popup menu.

If you want to take advantage of Mike West’s mcw_templates plugin and the special comment toggle, then install those plugins and enable them accordingly. Prior to any export session with the Plugin , it is necessary to adapt the file extensions in the first lines of the plugin code. You can do so by choosing edit plugin from admin > plugins, and changing the file extensions, for both pages to TXPML and forms to TXFML.

Another mandatory step is to set up the required static variables. See for details below:

Static Variables used by the Bundle

The Bundle uses a couple of static environment variables mainly to determine the right base URL’s for your Site projects. If those variables are not set up, some commands do not function as expected. Setting those variables can be done either from your prefs and choosing advanced and then shell variables, or in case you need specific project settings, from the Info Icon at the bottom of your project Drawer after you have deselected all project files in the Drawer. Most likely, you want to use the latter for your Site projects.

Note: Setting up both project variables and global Static variables, is also an effective method, to provide fallback values, since the former will take precedence over the latter.

Below is a list for the Static Variables used by this Bundle version and some example values.

1. $TM_ORGAMIZATION_NAME (required) Whatsoever Inc
2. $TM_LOCAL_URL (required) whatsoever.dev
3. $TM_LOCAL_SITE_ROOT (required) dev_whatsoever
4. $TM_REMOTE_URL (required) whatsoever.com
5. $TM_REMOTE_SITE_ROOT (required) public_html
6. $TM_PERMLINK_MODE (required) This supports currently only two values which are either
7. section/id/title or section/title
8. $TM_CREATOR_PREFIX (optional and experimental) mtv
9. $TM_CATEGORY (optional and experimental) A space separeted list with important categories used in your Site project: Example: dog cat goose mouse shark elephant monkey

Shortcuts

You can get an overview of all available shortcuts through a variety of ways.

1. Examining the Menu Structure after selecting The TXP Bundle in the Bundle Editor.See Screenshot below.

2. With the select Bundle Item command ⌃ ⌘ T and typing key phrase sequences.(Returns global results)

3. From the main menu, by selecting Bundles > Textpattern

4. From the gear Icon in the Tool menu bar and cycling through the menu options.

You can change or customize those shortcuts in case you encounter any conflict, by selecting the Bundle Item and typing the key sequence in the Activation Selector input Field for the key Equivalent option.

Templates

You can create 8 different kinds of Templates in any existent Site project from within TM’s main menu.

1. File > New From Template > Textpattern from the main menu will create a scratch Template outside your Project in a new window.

2. File> New Project File while holding ⇧, will create a new template in the current Directory of your Project.

3. ⌘ ⇧ N

Below is a list with the Templates that are currently available and their custom file extensions:

1. Front Page Templates, using: .txpml
2. Section Page Templates using: .txpml
3. Article Form Templates using: .article.txfml
4. Comment Form Templates using: .comment.txfml
5. File Form Templates using: .file.txfml
6. Link Form Templates using: .link.txfml
7. Miscallaneous Form Templates using: .misc.txfml
8. Article Body Templates using: .txaml

Those should fairly cover all your needs.

You can edit and customize those templates to your own needs by selecting the according template File:

1. From within the Bundle Editor , selecting the Template File Items and changing their contents

2. From the main menu selecting New > New From Templates> Edit Templates.

3. ⌃ ⌥ ⌘ T

Note.: Don’t confuse those Template files with your Template files already existent in your Site project.

Navigation

1. Tag Navigation

   You can select TXP tags from the symbol list menu at the bottom of the document window

2. Template Set Navigation

   It is possible to navigate from any tag attribute of a TXP tag to the corresponding form file using the special TXP Go To command, when the caret is on such an attribute name, ⌘ ⇧ D will take you to the form file, that corresponds to this tag.

   Additionally, the same shortcut, when triggered from within a form template file, will present you with a popup menu containing a Selection list of files that use this form template. Clicking on an item of this list will take you back to this Page Template and position the caret in front of the TXP tag, that uses this form. This command however will fail in a couple of instances, some of those are:

   1. The caret is on the first line of a document, when triggered from within a Form Template.
   2. The working directory of your Project is outside of a pages or forms folder of a template Set.

3. General Attribute Value Navigation

   It is possible to cycle through all attribute values, in any Template file using the Oniguruma Tabbing shortcuts, ⌃ ⇧ ⌘ < and ⌃ ⇧ ⌘ > The latter to cycle backwards and the former to cycle forwards.

TextMate’s scoping concept, and TXP custom scopes

The syntax highlighting and scoping cascade is handled by the Bundle’s Language Grammar. To get at the current scope, position your caret and press ⌃ ⇧ P, which will present you with a tool-tip of the currently available scope for that element.

Just to remind about a couple of useful global TM scoping commands:

It is possible to:

1. View a scope with ⌃ ⇧ P
2. Select a current scope with ⌃ ⌥ B
3. Copy a current scope with ⌃ ⇧ ⌘ C
4. Create a custom Theme using all available custom scopes using the non-assorted Bundle's Theme Builder command (Availiable through SVN)

Other custom Languages, that can currently be used from within a TXP scope, which is automatically selected for you once you open a file, that has the above mentioned file extensions, are : CSS, Javascript and HTML.

Furthermore, it is possible to extend this for other Languages (if needed) adding a special rule in the Language Grammar, although this should be handled with care.

However, custom PHP code, which in TXP templates is delimited with the custom txp:PHP tag, will currently show op as source.smarty. This is a workaround, since it could currently not be handled without modifications of the HTML Bundle, which I don’t want to do.

Since The Bundle’s scopes are fairly peculiar, a custom Theme becomes almost necessary, and it can be installed by double clicking the TEXARI Theme File, which is included in the download.

Custom scopes are available for:

1. Single Tags
2. Container Tags
3. Conditional Tags
4. Plugin Tags
5. Any of the approximately 140 recognized Custom Tags
6. Attributes
7. Attribute Values
8. Any double quoted string

to mention just the most important ones.

Note, that although the Language Grammar is able to correctly distinguish between Plugin Tags and conventional TXP tags, that a couple of things are currently disabled for those tags inside the Language Grammar. What that currently means, is that separate Scopes for attributes and their values are not available for those but only the scope attribute with value.

Completions

It is possible to cycle through a list of possible completion candidates by either pressing or holding the ⎋ key. This works for tag names (omit the TXP prefix and brackets), tag attributes and attribute values.

The completion command is context sensitive, which means it will only cycle through file form attribute names, when used on a file form tag and only through article form tags, when used on article from tags.

The same for all the rest of them.

However, once a completion has been inserted in a double quoted string it appends the file extension as well. Since it was not possible yet to strip it off after the insertion, a special hidden helper macro will do this for you each time you settle on an insertion value.

This macro is called: Remove extension backspace and is triggered with a back-tab (⇧ ⇥). It is important to remember to press ⇧ ⇥ each time you made use of the form name completion command, since your form references will be wrong in the latter case.

This is a temporary workaround. Something better might be found in the future.

Note, that it is also possible to cycle backwards with ⇧ ⎋.

Completions will of course not work on plugin tags.

Folding Start and Stop Markers

Folding Start and stop markers respond only to conventional TXP container tags and not plugin Tags. To have those both for HTML and TXP tags, is currently not possible. You may fold any blocks at any Level. Refer to the documentation that ships with TextMate, to find out more. Just as a small reminder: You can quickly gain access to a Folding Block’s content by hovering over the ellipsis, which will then show up as a tool-tip.

NOTE.: The Permlink Tag can not have Folding start and Stop markers.

Tag Automation

1. Tag Automation for Conventional Tags

   If you are familiar with the default assorted HTML Bundle, then you might have noticed, that the Tag automation commands available in the TXP Bundle pretty much follow the behavior of what is available there. What that means is, that the most efficient way to insert a TXP tag is ⌃ ⇧ < and not ⌃ ⇧ W in most cases for new insertions.

   So if for instance we want to insert an if_section conditional, we can type if underscore and an F, then make use of the TXP tag name completion command by holding on ⎋ and then press ⌃ ⇧ < to let TextMate do all the rest for us.

   The caret then will stay inside the bracket, if the inserted tag is valid with attributes, and you can insert the necessary tag attributes in a similar fashion as for any custom snippet, by just simply tabbing through the rest.

   If the tag does not allow attributes, the caret will be between the ending bracket of the starting tag and the starting bracket of the closing tag, if the tag was a container tag. You would then just press return and the tags do exactly the same thing as it would be the case using HTML tags in HTML scope, using the default assorted HTML Bundle

   Furthermore to this, a special preference handles this behavior for HTML tags as well if your are in text.html.txp-scope, since the default XHTML Bundle does not provide this feature.

2. Multi-line tag automation

   If multi-line wrapping is desired, then those commands are available through the key-equivalent: ⌃ ⌘ ⇧ W. To have each selected Line placed on a single Line, you would use the normal Wrap each selected Line with Tags command from the context menu.

   Additionally to this default behavior, there is another group of commands, which is for instance: Wrap each selected Line with Tags and Return

   

   This will place the closing Tag on the next Line, to prepare it for the Multi Wrap special return Macro. Just continue normally to insert all missing attributes, if any, until the caret is one column number before the closing bracket of the first starting tag.

   Then trigger the Macro with ⌃ ⇧ ↩ , and all container Blocks, will automatically be special returned. This is useful, if you have to work with a large number of such container Blocks, so you can just fold or unfold them, for instance with ⌥ ⌘ 0 if we wanted to fold and unfold for all Blocks on all Levels. Currently, this Macro supports up to 50 (initial) wrapped Lines.

3. Special cases: The TXP Permlink tag

   The special case of a TXP Permlink Tag (Which could be both either a Single, or a Container Tag) is handled by a special Macro, that will save you of the hassle, of having to type TAB trigger key sequences. It is simply triggered with ⌃ ⇧ >, since putting it on ⌃ ⇧ < would slow you down by presenting you with the context popup menu.

   How does it work?

   Simple:

   1. To trigger a Permlink, just press ⌃ ⇧ > (And a single Permlink Tag instance will be inserted.)
   2. If this was desired, then just pressing once more ⇥, will position the caret after the End Bracket.
   3. If this was NOT desired, and we want a Permlink Wrapper, then we just press > and it will be automatically converted to a Permlink Container Tag, leaving the caret in-between.
   4. You can then just press ↩, to split the Tags apart, like with the other Tags.

4. Plugin Tags

   The Plugin Tags are matched by the Language Grammar in a generic way, which means, that there is no way to know beforehand, which one is a Single Tag, which one a Container Tag, and which one has attributes or no attributes.

   For this reason, the most efficient way to type these, relies on a Macro, (which is the same that handles the Permlink Tags, but does a different thing.)

   How does it work?

   Easy:

   1. We first type the Plugin Tag name, like we always do, for instance: zem_contact and press ⌃ ⇧ >
   2. Then we insert the desired tag attributes or backward delete (⌫) the placeholder, to get rid of it
   3. Then we press ⇥ once, which will highlight the closing bracket together with the white-space and backslash character. If the tag was intended as a Single Tag, we press ⇥ once more, and the caret moves to the End bracket of the Tag.
   4. If the Tag was intended as a Container Tag, we type a > and it will automatically insert the closing Tag, leaving the caret in-between.
   5. See above.

Tag Automation Helper Shortcuts

1. Remove any Attribute with value from within a tag.(This special Helper Macro is triggered with ⌘ ⇧ ⌅ for the moment.)
2. Escape from Attribute value.(You can do so, just pressing ⇥, from within a double quoted string)

Helper commands

Some of the more useful helper commands include things as:

1. Open hosts file: To quickly adjust your local development domains
2. Open this for me: To gain quick access to a couple of important admin pages
3. Reformat source code, which can be triggered with ⌥ ⌘ ⇧ F, this however only listens to HTML tags, and one of my major concerns, is to adapt this wonderful script to respond to TXP tags as well.
4. File extension Helper commands may be used, to fix the file extensions. For more complex cases use Peter Maurer’s Find and Replace Utility, which is a big Time Saver, instead of having to pull your hair out about complex perl in sed and grep Bash Syntax.

Drag commands

Currently included by this version of the Bundle are 4 different drag commands.

1. Zip Drag command

This is quite useful, if you want to insert a download link, and you may alter the base URL, by holding on ⇧, while you drop the file. The behavior of this command is to use a local base URL as default and a remote base URL holding ⇧. The link is inserted as a hard coded link, not as a TXP Tag, you can customize this to your needs, if you wish so. The command assumes, that you know the file id of the field beforehand and it can be inserted at a tab stop variable.

1. Screenshot Handler

This command inserts a hardcoded link as well. It has the same modifier key behavior as the zip drag command. When used without the ⌥ modifier key it will insert a hardcoded img tag, that points to the thumbnail version of your image in a folder named screenshots in your public root folder. Furthermore holding on ⌥, it alternatively inserts a link wrapped thumbnail version, pointing to the original and appends a caption paragraph to the image anchor.

There are two reasons, why I wrote this command.The first one being a practical workaround for the Image Handling problems in the TXP Backend, and the second one as a demonstration about what can be done with Drag commands.

That makes it a perfect Tool for technical Writers or Reviewers as well, since it lets you maintain your natural writing Workflow while inserting screenshots in your articles in one Go.

This currently will drop the Source Files in a Folder named Screenshots in the TXP root Folder, either locally or remote, depending on weather you kept pressing the ⇧ modifier key or not.

However you can customize this to your needs. In practice, that means, that you can do four different things depending on what modifier keys you kept pressed during the dropping event in the Document window. One thing to watch out for is, that in case you use the ⌥ modifier key, that you first drag the file into the document window, and then press the ⌥ key and finally drop the file, otherwise the document window will loose focus right under your nose, which is expected behavior though. Additionally, it is possible to auto upload the file to your Live Server, provided, you have Transmit setup correctly to do so. You may enable this feature by removing the Hash symbols from the last lines of the drag command code.

1. Insert Article Form Drag command

This command inserts an article form, when triggered both from a page form document and and article body document window. If the action is illegal, it will exit with the insertion of an Error message.

1. Insert Article Anchor Drag command

This is a special drag command, that allows you to link to any other article from within an article body document window. It only works, if you keep your TM controlled article bodies in a Folder called articles below the _templates Folder, using the above mentioned file extensions, where the article ID number is prepended to the permlink formated title in the filename. (lowercased)

Synchronizing your back-end

There isn’t much available yet, however you can:

1. Access the mcw_templates extension tab to update or export a template set. by pressing ⌃ ⇧ U and selecting update template set from the context popup menu
2. Access any single form or page template that currently exists as such a file in your back-end, by pressing ⌃ ⇧ U and selecting Update Template.

Help, Troubleshooting and Bugs

You can access this Documentation at any time, through the default ⌃ H, while the caret is NOT positioned on a tag.

To use the context sensitive Help command, press the default ⌃ H, which will let you look up any TXP tag or plugin Tag at the Textpattern Support Sites. Just position the caret on the tag name prior triggering the command.

To look up the Tag Syntax Help from your Backend press ⌃ H, while the caret is in the plugin-creator index, which are the first three characters before the first underscore of the tag name. (This may fail in a couple of instances.)

The Language Grammar that is currently used by this Bundle may fail in some rare instances. Report any Bugs if possible together with a sample snippet that failed to get matched correctly.

Some commands will generate an error message, in case of a failure. If such a thing happens, check particularly for these things:

1. Typos or mistakes in variable Names and values
2. Permlink modus in the Permlink variable and commands.
3. Folder or filename inconsistencies in your Project Directories
4. File extensions
5. The status of the working Directory is correct.(You may use the ⌃ ⇧ V command, to echo the current values of your variables)

The Bundle has been thoroughly tested on a huge pile of Sample files on Os X 10.4.8 and up to TM Cutting Edge version r1305 and with Transmit 3.5. I have no Idea, if everything works the same on other platforms and versions, I’d be grateful to hear about it.

You may report any suggestions, errors or bugs either here or at this contact-page if you wish, since it is not available through SVN.

Credits

Credits go to Allan Odgaard for creating this wonderful Application and his excellent Support, Dean Allan for his superb Publishing Tool and Mike West for his intelligent and stable Plugin.

Credits also to James Edward Gray II for giving permission to use and modify his code for the Go to TXP Tag command prior this Book goes to print. If you haven’t heard of him, James is heavily involved into Rails Development, and he is the Mastermind behind the Ruby Idioms for TextMate, and Author of the first Book about TextMate. However, this very useful Book is not only geared towards Rails Developers, since it covers the whole Basics of TextMate Workflow techniques from the ground up. James is a Master on the Keyboard and every single Workflow example that I tried out, was working right out of the Box, even though the Book is in beta stage. Even better, you can have this Book today as PDF beta version, if you don’t want to wait any longer.

Credits also to Andy Chase, for his plugin, which is one of the most useful helper plugins around.

Credits also to Ace of Dubs, and anyone whom I might have forgotten now.

Closing Note

This Bundle has been partly created for my own needs. However, it has been done with the concept of extensibility in mind, and it is possible to customize it to your own needs.

Furthermore, this Bundle has been developed, using TextMate’s latest Cutting Edge version, which means, that it is uncertain to determine,wether everything works the same on previous versions of TextMate, since this remains untested. However, upgrading to latest cutting Edge, will probably get you the desired results.

When it doesn’t fit your bill, or you got a terrific Idea about what could be included to make it better, feel free to use TextMate’s Radio Shack Paradise Toolset to contribute something new, that you have found. The Tools are all there, the building process must be done by yourself.

So now you have it again, maintaining complex Site Projects, will now be possible again from one single document window each time, that does not obfuscate your mind with the burden of proprietary limitations. In fact: Each time you need to accomplish a specific task, there is not only one way to do the job, but at least dozens, if not hundreds, and each time, there will be at least one, that fits your individual and personal workflow needs.

Download version 07.beta

TextMateBundle     Ⓧ   DOWNLOAD for Textpattern NEW VERSION

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

Total amount of downloads: 1553 times

Posted ·2006-11-05 · by · marios ·

© 2006-2008 marios buttner

send this article to a friend