Querying documents
This topic explains how to query instances of documents. The examples below show you how to query all of the available documents or how to query only a specific document by its ID.
NOTE: The code examples below work with the ID of the master version of the document and return the live version of the document. For more information about other scenarios, see Querying master and live versions.
- Querying a single document
- Querying documents by a document library
- Querying all documents
Querying a single document
When querying the live version of a specific document by the ID of its master version, you must perform the following:
-
Get the master version.
First, get an instance of the master version with the corresponding ID.
-
Get the live version.
The instance that corresponds to the ID argument is the master version of the document. You must get the live version explicitly.
NOTE: The live version is used only when displaying the document in a front-end scenario. If you want to manipulate the document, consider using the master version. To transfer the changes to the live version, publish the master version.
-
Return the live version.
Return the live version.
The following code queries the live version of a document by the ID of its master version.
Native API
private Document GetDocumentNativeAPI(Guid masterDocumentId)
{
LibrariesManager librariesManager = LibrariesManager.GetManager();
Document document = librariesManager.GetDocuments().Where(d => d.Id == masterDocumentId).FirstOrDefault();
if (document != null)
{
document = librariesManager.Lifecycle.GetLive(document) as Document;
}
return document;
}
First, you get an instance of the LibrariesManager class. You get the specified document by querying all documents and filtering the collection by the ID property of the document. If the document exists, you get its live version. If no live version exists (i.e. the item has not been published), you return null. Finally, you return the live version.
You can also use the following code to retrieve the document:
Document document = librariesManager.GetDocument(masterDocumentId);
Note that when the document does not exist, an exception of type ItemNotFoundException is thrown.
Fluent API
private Document GetDocumentFluentAPI(Guid masterDocumentId)
{
return App.WorkWith().Document(masterDocumentId).GetLive().Get();
}
First, you get the singular document facade of the master version with the specified ID. Then, to load the live version of the document, you call the GetLive method of the facade. Finally, to get the instance of the live version, you call the Get method.
Querying documents by a document library
To query documents by a document library, you must perform the following:
- Get the libraries manager.
Get an instance of the LibrariesManager object.
- Get the document library.
Get an instance of the specified document library. For more information, see Querying document libraries.
- Get the documents.
Get the documents by calling the Documents extension method of the DocumentLibrary instance. This extension method is located in the Telerik.Sitefinity.Modules.Libraries namespace.
TIP: Another way of getting the documents from a specific library, is to query all the documents and filter the collection by the ID of the document library. You can find an example of this approach in the next section.
Here is a code example:
Native API
public static IQueryable<Document> GetDocumentsByDocumentLibrary(Guid documentLibraryId)
{
LibrariesManager librariesManager = LibrariesManager.GetManager();
DocumentLibrary documentLibrary = librariesManager.GetDocumentLibrary(documentLibraryId);
return documentLibrary.Documents();
}
Fluent API
public static IQueryable<Document> GetDocumentsByDocumentLibraryFluentAPI(Guid documentLibraryId)
{
return App.WorkWith().DocumentLibrary(documentLibraryId).Documents().Where(d => d.Status == ContentLifecycleStatus.Live).Get();
}
Querying all documents
When querying all documents, you must perform the following:
-
Query all documents.
First, get a query of all available documents. The query includes all live, master and temp versions.
-
Filter the query.
Filter the query to return only the live versions.
-
Get the documents.
Get the filtered documents in a list.
-
Return the documents.
Return the list of documents.
The following code queries all published documents.
Native API
private List<Document> GetAllDocumentsNativeAPI()
{
LibrariesManager librariesManager = LibrariesManager.GetManager();
return librariesManager.GetDocuments().Where(d => d.Status == ContentLifecycleStatus.Live).ToList();
}
First, you get an instance of the LibrariesManager class. You query all documents, including the live, master and temp versions of each. You filter the collection to return only the live versions. Finally, you return the documents as a list.
TIP: You can filter the query to get a specific set of documents. For example, you can get the documents from a specific library:
private List<Document> GetAllDocumentsByDocumentLibraryNativeAPI(Guid documentLibraryId)
{
LibrariesManager librariesManager = LibrariesManager.GetManager();
return librariesManager.GetDocuments().Where(d => d.Status == ContentLifecycleStatus.Live && d.Parent.Id == documentLibraryId).ToList();
}
In this code example you additionally filter the collection by the ID of the parent document library.
Fluent API
private List<Document> GetAllDocumentsFluentAPI()
{
return App.WorkWith().Documents().Where(d => d.Status == ContentLifecycleStatus.Live).Get().ToList();
}
First, you get an instance of the plural documents facade. Then you get all the documents, including the live, master and temp versions of each. You filter the collection to return only the live versions. Finally, you return the documents as a list. If no documents exist or there are not any published documents, you return an empty list.
TIP: You can filter the query to get a specific set of documents. For example, you can get the documents from a specific library:
public static List<Document> GetAllDocumentsByDocumentLibraryFluentAPI(Guid documentLibraryId)
{
return App.WorkWith().Documents().Where(d => d.Library.Id == documentLibraryId && d.Status == ContentLifecycleStatus.Live).Get().ToList();
}
In this code example you use the plural facade for the documents and filter them by the ID of the specified document library. Then, you get the live versions of the selected documents.