Base Controller Functions

#Base Controller Actions(functions)

XQuerrail defines a base controller services that are globally applied to all model/controllers defined in a domain. The definition of these functions can be found in {framework-dir}/_framework/base/base-controller.xqy.

There are 2 concerns that are available to distinguish beteween html and rest based services. This allows REST to operate under different endpoints from html. The urls described are the basic patterns that are defined under {app-dir}/_config/routing.xml.

##REST BASIC CRUD

##/{controller}/post.(json|xml) Methods : (GET, POST)

Creates a new document based on a post body in either json or xml.

###Query Parameters: body a body that is structured according to the domain model. The response body can either be an xml or json.

/countries/post.json
[Header :Content-Type application/json]
{
  code:'KB',
  displayName : 'Kurblakistan',
  aliasCode : [
    "Evil Nation"
  ]
}

####JSON

{
    "uuid": "72434cdd-e987-bb58-7c3e-c75e52c7f35894c437bf",
    "create-user": "admin",
    "created": "2014-09-10T08:46:13.046-04:00",
    "code": "KB",
    "displayName": "Kurblakistan",
    "aliasCode": [
        "Evil Nation",
        "666"
    ],
    "locale": {
        "text": "",
        "id": "",
        "type": ""
    }
}

##/{controller}/put.(json|xml) Methods : (GET, POST) Updates new document based on a post body in either json or xml. The body must have the identity or key field defined or system will throw exception that document does not exist

###Query Parameters:

partial= Set whether the update is a partial update. This is mode is helpful when updating a subset of the instance fields
body a body that is structured according to the domain model. The response body can either be an xml or json.

####Example

/countries/put.json
[Header :Content-Type application/json]
{
  code:'KB',
  displayName : 'Kurblakistan',
  aliasCode : [
    "Evil Nation"
  ]
}

####JSON

{
    "uuid": "72434cdd-e987-bb58-7c3e-c75e52c7f35894c437bf",
    "create-user": "admin",
    "created": "2014-09-10T08:46:13.046-04:00",
    "code": "KB",
    "displayName": "Kurblakistan",
    "aliasCode": [
        "Evil Nation",
        "666"
    ],
    "locale": {
        "text": "",
        "id": "",
        "type": ""
    }
}

##/{controller}/get.(json|xml) Methods : (GET, POST)

Returns an model instance by its key field

###Query Parameters: {keyField}= The keyfield is defined on the model definition as either a <model/> @key or @keyLabel property field.

####Example:

/countries/get.json?uuid=72434cdd-e987-bb58-7c3e-c75e52c7f35894c437bf

####JSON

{
    "uuid": "72434cdd-e987-bb58-7c3e-c75e52c7f35894c437bf",
    "create-user": "admin",
    "created": "2014-09-10T08:46:13.046-04:00",
    "code": "KB",
    "displayName": "Kurblakistan",
    "aliasCode": [
        "Evil Nation",
        "666"
    ],
    "locale": {
        "text": "",
        "id": "",
        "type": ""
    }
}

##/{controller}/delete.(json|xml) Methods : (GET, POST, DELETE)

Returns an model instance by its key field

####Query Parameters: {keyField}= The keyfield is defined on the model definition as either a <model/> @key or @keyLabel property field>.

####Example

/countries/delete.json?uuid=72434cdd-e987-bb58-7c3e-c75e52c7f35894c437bf

#REST Extension Services

##/{controller}/list.(json|xml) Methods : (GET, POST)

Returns a paged list result from a controller endpoint.

###Query Parameters:

Pagination:

rows= Number of results to return (Default:50)
page= Sets the return of the nth records defined from the start (Default:1)
start= start to return from index (Default:1)
all= Returns all the results if the list.

Sorting:

sidx= Returns the sort order of the list.
sord= Returns the default order of the search result.

Filtering :

{fieldname}= Filters all the results by the value specified. By default all parameters matched by a fieldname will be and'ed together.
searchField= Name of the field to filter by
searchOper= Operator to filter results (eq = Equals, ne = Not Equals, lt = "Less Than")
searchString= String

###Examples:

/countries/list.json?all=true //Returns all results (WARNING!!! use for models representing small resultsets
[Pagination]
/countries/list.json?rows=200&page=2&start=10 //returns the 200 rows per page from page 2 and starts at 10th record

[Sorting]
/countries/list.json?sidx=name&sord=descending

[Filtering]
/states/list.json?country=US //Returns only states that whose country field is = US
/states/list.json?searchField=country&searchOper=bw&searchString=M //Returns all states that begin with M

####JSON Output

