MarkLogicContext

MarkLogicContext enables FastTrack applications to connect to the MarkLogic REST API. MarkLogicContext exposes methods for performing searches, retrieving documents, setting search constraints, and more. FastTrack UI widgets do not communicate with MarkLogic directly. Instead, widgets communicate by executing methods from MarkLogicContext.

MarkLogicContext saves the responses returned from MarkLogic in state variables. Data from MarkLogic can be displayed in FastTrack applications by accessing these state variables. MarkLogicContext methods also return HTTP responses, so the application can handle them directly (if desired).

MarkLogicContext leverages React context to make the methods and variables accessible throughout a FastTrack-enabled application.

MarkLogicProvider

MarkLogicProvider is a React context provider that gives FastTrack widgets access to MarkLogicContext. After wrapping a React application component with MarkLogicProvider (see the example), all child widgets in the application can import MarkLogicContext and have access to MarkLogicContext methods and state.

MarkLogicProvider props define the connection settings for the MarkLogic backend. In a three-tier application, set the props to the connection settings for the middle-tier server of the application. 

MarkLogicProvider API

MarkLogicProvider example

import { MarkLogicProvider } from "ml-fasttrack"
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <MarkLogicProvider
    scheme="http"
    host="localhost"
    port="4001"
    options="my-options"
    auth={{ username: "theUser", password: "p4ssw0rd" }}
    debug={true}
  >
    <App />
  </MarkLogicProvider>
);

PaginationProvider

PaginationProvider is a React context provider designed to optimize performance for FastTrack widgets that use pagination functionality. This wrapper is required to enable pagination in child widgets and provides performance benefits by preventing unnecessary re-renders when other MarkLogicContext values change. After wrapping a React application component with PaginationProvider (see the example), all child widgets with pagination functionality will have access to pagination state and methods.

MarkLogicProvider example with pagination

import { MarkLogicProvider, PaginationProvider } from "ml-fasttrack"
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <MarkLogicProvider
    scheme="http"
    host="localhost"
    port="4001"
    options="my-options"
    auth={{ username: "theUser", password: "p4ssw0rd" }}
    paginationOptions={{ pageLength: 20 }}
    debug={true}
  >
    <PaginationProvider>
      <App />
    </PaginationProvider>
  </MarkLogicProvider>
);

MarkLogicContext methods

This section describes the MarkLogicContext methods.

setQtext(qtext)

This method sets the qtext search state property.

When qtext changes, MarkLogicContext executes a new /v1/search using the current context state and populates the searchResponse property with the response.

setQtext(qtext) example

context.setQtext("fast OR track");

setCollections(collections)

This method sets the collections state property. Collections allow documents to be organized into subsets. Searches can then be constrained by one or more collections. When collections changes, MarkLogicContext executes a new search using the current context state and populates the searchResponse property with the response.

setCollections(collections) example

context.setCollections(["person", "organization"]);

setDirectories(directories)

This method sets the directories state property. Directories organize documents into subsets based on paths in URIs. Searches can be constrained by directories. When the directories state property changes, MarkLogicContext executes a new search using the current context state and populates the searchResponse property with the response.

setDirectories(directories) example

context.setDirectories(["/pets/dogs/", "/pets/cats/"]);

setPageStart(index)

This method sets the index of the first result to return when executing postSearch(). It sets the start parameter for [POST /v1/search](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/POST/v1/search).

setPageStart(index) example

context.setPageStart(2);

setPageLength(length)

This method sets the number of results returned when executing postSearch().

setPageLength(length) example

context.setPageLength(20);

setOptions(name)

This method names a query options previously created via the /v1/config/query service. It sets the options parameter for [POST /v1/search](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/POST/v1/search).

setOptions(name) example

context.setOptions("myQueryOptions")

setSearchTransform(name)

This method names a search result transformation previously installed via the /config/transformsservice. It sets the transform parameter for [POST/v1/search](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/POST/v1/search). If a search response is returned, the transformation is applied to the search response.

setSearchTransform(name) example

context.setSearchTransform("myTransformFunction")

setDocumentTransform(name)

This method names a content transformation previously installed via the /config/transforms service. It sets the transform parameter for [GET /v1/documents](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/GET/v1/documents). The service applies the transformation to the document prior to constructing the response.

setDocumentTransform(name) example

context.setDocumentTransform("myTransformFunction")

postSearch(combinedQuery, parameters, config)

This method executes a call to POST /v1/search. The call returns a Promise. The Promise is fulfilled with an HTTP response when it is successful. The searchResponse state variable is also populated with the response.

