Using TV Bindings
Bindings allow a TV to get its content from an external source. This could be the output of specified PHP code, a file, another document or from the database. Bindings are specified by using the @BINDING syntax in the TV's Default Value field.
Bindings are used simply by entering the binding you want to use, followed by the file name, chunk name, document ID, PHP code to be parsed, sql query to be executed, etc.
The code for processing bindings is in the /manager/includes/tmplvars.commands.inc.php file.
The @BINDING Options
There are seven binding options.
- @FILE - use the contents of the given file. A full or relative path to the file must be used.
- @CHUNK - use the content of the given chunk, using the chunk's name.
- @DOCUMENT - use the content of the given document, using the document's ID (the number in parentheses to the right of the document in the Document Tree).
- @SELECT - use the results of a query to the database.
- @EVAL - use the output of given PHP code.
- @INHERIT - inherits the value of the same TV as set for a parent document.
- @DIRECTORY - a list of files in the given directory. The list output uses || as a delimiter.
The content of chunks and documents are inserted directly into the document object being parsed, and any MODx tags in that content are processed on the next pass of the parser. It would be possible for the maximum number of passes (10, as set in the index.php file) to be reached, in which case the MODx tags would not be processed but rather displayed in the final page. If this were to occur, it would most likely be a good idea to re-think the design and structure of your template and content. However, most instances of MODx tags not being processed are caused by misspelling the name of the MODx element in the tags.
@EVAL
The @EVAL binding simply takes the argument and passes it as a parameter to the PHP eval() function. The value of the TV will be the returned value of the eval() function, so the PHP code needs to start with the return function:
@SELECT
The @SELECT binding returns the result set of a SELECT SQL query. Simply enter the query as a normal sql SELECT query. Placeholders can be used for variable values. Two placeholders are already set, [+DBASE+] and [+PREFIX+], which are set to your MODx database name and table prefix. Other placeholders can be set in snippets and @EVAL TVs. Just make sure the snippet or @EVAL TV is called before the @SELECT TV.
This binding will return the raw result set of the SELECT query. You can process this either with your own snippet or configure the @SELECT TV to use the dataset output widget.
Let's say you have a listing of restaurants, and you want to display a list of restaurants in a given zip code. First you would set a placeholder with the zip code; how you get this is irrelevant to this discussion.
$modx->setPlaceholder('restaurantzip', $zip);
This code could be in a snippet processing a user-submitted form, or in an @EVAL TV.
Then you would query your restaurant table (or whatever table you have the zip code of your restaurants in) using the placeholder you've set. Make sure to add the single-quotes around the placeholder if the value will be a string.
@SELECT * FROM [+PREFIX+]restuarants WHERE zip='[+restaurantzip+]'
This will give you a result set that you can process as you would normally process the result set of any SELECT query.
@INHERIT
The @INHERIT TV is a little confusing at first, but once you understand it you'll wonder how you ever created a site without it. Basically what it does is cause a document to "inherit" the value of the same TV as set in a parent document.
When creating the TV the default value is @INHERIT. Now edit the TV in the parent document of each section of your Document Tree, replacing the @INHERIT with the value you want the rest of the documents under that parent to have. This is especially good for setting &startId or &parents values for snippets like Wayfinder or Ditto.
Another example might be where you want different sections of your site to have a different image in the sidebar or masthead. Since I try to avoid images as part of the template, using CSS background images instead, I frequently use a small <stlye> block in my template head, with a background image for the masthead or colors for the headers and titles. I use an @INHERIT TV for the image name (you can even use an image input type TV for this) or the color value, and edit the TV in the parent document of each section. This way each section will have a different image or different colors.
You can set a default value, such as @INHERIT blue, so that you will get something even if you don't edit the TV in any documents.
Of course, if you edit the TV for any of the child documents, the value you set in that document will be used rather than the parent's value. This being the case, if you have editors working with the site, make sure that they understand that they must not change the TVs that show a value of @INHERIT!
Comment On This Article
Do you find something unclear? Did I miss something or get something wrong? What do you like or not like about this chapter? Please do not ask for help here; use the forums if you need help.