{
    "type": "country",
    "elapsed": "PT0.102S",
    "currentpage": 1,
    "pagesize": 50,
    "totalpages": 5,
    "totalrecords": 250,
    "country": [{
       "uuid": "4af528b4-5c61-b68f-3fba-62bbd29c32f56ee89c41",
       "create-user": "admin",
       "created": "2014-06-09T16:41:56.996-04:00",
       ...
      }, (more results)
    ]
}

####XML Output

<list xmlns="{content-namespace}" type="country" elapsed="PT0.096S">
        <currentpage xmlns="">1</currentpage>
        <pagesize xmlns="">50</pagesize>
        <totalpages xmlns="">5</totalpages>
        <totalrecords xmlns="">250</totalrecords>
        <country xsi:type="country">
            <uuid>4af528b4-5c61-b68f-3fba-62bbd29c32f56ee89c41</uuid>
            <create-user>admin</create-user>
            <created>2014-06-09T16:41:56.996-04:00</created>
            <code>AF</code>
            <displayName>Afghanistan</displayName>
            <aliasCode>AF</aliasCode>
            <aliasCode>AFG</aliasCode>
            <aliasCode>4</aliasCode>
            <aliasCode>Afghanistan</aliasCode>
            <locale ref-type="model" 
                    ref-uuid="74ef1396-ace5-5fb1-2713-4bb018bd146971dbe3d2" 
                    ref-id="74ef1396-ace5-5fb1-2713-4bb018bd146971dbe3d2" 
                    ref="locale">en-gb</locale>
        </country>

##{controller}/lookup.(json|xml)

Methods : (GET, POST)

Returns a list of suggestions based on search configuration

###Query Parameters:

General:

Sorting:

sidx= Returns the sort order of the list.
sord= Returns the default order of the search result.
all= Returns all the results if the list.

####Examples URLs:

/countries/lookup.json
/countries/lookup.xml

####JSON

{
    "lookups": [{
        "key": "77a4261b-2cc4-0515-e6ce-c585846c1d165e3984b2",
        "label": "AD"
    }, {
        "key": "9bbb210a-d4c6-1539-4e88-afb23c99e8de59e866fd",  
        "label": "AE"
    }]
}

####XML

<lookups type="country">
    <lookup>
        <key>77a4261b-2cc4-0515-e6ce-c585846c1d165e3984b2</key>
        <label>AD</label>
    </lookup>
    <lookup>
        <key>9bbb210a-d4c6-1539-4e88-afb23c99e8de59e866fd</key>
        <label>AE</label>
    </lookup>
</lookups>

##/search.(json|xml) Methods : (GET, POST)

Returns a search result based on MarkLogic search:search

###Query Parameters:

General:

