Snippet Creation Docs or Tutorial?

H i - can anyone point me towards a good thread or docs for snippet creation / development for those new to modX? I’ve perused the available resources, but I can’t seem to locate any good documentation on how to create a snippet, etc. - specific steps, what is nesc. to for output, if one can access a DB server and extraneous DB tables from with a snippet, how to integrate a snippet with calls to outside SQL resources - basically a beginner’s tutorial to nippet development.


thanks

Steveua

Hi Steveua,

Well, I’m not sure about any other threads but I hope the information below helps:

What is a Snippet?

Snippets, at the heart of the matter, provide a way of including PHP code into your template, document, template variable or chunk. (I’m sure I’ve missed a few already ) In the most typical case, this is to provide some form of HTML output (and the output can be governed by using input parameters to the snippet – but this isn’t mandatory)

As the documentation states, it can also provide a useful means of other forms of processing, such as checking if a user logged in or not.

Basic Flow of a Snippet

Every snippet, in the typical case, will follow the three basic steps below:

1. Process any snippet inputs
2. Conduct the main processing and store any required output into a variable.
3. Return the output.

Input Parameters

An example of a typical snippet call is as follows:

Each of the variables is parsed into a PHP variable in the snippet, and it’s important to note that all variables passed via the snippet parameters are converted to a string. So, if you require Boolean values as input parameters then use `0` and `1` as these can be typecast into Boolean values in the snippet.
This will check for the input parameter ’myVar’ and, if set, use the value that has been passed into the snippet - if not, it sets the variable to some default text that can later be used in the snippet (for evaluation purposes perhaps)

What about the Database functions?

You can use any of the DBAPI functions in the snippet. This gives you access to the full range of database operations you may need to do. As for external databases, this is achievable as well – you just need to create another instance of the DBAPI (there is a thread somewhere on this, I’ll try and find it for you)

And, don’t forget, you also have access to all the other functions available through the document parser – for example, access to the Document Object. User defined functions can be included as you would in any other PHP script.

So, what about the output?

The output from a snippet (if required) can be handled in a few ways:

1. Return a variable
2. Setting a placeholder – for using somewhere in your document, template, chunk etc.

Placeholders are easy to set. You can use:

Where, $myVariable is the output that has been buffered. You would then use [+myPlaceholderName+] to display the output on your page.

Cache / No Cache ?

Most snippets will run fine if called cached, i.e. using [[mySnippet]]. However, some snippets require the need to be called uncached. In these instances, you can use [!mySnippet!] - simple, eh?

What Next?

One of the best ways (and how I figured it all out) is to look over the Repository and pick out some of the simpler snippets to analyse (for example, my A to Z snippet is relatively simple <- definite plug ) And, of course, if you have any questions, then post back and I’m sure we’ll be able to help.

Hope this helps in some way,

Garry

Gary - that was very helpful - one of y’all (MODx team) needs to take your response and drop it whole into the snippet documentation - seriously - there’s almost nothing there, and the below explanation is extremely helpful. I may have a few other questions in a bit, if you don’t mind..., after I try the DBAPI...thanks again, Gary.

Anyone - in the DBAPI, what are the wrappers for mysql_select_db() and mysql_connect()? I can’t find any references...it seems as if there should be a lot more to the DBAPI - is it just undocumented?

I browsed the MODx files, and I found the dbapi class files - are the other functions/methods listed accessed in the same manner - i.e., $modx->db->functionName()?
And how is the connection method properly used?
And how does one go about de-bugging snippets? Are there best practices?





thanks,
Steveua

You can call any of the functions in the DBAPI include file with the $modx->db->functionName(arg1, arg2) syntax.

As far as debugging, you can use echo and print() statements to see the output where you have placed the snippet tags. I often use this little bit of code:


I use this for checking the POST, GET, SESSION, or any other arrays I want to examine.