The Pages class provides functionality for loading and manipulating page objects in Scriptor. This class also inherits all the methods and properties of the Module class.

Retrieve a Specific Page

If you need to retrieve a specific page, you can use the Pages::getPage() method:

use Scriptor\Core\Scriptor;

$pages = Scriptor::getSite()->pages();
$page = $pages->getPage('slug=my-page');

To search for a page within an array, you can pass the array as the second parameter:

$page = $site->pages()->getPage('name=My %', $pagesArray);

...which searches for a page with the name "My page", "My document", or "My whatever", etc.

The following selector operators are supported:

=          Equal to  
%word      Contains the exact word or phrase at the beginning of the field value.
word%      Contains the exact word or phrase at the end of the field value.
%word%     Contains the exact word or phrase.

You can access the page fields and attributes using this method, as well as others described below.

Select Multiple Pages

The Pages::getPages() method is useful when you want to select more than one page. It returns an array of matching objects based on a selector string:

$pages = Scriptor::getSite()->pages()->getPages('your_field_name=value');

The selector operators that can be used include:

=          Equal to.
!=         Not equal to.   
<          Less than.   
>          Greater than.   
<=         Less than or equal to.
>=         Greater than or equal to.
%word      Contains the exact word or phrase at the beginning of the field value.
word%      Contains the exact word or phrase at the end of the field value.
%word%     Contains the exact word or phrase.

For example, to retrieve all pages that do not have a hidden template assigned to them:

$pages = Scriptor::getSite()->pages();
$visible = $pages->getPages('template!=hidden');

Another example is to select all pages created later than a specific page:

$pages = Scriptor::getSite()->pages();
$page = $pages->getPage('name=Specific Page');
$createdAfter = $pages->getPages("created>$page->created");

To find all pages that have been updated after October 7, 2022:

$date = new DateTimeImmutable('2022-10-07');
$pages = $site->pages()->getPages('updated>'.$date->getTimestamp());

You can pass options as the second parameter to the getPages() method:

$options = [
    'all' => false, // Set it to true if you want to select inactive pages as well.
    'sortBy' => 'position', // Sort by attribute or field name.
    'order' => 'asc', // Sorting in ascending or descending order.
    'offset' => 0, // Specify the number of records to return.
    'length' => 0, // Specify the number of records to return.
    'items' => [] // An array of pages. Leave it empty if you want to search all pages.
];

$pages = $site->pages()->getPages('template!=hidden', $options);

Create a New Page

To add a new page, create a new Page object:

use Scriptor\Core\Page;

$page = new Page();
$page->set('name', 'My page')
    ->set('content', 'This is the page content ...')
    ->set('active', true)
    ->save();

Delete Pages

To permanently delete a page and its assets:

$site->pages()->deletePage($page, $options);

Here, $page can be a Page object or a page ID (integer) to be deleted.

The $options parameter is an array that allows you to customize the behavior. By default, if you attempt to delete a page with children and don't explicitly set the recursive argument to true, the recursive deletion fails. Other available options are clearCache (whether to clear the markup cache after delete, default=true) and force (set to true to perform the deletion despite the existence of child pages, default=false).

The method returns a boolean value, true for success and false for failure. It can throw an \ErrorException on fatal error.

If you attempt to delete a page with child pages, you may encounter a fatal error. For example:

$page = $site->pages()->getPage('name=My Page');
$result = $site->pages()->deletePage($page);

In this case, you will receive a fatal error: "Uncaught ErrorException: The operation was not approved."

You can access more information in the Site::$notes variable, which contains an array of notifications. You can retrieve them as follows:

try {
    $result = $site->pages()->deletePage($page);
} catch (\ErrorException $e) {
    var_dump('Exception: ' . $e->getMessage());  // Exception message
    var_dump($site->getNotes());  // Deletion notes
}

To delete the page and its child pages, use the recursive option:

$result = $site->pages()->deletePage($page, ['recursive' => true]);

If you want to delete only the single page, regardless of the existence of child pages, use the force option:

$result = $site->pages()->deletePage($page, ['force' => true]);

If you don't want to clear the cache every time a page is deleted, set the clearCache option to false:

$options = [
    'clearCache' => false
];

$result = $site->pages()->deletePage($page, $options);

By utilizing these methods, you can efficiently load, manipulate, create, and delete pages in Scriptor according to your requirements.