query= A search query string to pass to module ex "foo" or {fieldname}:"some-value"
sort= The field to sortBy (must have domain:navigation/@sortable=true
sort-order= Order of sort either (ascending or descending)
ps= Page Size for returned search results (Default:20)
pg= Page of results to return (Default:1)

###/{controller}/suggest.(json|xml)

Methods : (GET, POST)

Returns a list of suggestions based on search configuration. The parameters follow conventions from search:suggest definition[http://docs.marklogic.com/search:search]

###Query Parameters:

General:

Sorting:

query= String to return suggestions against.
limit= Returns the default order of the search result.
position= Returns all the results if the list.
focus= Focus of the current

####Examples:

####JSON

{
    "suggest": [
        "uuid:",
        "create-user:",
        "created:",
        "code:",
        "displayName:",
        "aliasCode:",
        "locale:",
        "sort:"
    ]
}

####XML

    <s>
        <t>uuid:</t>
        <t>create-user:</t>
        <t>created:</t>
        <t>code:</t>
        <t>displayName:</t>
        <t>aliasCode:</t>
        <t>locale:</t>
        <t>sort:</t>
    </s>

###/{controller}/schema.(json|xml) ####Methods : (POST|GET)

Returns the schema definition of a model

####Examples:

/**/
/countries/schema.json

####JSON

{"model": {
    "name": "country",
    "label": "Countries",
    "persistence": "document",
    "extends": "lookupBase",
    "key": "uuid",
    "keyLabel": "code",
    "class": "lookup",
    "navigation": {
        "importable": "true",
        "exportable": "true",
        "sortField": "displayName",
        "sortable": "true",
        "sortOrder": "ascending"
    },
    "document": {
        "uri": "/lookup/countries.xml",
        "root": "countries"
    },
    "fields": [
        {
            "__type": "element",
            "keyId": "code__c4ecba5df2f75de24da4d0bce4d2186c",
            "keyName": "code",
            "name": "code",
            "type": "string",
            "label": "Code",
            "navigation": {
                "sortable": "true",
                "newable": "true",
                "editable": "false",
                "exportable": "true",
                "suggestable": "true"
            },
            "constraint": {"required": "true"},
            "ui": {"colWidth": "400"}
        },
        {
            "__type": "element",
            "keyId": "displayName__4fd27f130c350f2c4d13745ac39c171a",
            "keyName": "displayName",
            "name": "displayName",
            "type": "string",
            "label": "Display Name",
            "navigation": {
                "sortable": "true",
                "exportable": "true",
                "suggestable": "true",
                "searchable": "true"
            },
            "ui": {"colWidth": "400"}
        },
        {
            "__type": "element",
            "keyId": "aliasCode__8b88aa3344e571e74422f2fb81a93c62",
            "keyName": "aliasCode",
            "name": "aliasCode",
            "type": "string",
            "label": "Alias Code",
            "occurrence": "*",
            "navigation": {"exportable": "true"},
            "ui": {"colWidth": "600"}
        },
        {
            "__type": "element",
            "keyId": "locale__4e5fa4e19428554708e863d00d1f0ff7",
            "keyName": "locale",
            "name": "locale",
            "type": "reference",
            "reference": "model:locale:reference",
            "label": "Locale",
            "options": [
                {
                    "label": "de",
                    "value": "ced06a48-98a2-1775-e8f6-517c20cf99a434b60675"
                },
                {
                    "label": "en",
                    "value": "d3ccb106-c111-4164-e071-1a369be9a10fd31e72d8"
                },
                {
                    "label": "en-gb",
                    "value": "74ef1396-ace5-5fb1-2713-4bb018bd146971dbe3d2"
                }
            ]
        }
    ],
    "optionlists": [],
    "controller": {
        "name": "countries",
        "model": "country",
        "label": "Country",
        "class": "lookup"
    }
}}

##HTML Services

###/{controller}/index.html Methods : (GET, POST)

Returns the html index page usually defined for list of model instances. The output is dependent on the return and the view associated with the index.

####Query Parameters:

_partial= Returns only the view of the page without any template
_debug= Returns debug output to evaluate issues with the page or request/response

###/{controller}/new.html

Methods : (GET, POST)

Returns an HTML form to support the creation of a new model instance.

####Query Parameters:

_partial= Returns only the view of the page without any template
_debug= Returns debug output to evaluate issues with the page or request/response

###/{controller}/save.html Methods : (GET, POST)

Saves the response of either a form specified via new/edit html.

####Query Parameters:

body - A POST Body using html encoded form
_partial= Returns only the view of the page without any template
_debug= Returns debug output to evaluate issues with the page or request/response`

###/{controller}/remove.html Methods : (GET, POST)

Deletes the current instance by its ID or "key" field and returns the form back to the index.

####Query Parameters:

{key or identity field}= - A POST Body using html encoded form
_partial= Returns only the view of the page without any template
_debug= Returns debug output to evaluate issues with the page or request/response`

###/{controller}/details.html

Methods : (GET, POST)

Returns the details html view defined by the view. The default view is to return a readonly form view.

####Query Parameters:

{key or identity field}= A POST Body using html encoded form
_partial= Returns only the view of the page without any template
_debug= Returns debug output to evaluate issues with the page or request/response`

###/{controller}/fields.html Methods : (GET, POST)

Returns the form element of fields without any template outer content.

####Query Parameters:

_debug= Returns debug output to evaluate issues with the page or request/response`

###/{controller}/binary(json|xml) Methods : (GET,POST)

Returns the binary output of the field definition. Since files can have multiple binary fields you must call the binary representation by its field name.

####Parameters

{key field}= The field defined as the key or identity of the model.
{binary field name}= Name of the binary field to retrieve.

####Example Consider the definition of the following domain model. A POST to /resource/save.html with multipart/mime for JellyFish.jpg will add binary and create the appropriate reference.

<!--Model Definition-->
<model name="resource" label="Resources" extends="base" persistence="directory" key="uuid" keyLabel="uuid">
    <directory>/resources/</directory>
     <element name="fileName" type="string"></element>
     <element name="resourceFile" type="binary" fileURI="/resources/images/$(uuid)/binary"/>
  </model>

The Resource output is a graph with resourceFile set to JellyFish.jpg. The binary is stored under the URI defined by the fileURI attribute

<resource>
    <uuid>f8c733ab-9257-62e7-c7d8-438ad918a035b34b52fa</uuid>
    ...
    <resourceFile type="binary" content-type="image/jpeg" filename="Jellyfish.jpg" filesize="775702">
        /resources/images/f8c733ab-9257-62e7-c7d8-438ad918a035b34b52fa/binary
    </resourceFile>
</resource>

To Extract the binary #####Examples URI:

http://localhost:9100/resource/binary.xml?uuid=f8c733ab-9257-62e7-c7d8-438ad918a035b34b52fa&name=resourceFile

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Base Controller Functions

Pagination:

Sorting:

Filtering :

General:

Sorting:

General:

General:

Sorting:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally