Documentation

Author: jeffgbutler

src/site/markdown/docs/extending.md

@@ -1,6 +1,6 @@
 # Extending MyBatis Dynamic SQL
 
-The library has been designed for extension from the very start of the design.  We do not believe that the library
+The library has been designed for extension from the very beginning.  We do not believe that the library
 covers all possible uses, and we wanted to make it possible to add functionality that suits the needs of different
 projects.
 
@@ -11,10 +11,18 @@ The SELECT support is the most complex part of the library, and also the part of
 extended.  There are two main interfaces involved with extending the SELECT support.  Picking which interface to
 implement is dependent on how you want to use your extension.
 
-| Interface                                | Purpose                                                                                                                                  |
-|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
-| `org.mybatis.dynamic.sql.BasicColumn`    | Use this interface if you want to add capabilities to a SELECT list or a GROUP BY expression. For example, creating a calculated column. |
-| `org.mybatis.dynamic.sql.BindableColumn` | Use this interface if you want to add capabilities to a WHERE clause. For example, creating a custom condition.                          |
+| Interface                                | Purpose                                                                                                                               |
+|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| `org.mybatis.dynamic.sql.BasicColumn`    | Use this interface if you want to add capabilities to a SELECT list or a GROUP BY expression. For example, using a database function. |
+| `org.mybatis.dynamic.sql.BindableColumn` | Use this interface if you want to add capabilities to a WHERE clause. For example, creating a custom condition.                       |
+
+Rendering is the process of generating an appropriate SQL fragment to implement the function or calculated column.
+The library will call a method `render(RenderingContext)` in your implementation. This method should return an
+instance of `FragmentAndParameters` containing your desired SQL fragment and any bind parameters needed. Bind
+parameter markers can be calculated by calling the `RenderingContext.calculateParameterInfo()` method. That method will
+return a properly formatted bind marker for the SQL string, and a matching Map key you should use in your parameter map.
+In general, you do not need to worry about adding spacing, commas, etc. before or after your fragment - the library
+will properly format the final statement from all the different fragments.
 
 See the following sections for examples.
 
@@ -166,6 +174,37 @@ public class Upper extends AbstractUniTypeFunction<String, Upper> {
 }
 ```
 
+Note that `FragmentAndParameters` has a utility method that can simplify the implementation if you do not need to
+add any new parameters to the resulting fragment. For example, the UPPER function can be simplified as follows:
+
+```java
+import org.mybatis.dynamic.sql.render.RenderingContext;
+import org.mybatis.dynamic.sql.select.function.AbstractUniTypeFunction;
+import org.mybatis.dynamic.sql.util.FragmentAndParameters;
+
+public class Upper extends AbstractUniTypeFunction<String, Upper> {
+
+   private Upper(BindableColumn<String> column) {
+      super(column);
+   }
+
+   @Override
+   public FragmentAndParameters render(RenderingContext renderingContext) {
+      return = column.render(renderingContext).mapFragment(f -> "upper(" + f + ")"); //$NON-NLS-1$ //$NON-NLS-2$
+   }
+
+   @Override
+   protected Upper copy() {
+      return new Upper(column);
+   }
+
+   public static Upper of(BindableColumn<String> column) {
+      return new Upper(column);
+   }
+}
+```
+
+
 ### OperatorFunction Example
 
 The following function implements the concatenate operator. Note that the operator can be applied to list of columns of