Skip to content
This repository was archived by the owner on Nov 9, 2022. It is now read-only.

Adding Custom Build Steps

David Cassel edited this page Apr 11, 2014 · 9 revisions

The Roxy Deployer does a lot of things for you, but sometimes you'll need to do something that the Deployer doesn't handle yet. In that case, you can add a custom step to the deployer, specifying your own XQuery code.

The key is to use the deploy/app_specific.rb file. (You don't need to know Ruby to use this feature.) In this example, a user is adding ODBC views:

class ServerConfig

  def delete_view()
    r = execute_query %Q{
      xquery version "1.0-ml"; 

      import module namespace view = "http://marklogic.com/xdmp/view" 
        at "/MarkLogic/views.xqy";

      try {
        view:remove(
          "main",
          "Compliance"
        )
      } catch ($e) { () }
      (: Deletes a view, of the 'main' schema that contains columns, with a scope on the element, 'html'. :)
    },
    { :db_name => @properties["ml.content-db"] }
  end

  def create_view()
    r = execute_query %Q{
      xquery version "1.0-ml"; 

      import module namespace view = "http://marklogic.com/xdmp/view" 
        at "/MarkLogic/views.xqy";

      try {
        view:schema-create(
          "main",
          ()
        )
      } catch ($e) {()},
      view:create(
          "main",
          "Compliance",
          view:element-view-scope(fn:QName("http://www.w3.org/1999/xhtml","html")),
          ( view:column("uri", cts:uri-reference()), 
            view:column("entityName", cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityName"]/@content',("collation=http://marklogic.com/collation/"))),
            view:column("entityStreetAddress",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityStreetAddress"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("entityCityAddress",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityCityAddress"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("entityCountryAddress",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "entityCountryAddress"]/@content',("collation=http://marklogic.com/collation//S2", ("nullable")))), 
            view:column("foreignEntityStatus",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "foreignEntityStatus"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("intermediaryEntityStatus",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "intermediaryEntityStatus"]/@content',("collation=http://marklogic.com/collation/codepoint", ("nullable")))),
            view:column("EIN",  cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "EIN"]/@content',("collation=http://marklogic.com/collation/", ("nullable")))),
            view:column("docType", cts:path-reference('/xhtml:html/xhtml:head/xhtml:meta[@name eq "docType"]/@content',("collation=http://marklogic.com/collation//S1", ("nullable"))))
          ),
          () 
      )

      (: Creates a view, of the 'main' schema that contains columns, with a scope on the element, 'html'. :)
    },
    { :db_name => @properties["ml.content-db"] }
  end

end

How To Use It

Custom build steps are implemented using Ruby functions. You can use these steps from the ml script, using the function names:

ml local create_view

Note that these functions are used with an environment.

How It Works

There are three key pieces you need to know to use this feature.

Defining a Function

Before you start editing, the deploy/app_specific.rb file looks like this:

class ServerConfig
  def my_custom_method()
    @logger.info(@properties["ml.content-db"])
  end
end

This is Ruby code. If you don't know Ruby, don't worry, you don't need to. The "class ServerConfig ... end" part of the code is a wrapper that provides some context. We'll focus on defining our custom functions.

This part of the code:

  def my_custom_method()
    ...
  end

defines a Ruby function. You can choose what to call the function, but the name should reflect what step is being done. The example above defined create_view and delete_view. Let's define a simple (but not very useful) function that tells us how many documents are in a database. We can replace my_custom_method(), so we'll start with this:

class ServerConfig
  def get_document_count()
    @logger.info(@properties["ml.content-db"])
  end
end

Note that Ruby, by convention, uses underscores to separate words.

Having declared the function, we need to add some XQuery code. The XQuery gets wrapped in %Q{ }. [TODO]

Specifying the Database Target

[TODO]

Supplementing existing Commands

In addition to adding new commands, you can make the existing commands do extra steps. Suppose you want the "deploy content" command to do something extra. Add this to deploy/app_specific.rb:

alias_method :original_deploy_content, :deploy_content
def deploy_content
  original_deploy_content

  execute_query(%Q{
    (: put your xquery here :)
  },
  :db_name => @properties["ml.app-name"])
end

This “overrides” deploy content. You can call it with:

./ml {env} deploy content
Clone this wiki locally