4.9 Macros in Stories and Comments

Macros are at heart a bit like HTML tags. Instead of telling the browser what to do, though, macros tell Scoop what to do. This allows you to give users limited access to functions that could, if not limited, leave you with a security problem or stuff on your site that you don't want.

To configure the macro system, create the macro definitions you want to use, then set the variable use_macros to 1. Macro definitions are created in the Macros Admin Tool (A.20).

Macros can be either rendered when the story is saved or every time it's viewed using the variable macro_render_on_save. Which setting you want will depend on what your macros do. If all your macros do something completely static, then having them render on save can reduce the load on your server. If your macros are dynamic, or you want them to run with the environment and preferences of the user viewing the page instead of the story author, then macros should be rendered every time they're viewed.

When using the edit queue (4.1.1) keep in mind that the author can edit the story after it's been saved, so if macros render on saving, when the author edits the story, he will be presented with the output of the macro rather than the macro command.

Macros can also be rendered `verbosely' by turning on the variable macro_render_verbose, that is, extra comments will be added around the macro and the original macro command will be preserved in an HTML comment when the rendered macro is displayed.

When the macro system is enabled, Scoop will scan stories and comments for existing macros and replace them with the macro definition you have created. Macros are indicated in stories and comments with double parentheses around the macro name. To use the included example macro, macro_test, you would put ((macro_test)) where you want the text of that macro to appear.

For example, if you have a box that you want users to be able to embed in a story or comment, you would do this via a macro. Normally, boxes and blocks are not substituted in stories for security reasons. If you created a macro with the box key (|BOX,boxid|) as the value, then that one box can be embedded in a story while denying access to the other boxes. Any box, block, or site control that can be interpolated into a regular block via vertical pipes is available to macros.

Macros can take arguments as well. If, for example, you want to allow users to embed images in their stories and comments but don't want them linking to any arbitrary picture out on the internet, you can create a macro with one argument that allows the user to specify the filename of an image in the directory you set. Arguments are used in the macro definition as ((1)) for the first argument, ((2)) for the second argument, and so on. With file uploads (4.12) and this macro, users could put images in their upload directory into their stories but no other images.

If you created a macro called img and gave it the definition <IMG src="|upload_link_user|((1))"> then a user could put ((img 2/filename.jpg)) in their story or comment, and that image would appear in their story. (The 2 in this example is the user's numeric UID.)

If macros don't seem to be working, try putting ((macro_test)) in a story or comment. If the system is active, that will be replaced by some red text telling you that the macro system is active. This macro is included by default as an example.


janra
2004-03-26