HTML helper mode now supports the ability to add new tags, override existing tags, or add entire new classes of tags after the mode is loaded. You don't have to modify the sources anymore! This is a great convenience for adding in your favourite extensions to HTML, your own special macros, or overriding some tags that are currently in the mode. It is helpful to know something about lisp to extend the mode, but if you don't and you're patient you can probably figure it out from the examples.
I have a simple test module that is well commented and describes how to extend HTML helper mode to add a new tag in an existing type, override an existing tag, and add an entire new type into the mode. The user contributed tags section will have useful examples. The mode itself also uses these same functions to construct the tags it uses, but my fondness for mapcar might make the code a bit confusing to read.
The core of HTML helper mode mode is the function html-helper-add-tag
:
this adds a new HTML tag with a tag type, a keybinding, a template, a completion
string, and an expert menu definition. Here is an example:
(html-helper-add-tag '(phys "c" "<center>" "Center" ("<center>" (r "Text:") "</center>")))
This creates a new tag of type "phys" (more on that in a minute) that inserts
the text <center></center> when the key C-cC-pc or the menu item
"Center" is used. It completes on the string <center>. The general form
for html-helper-add-tag
is
(html-helper-add-tag '(type keybinding completion-string menu-name template))
the type of tag: more information is below.
The key to bind the new tag to. This keybinding is relative to the prefix map implied by the type: if the type has no prefix map, then the keybinding is to html-helper-mode-map.
the most explicit substring to use when doing completion. It is generally the opening part of the HTML tag.
the name to put in the menu. It should be a short descriptive bit of text about what you're inserting, see existing menus for stylistic examples. (This string is also used to produce the symbol for the command. You shouldn't have to worry about that.)
the strings to insert: for more information on templates, see the documentation in tempo.el for tempo-define-template, the note here about templates, or just copy the examples here and in html-helper-mode.
Each tag in HTML helper mode is a member of some "type": types are an attempt at grouping all the HTML tags into some logical structure. Each type of tag is associated with a keymap prefix and a submenu (that is how the prefix C-cC-p was associated to the <center> tag mentioned above.) Install a new type only if you're really supporting a whole new realm of HTML markup.
Before defining tags in a type, the type itself must be defined using html-helper-add-type-to-alist. Here is an example of definining a new type:
(html-helper-add-type-to-alist '(phys . (html-helper-phys-map "\C-c\C-p" html-helper-phys-menu "Insert Physical Styles")))
This creates a new tag type called "phys", with a key prefix of \C-c\C-p and a menu title of "Insert Physical Styles".
The general form of html-helper-add-type-to-alist is
(html-helper-add-type-to-alist '(type . (keymap-var keymap-entry menu-var menu-name")))
This is the symbol for your new type.
These are symbols used to hold the keymap and menu. I recommend html-helper-<type>-map and html-helper-<type>-menu, respectively.
The key to bind your new type to. Emacs convention dictates this be C-cC-letter. If this variable is nil, then all tags of that type are bound to the html-helper-mode-map.
The name to put in the menu. I recommend "Insert <descriptive text>".
After a type is defined in the mode, it also has to be installed to make it visible. This is done via the function html-helper-install-type
(html-helper-install-type 'phys)
HTML helper mode already has a few types used in the mode. If you're truly defining a new type of tag you should create your own type with its own keybinding. But if you're just augmenting an existing type, you can simply add to one of these. In any case you should be careful not to clobber existing keybindings unless you mean to. Don't forget, C-cC-z is also bound to special mode functions.
Type Key Prefix Menu Name ---- ---------- -------------------------- entity none Insert Character Entitites textel none Insert Text Elements head C-cC-b Insert Structural Elements header C-cC-t Insert Headers anchor C-cC-a Insert Hyperlinks logical C-cC-s Insert Logical Styles phys C-cC-p Insert Physical Styles list C-cC-l Insert List Elements form C-cC-f Insert Form Elements image C-cC-i Insert Inlined Images
Once a type is installed, you get the keybindings and menu entries for free. But you have to force HTML helper mode to rebuild its menus to show all the new tags that have been defined. This is done by executing
(html-helper-rebuild-menu)
Charles Curley <ccurley@wyoming.com> wrote me this documentation about templates, in particular prompts. It might be helpful to you.
;; On prompts... C^2: It took some time to figure this out... The (p ;; "prompt: ") and (r "prompt: ") entries indicate where the prompting ;; mode should prompt for a field in the tag. (p ) indicates a ;; parameter, such as the color of a <font> tag. (r ) indicates a ;; region, where the text to be surrounded by the tag should go, such as ;; the text to be turned that color. The difference is this: when ;; prompting mode is turned off and the user is surrounding a region ;; with the tag, the (r ) (region) parameter indicates where the ;; surrounded region will go. The first (p ) (parameter) is where the ;; cursor will go, ready to input the first parameter to the tag. ;; So when you have prompting on, and use the font with color and size ;; tag, put the cursor where you want the modified text to go. Start ;; inserting the tag. You will be prompted for the color, the size, and ;; then the text to display that way. When you have prompting turned ;; off, and don't have a region blocked, insert the font tag, and the ;; cursor will be at the the first parameter. Then tab over to the ;; space between the two parts of the tag, and type in your text. If ;; you have region blocked, C-u followed by the tag will surround the ;; region with the tag. The blocked region goes into the (r ) ;; parameter. Then the cursor is placed at the first (p ) location, ;; ready for you to type in a parameter, such as the color of the text.
These user-contributed extensions to HTML helper mode come with no guarantees. They should work, and they might well add things you'd like to have in the mode. To use an extension, load the extension after html-helper-mode has been loaded via something like
(add-hook 'html-helper-load-hook (function (lambda () (load "some-extension.el"))))
If you have a nice HTML helper mode extension you think is generally useful, please send me mail and tell me and I'll add it here. I would prefer if you just gave me a URL for your own page with your extension, but I can also serve your extension directly from here. Also, please try to coordinate with the html-helper-mode-map and the emacs conventions. It is best to bind to a C-cC-letter combination that is not already used.