postSearch(CombinedQuery, parameters) example

This example searches for documents containing the strings "fast" or "track". The example returns results, starting with the second result.

const combinedQuery = {  
  qtext: "fast OR track"
}
 
context.postSearch(combinedQuery, {start: 2}).then(response => {
  console.log(response);
})

updateSearch()

This method triggers a call to postSearch() using the search-related state variables in MarkLogicContext and the parameters defined in MarkLogicProvider. Use this method to manually trigger a search when disableSearchOnChange in MarkLogicProvider is set to true.

updateSearch() example

In this example, because disableSearchOnChange is set to true, the setQtext() method does not automatically trigger a postSearch() search as it normally would. The updateSearch() call that follows does trigger a search.

<MarkLogicProvider
  host={host}
  port="4000"
  disableSearchOnChange={true}
>
  <App />
</MarkLogicProvider>

// ...

context.setQtext("fast OR track"); // Does not trigger search
context.updateSearch();

getSuggestedSearch(partialQ, limit, config)

This method executes a call to [GET /v1/suggest](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/GET/v1/suggest). The call returns a Promise. When the response is successful, the promise is fulfilled with an HTTP response. The suggestSearchResponse state variable is also populated with the response. For more details, see [Generating Search Term Completion Suggestions](https://docs.progress.com/bundle/marklogic-server-develop-rest-api-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/search.html#id_82587).

getSuggestedSearch(partialQ, limit) example

context.getSuggestedSearch("New", 5).then(response => {
  console.log(response);
})

getDocument(uri, parameters, config)

This method executes a call to [GET /v1/documents](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/GET/v1/documents). The method returns a Promise. When the call is successful, the promise is fulfilled with an HTTP response. The document content will be in the data property of the response object. The documentResponse state variable will also be populated with the response.

getDocument(uri, parameters) example

const uri = "/person/1001.json";
 
context.getDocument(uri, {database: "my-app-db"}).then(response => {
  console.log(response);
})

getSparql(query, parameters, config)

The getSparql(query, parameters) method executes a call to [GET /v1/graphs/sparql](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/GET/v1/graphs/sparql). The next action depends on the results of the call:

• When the call is successful, a Promise is returned and the sparqlResponse state variable is populated with the response.

• If the call is unsuccessful, an error is written to the console.

getSparql(query, parameters) example

const sq = `SELECT * 
  WHERE { 
    ?s <http://xmlns.com/foaf/0.1/givenname/> ?o 
  } LIMIT 10`; 
context.getSparql(sq, {database: "ml-demo-app-content"}, 
  {headers: {'X-Example-Header': 'my-header-value'}} ).then(response => { 
  console.log(response); 
})

postSparql(combinedQuery, parameters, config)

The postSparql(combinedQuery) method executes a call to [POST /v1/graphs/sparql](https://docs.marklogic.com/12.0 # The URL of paths to some API documentation contains a dot (12.0 as opposed to 12) change this when you change 'version'/REST/POST/v1/graphs/sparql). The next action depends on the results of the call:

• When the call is successful, a Promise is returned, and the sparqlResponse state variable is populated with the response.

• If the call is unsuccessful, an error is written to the console.

postSparql (combinedQuery, parameters) example

const sq = `SELECT *
  WHERE {
    ?s <http://xmlns.com/foaf/0.1/givenname/> ?o
  } LIMIT 10`;
const combinedQuery = {  
  qtext: "fast OR track",
  sparql: sq
}
context.postSparql(combinedQuery, {database: "my-app-db"}).then(response => {
  console.log(response);
})

postChat(message, combinedQuery, parameters, config)

The postChat() method executes a call to an endpoint that responds to a chat message:

• If the call is successful, a Promise returns, and the chatResponse state variable populates with the response.
• If the call is unsuccessful, an error is written to the console.

postChat(message, combinedQuery, parameters) example

const myCombinedQuery = {
  qtext: 'suv OR crossover'
}
const myParameters={{
  host: '127.0.0.1',
  port: 4015
}}
context.postChat('What are the safest new cars?', myCombinedQuery, myParameters)
  .then((response) => {
    console.log("Response", response);
  }
);

request(config)

This method executes an HTTP request based on an Axios request configuration object. The call returns a Promise. The Promise is fulfilled with an HTTP response when it is successful. The response state variable is also populated with the response.

The request uses the scheme, host, port, and basePath values defined by MarkLogicProvider unless these values are overridden by a baseURL property in the configuration object.

request(axiosRequestConfig) example

context.request({
      url: '/v1/resources/customEndpoint',
      method: 'POST',
      data: { prop1: 'foo', prop2: 'bar' },
      headers: { 'Content-Type': 'application/json' }
}).then(response => {
  console.log(response);
})

addStringFacetConstraint(constraint)

This method adds a constraint from the StringFacet widget to the context state. When a checkbox selection is made, this method may receive the constraint object passed to the StringFacet onSelect event handler. Internally, this method sets a [range-constraint-query](https://docs.progress.com/bundle/marklogic-server-use-search-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/structured-query.html#id_38268).

addStringFacetConstraint(constraint) example

const handleFacetClick = (constraint) => {
  context.addStringFacetConstraint(constraint);
}
 
return (
  <StringFacet
    title="Status"
    name="status"
    data={context.searchResponse?.facets?.status}
    onSelect={handleFacetClick}
    reset={resetStringFacet}
  />
)

removeStringFacetConstraint(constraint)

This method removes a string facet constraint from the context state. The method may receive the constraint object passed to the SelectedFacets removeStringFacet event handler when a selected facet is removed. Internally, this method removes a [range-constraint-query](https://docs.progress.com/bundle/marklogic-server-use-search-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/structured-query.html#id_38268).

removeStringFacetConstraint(constraint) example

return (  
  <SelectedFacets
    selectedFacetConfig={{
      string: {
        color: 'red',
        closable: true,
      }
    }}
    stringFacets={context.stringFacetConstraints}
    removeStringFacet={context.removeStringFacetConstraint}
  ></SelectedFacets>
)

addRangeFacetConstraint(constraint)

The addRangeFacetConstraint(constraint) method adds a range facet constraint to the context state. The method may receive the constraint object passed to the DateRangeFacet onSelect event handler or the NumberRangeFacet and BucketRangeFacet onChange event handlers. Internally, this method sets a [range-constraint-query](https://docs.progress.com/bundle/marklogic-server-use-search-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/structured-query.html#id_38268).

addRangeFacetConstraint(constraint) example

const handleValueRange = (constraint) => {
  context.addRangeFacetConstraint(constraint);
}
 
return (
  <NumberRangeFacet
    title="Salary"
    name="salary"
    data={context?.searchResponse?.facets?.salary}
    minValue={0}
    maxValue={100000}
    onChange={handleValueRange}
  />
)

removeRangeFacetConstraint(constraint)

The removeRangeFacetConstraint(constraint) method removes a range facet constraint from the context state. The method may receive the constraint object passed to the SelectedFacets removeRangeFacet event handler when a selected facet is removed. Internally, this method removes a [range-constraint-query](https://docs.progress.com/bundle/marklogic-server-use-search-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/structured-query.html#id_38268).

removeRangeFacetConstraint(constraint) example

return (  
  <SelectedFacets
    selectedFacetConfig={{
      string: {
        color: 'red',
        closable: true,
      }
    }}
    rangeFacets={context.rangeFacetConstraints}
    removeRangeFacet={context.removeRangeFacetConstraint}
  ></SelectedFacets>
)

addGeoConstraint(geoConstraint)

This method adds a geospatial constraint to the context state.

addGeoConstraint(geoConstraint) example

const geoConstraint = {
  type: 'geo',
  lat: 'Latitude',
  lon: 'Longitude',
  parent: 'Location',
  polygon: [
    {
      point: [
        {
          latitude: 33,
          longitude: 45,
        },
        {
          latitude: 33,
          longitude: 46,
        },
        {
          latitude: 32,
          longitude: 45,
        },
        {
          latitude: 33,
          longitude: 45,
        },
      ],
    },
  ],
};
context.addGeoConstraint(geoConstraint);

addWordQueryConstraint(constraint)

This method adds a word query constraint to the context state.

addWordQueryConstraint(constraint) example

context.addWordQueryConstraint(
  {
    'json-property': 'transcript',
     text: ['dog', 'cat']
  }
)

removeWordQueryConstraint(constraint)

This method removes a word query constraint from the context state.

removeWordQueryConstraint(constraint) example

context.removeWordQueryConstraint(
  {
    'json-property': 'transcript',
     text: ['dog', 'cat']
  }
)

removeAllWordQueryConstraints()

This method removes all existing word query constraints from the context state.

removeAllWordQueryConstraints() example

context.removeAllWordQueryConstraints()

patchComment(uri, comment)

The patchComment(uri, comment) method adds a comment to a document specified by a URI. This method works with the CommentBox onSubmit event handler. The event handler receives an object representing a comment as an argument.

patchComment(uri, comment) example

const onSubmitComment = async (comment) => {
  let res = await context.patchComment("/person/1001.json", { content: comment, context: '/person/comments' })
  if (res.success === true) {
    context.getDocument(selectedUri);
  } else {
    alert('Comment submission failed')
  }
}
 
<CommentBox
  label="Comments"
  inputPlaceholder="Add a comment"
  buttonLabel="Post"
  onSubmit={(comment) => onSubmitComment(comment)}
  username="joe-user"
  imgSrc="https://example.org/joe.jpg"
  profileImage={{
    alt: 'Avatar',
    path: 'https://example.org/joe.jpg'
  }}
/>

editComment(uri, id, comment)

This method edits a comment with a given ID in a document specified by a URI. The method works with the CommentList onSaveComment event handler. The event handler receives the comment ID and an object representing the edited comment as arguments.

editComment(uri, id, config) example

const onEditComment = async (id, comment) => {
  let res = await context.editComment("/person/1001.json", id, { content: comment, context: '/person/comments/comment' })
  if (res.success !== true) {
    alert('Comment failed to be edited')
  }
}
 
<CommentList
  data={context.documentResponse}
  config={{comments: {
    path: 'data.person.comments.comment'
  }}}
  username="joe-user"
  onSaveComment={(id, comment) => onEditComment(id, comment)}
  onDeleteComment={(id) => onDeleteComment(id)}

deleteComment(uri, id, context, config)

This method deletes a comment with a given ID in a document specified by a URI. Works with the CommentList onDeleteComment event handler. The event handler receives the ID of the comment to delete as an argument.

deleteComment(uri, id, context) example

const onDeleteComment = async (id) => {
  let res = await context.deleteComment("/person/1001.json", id, '/person/comments/comment')
  if (res.success !== true) {
    alert('Comment failed to be deleted')
  }
}
 
<CommentList
  data={context.documentResponse}
  config={{comments: {
    path: 'data.person.comments.comment'
  }}}
  username="joe-user"
  onSaveComment={(id, comment) => onEditComment(id, comment)}
  onDeleteComment={(id) => onDeleteComment(id)}
/>

MarkLogicContext state variables

This section contains information on the MarkLogicContext state variables.

searchResponse

This variable contains the result of the postSearch() method.

searchResponse example

useEffect(() => {
  context.postSearch({qtext: "Alabama OR Texas"});
}, []);
 
// searchResponse
 
{
    "snippet-format": "snippet",
    "total": 2,
    "start": 1,
    "page-length": 10,
    "results": [
        {
            "index": 1,
            "uri": "/person/1002.json",
            "path": "fn:doc(\"/person/1002.json\")",
            "score": 10240,
            "confidence": 0.5028362,
            "fitness": 0.5028362,
            "href": "/v1/documents?uri=%2Fperson%2F1002.json",
            "mimetype": "application/json",
            "format": "json",
            "matches": [
                {
                    "path": "fn:doc(\"/person/1002.json\")/envelope/address/text(\"state\")",
                    "match-text": [
                        {
                            "highlight": "Texas"
                        }
                    ]
                }
            ]
        },
        {
            "index": 2,
            "uri": "/person/1003.json",
            "path": "fn:doc(\"/person/1003.json\")",
            "score": 10240,
            "confidence": 0.5028362,
            "fitness": 0.5028362,
            "href": "/v1/documents?uri=%2Fperson%2F1003.json",
            "mimetype": "application/json",
            "format": "json",
            "matches": [
                {
                    "path": "fn:doc(\"/person/1003.json\")/envelope/address/text(\"state\")",
                    "match-text": [
                        {
                            "highlight": "Alabama"
                        }
                    ]
                }
            ]
        }
    ],
    "qtext": "Alabama OR Texas",
    "metrics": {
        "query-resolution-time": "PT0.005024S",
        "snippet-resolution-time": "PT0.000615S",
        "total-time": "PT0.315651S"
    }
}

searchResponseLoading

This variable is true when the asynchronous postSearch() method has been executed and is waiting for a response and false otherwise. The variable can be checked to display a loading message during a search.

searchResponseLoading example

{ context.searchResponseLoading ? 
  <div>Loading...</div> :
  <ResultsSnippet 
    results={context.searchResponse.results}
  />
}

suggestedSearchResponse

This variable is the result of the getSuggestedSearch() method.

suggestedSearchResponse example

useEffect(() => {
  context.getSuggestedSearch("New", 5)
}, []);
 
// suggestedSearchResponse
 
{
    "suggestions": [
        "\"New Haven\"",
        "\"New York City\"",
        "Newark",
        "Newton"
    ]
}

documentResponse

This variable is the result of the getDocument() method. The object’s data property is set to the document content and the object’s uri property is set to the document URI.

documentResponse example

useEffect(() => {
  context.getDocument({"/person/1001.json", {database: "my-app-db"})
}, []);

// documentResponse

{ 
  data: {
    id: "1001",
    first: "Jane",
    last: "Smith"
  },
  uri: "/person/1001.json"
}

sparqlResponse

Result of the getSparql() or postSparql() methods.

sparqlResponse example

useEffect(() => {
  context.getSparql(`
    SELECT *
    WHERE {
    ?s ?p ?o .
    ?s <http://xmlns.com/foaf/0.1/knows/> ?o
    } LIMIT 10
  `);
}, []);
 
// sparqlResponse
 
{
    "head": {
        "vars": [
            "s",
            "p",
            "o"
        ]
    },
    "results": {
        "bindings": [
            {
                "s": {
                    "type": "uri",
                    "value": "http://example.org/1001"
                },
                "p": {
                    "type": "uri",
                    "value": "http://xmlns.com/foaf/0.1/knows/"
                },
                "o": {
                    "type": "literal",
                    "value": "1002"
                }
            },
            {
                "s": {
                    "type": "uri",
                    "value": "http://example.org/1001"
                },
                "p": {
                    "type": "uri",
                    "value": "http://xmlns.com/foaf/0.1/knows/"
                },
                "o": {
                    "type": "literal",
                    "value": "1003"
                }
            },
            {
                "s": {
                    "type": "uri",
                    "value": "http://example.org/1002"
                },
                "p": {
                    "type": "uri",
                    "value": "http://xmlns.com/foaf/0.1/knows/"
                },
                "o": {
                    "type": "literal",
                    "value": "1001"
                }
            },
            {
                "s": {
                    "type": "uri",
                    "value": "http://example.org/1003"
                },
                "p": {
                    "type": "uri",
                    "value": "http://xmlns.com/foaf/0.1/knows/"
                },
                "o": {
                    "type": "literal",
                    "value": "1001"
                }
            }
        ]
    }
}

response

This variable is the result of the request() method.

response example

useEffect(() => {
  context.request({
    url: '/v1/resources/currentTime',
    method: 'GET',
    headers: { 'Content-Type': 'application/json' }
  });
}, []);
 
// response

{ 
  currentTime:"10:22:25-07:00" 
}

stringFacetConstraints

Current string facet constraints of the context state. Constraints may be added with addStringFacetConstraint() and removed with removeStringFacetConstraint().

stringFacetConstraints example

useEffect(() => {
  context.addStringFacetConstraint([
    {
        "type": "string",
        "name": "status",
        "value": [
            "Active"
        ],
        "title": "Status"
    }
])
}, []);
 
// stringFacetConstraints
 
[
    {
        "type": "string",
        "name": "status",
        "value": [
            "Active"
        ],
        "title": "Status"
    }
]

rangeFacetConstraints

The rangeFacetConstraints state variable holds the current range facet constraints of the context state. Constraints may be added with addRangeFacetConstraint() and removed with removeRangeFacetConstraint().

rangeFacetConstraints example

useEffect(() => {
  context.addRangeFacetConstraint([
    [
        {
            "type": "number",
            "name": "salary",
            "value": 50000,
            "operator": "GE",
            "title": "Salary"
        },
        {
            "type": "number",
            "name": "salary",
            "value": 100000,
            "operator": "LE",
            "title": "Salary"
        }
    ]
  ])
}, []);
 
// rangeFacetConstraints
 
[
    [
        {
            "type": "number",
            "name": "salary",
            "value": 50000,
            "operator": "GE",
            "title": "Salary"
        },
        {
            "type": "number",
            "name": "salary",
            "value": 100000,
            "operator": "LE",
            "title": "Salary"
        }
    ]
]

wordQueryConstraints

The wordQueryConstraints state variable holds the current word query constraints of the context state. A constraint may be added with addWordQueryConstraint(). A constraint may be removed with removeWordQueryConstraint(), or all constraints may be removed at once with removeAllWordQueryConstraints().

wordQueryConstraints example

useEffect(() => {
    context.addWordQueryConstraint(
      {
          "json-property": "transcript",
          "text": ['dog', 'cat']
      })
    }, []);

// wordQueryConstraints

{
    "json-property": "transcript",
    "text": ['dog', 'cat']
}