A DesktopServer Blueprint allows you to create a WordPress installation with all of your favorite themes, frameworks, page builders, and plugins already preconfigured. A simple way to make a blueprint is to just create a website in DesktopServer and configure it the way you want (installing plugins, etc.) and exporting it to a zip archive using DesktopServer’s export option from the main menu. Unzipping the resulting folder and placing it into DesktopServer’s special ‘blueprint’ folder will make your project into an available blueprint to jump start your subsequent projects (see #1, Figure 1).

The blueprint selection screen appears when selecting DesktopServer’s ‘Create a new development website’ from the main menu and proceeding to create a new site. You can locate the blueprint folder by clicking the hyperlink on the blueprints screen (see #2, Figure 1) which will automatically open the folder in Explorer (Windows) or Finder (Macintosh). You can also locate the blueprints folder based on your operating system platform:

On Macintosh at:
/Users/Shared/.ds/blueprints

On Windows at:
C:\ProgramData\.ds\blueprints

Displaying the Blueprint

When adding a new blueprint sub-folder to the .ds/blueprints folder, DesktopServer’s services must be restarted to validate and make the blueprint available for selection. New in DesktopServer 5 is a dedicated blueprints selection screen that displays additional information about the selected blueprint. By default this information is derived from the sub-folder name that houses the blueprint, and various themes, and plugins. Screenshots come from the themes, and WordPress version information is displayed based on the blueprint’s core WordPress file contents (see Figure 2, Blueprints Selection Screen.

Further information and a proper title (rather than the folder name as default) can be displayed by supplying a blueprint with the optional blueprint.php file. Placing the blueprint.php file the blueprint sub-folder root will cause DesktopServer to parse and display the file’s header contents when selected on the DesktopServer blueprint selection screen. This header file should contain a blueprint.php file with a syntax that is very similar to the WordPress API plugin header file format. See the example code below:

<?php
/**
 * Blueprint Name: Example Blueprint
 * Blueprint URI: https://www.desktopserver.com/developer/creating-blueprints
 * Description: An example blueprint of dynamic, DesktopServer 5, features. 
 * Version: 1.0.0
 * Author: Stephen J. Carnam
 */

A dynamic DesktopServer blueprint is a PHP file called “blueprint.php” and lives within a uniquely named sub-folder inside the DesktopServer ‘blueprints’ folder (i.e. C:\ProgramFiles.ds\blueprints on Windows or /Users/Shared/.ds/blueprints on Macintosh). A dynamic blueprint is a folder containing a series of files, often WordPress core files, themes, plugins, and the blueprint.php file; serving as a template for creating a new website. The blueprint.php file may be executed as many as five times (and in different processes); it executes when displaying an optional ‘blueprint options’ page (aka bp_options.php), and during the ‘create’ website workflow. The blueprint.php file may also execute if a database is present which invokes a background ‘scub’ workflow, and also when the final creation screen appears (creating.php) that displays the newly created website’s hyperlink. When a user selects a blueprint with a valid blueprint.php file, DesktopServer furnishes the blueprint.php with a subset of the DesktopServer Plugins API action hooks. These action hooks can allow a blueprint author to further customize or modify a newly created website, and/or display custom screens and controls to the user within the DesktopServer user interface.

Blueprint Options User Interface

After the user selects a given blueprint, the blueprint.php may insert its own optional custom user interface page (aka bp_options or ‘Blueprint Options’ screen). To display the blueprint options page, the blueprint.php file simply needs to respond to the action hook, ‘ds_bp_options_title’ with a title string that will appear at the top of the page window. For our example blueprint.php file, we can supply an ‘Example Title’ (returning an empty string or not hooking the event at all omits displaying the optional page). Consider:

global $ds_runtime;
$ds_runtime->add_action(‘ds_bp_options_title’, function($title) {
  return ‘Example Title’;
});

The proceeding code will cause DesktopServer to display a mostly blank options page with next and back buttons before copying files from the selected blueprint folder and creating a new website (see figure 3 – Blueprints Options Screen). Subsequent action hooks can allow a blueprint to display additional UI elements, gather user input, and execute code after the site is created to apply selected options. The following table lists additional action hooks that will fire if the blueprint.php file has returned a title string to the initial ‘ds_bp_options_title’ action hook (see Table 1 – Blueprint Options Screen Action Hooks). It should be noted that these actions are fired in the order listed in the table below and as apart of the same process (i.e. global and procedural variables will maintain their values within these action hooks).

Action Hook	Description
ds_head_bp_options	This action hook typically contains the inside of the page’s <head> and </head> tag contents. From here, a blueprint.php file can insert references to additional CSS and script tags, and/or modify the existing header contents.
ds_card_bp_options	This action hook contains just the center area (aka card) of the customizable user interface, below the title and within a margin area in the center of the display (see figure 3 – Blueprints Options Screen).
ds_app_bp_options	This action hook contains the bulk of the body tag and center area that makes up the customizable user interface. It includes the title, and subsequent ‘ds_card_bp_options’ action hook content.
ds_actionbar_bp_options	This action hook contains the HTML markup that displays the action bar with the back and next buttons at the bottom of the screen.
ds_overlay	This action hook contains the optional overlay that may appear on top of the Blueprint Options Screen.
ds_footer_bp_options	This action hook is empty by default; it contains any markup to appear above the closing </body> tag for the ‘Blueprint Options’ screen.

The next screen in the DesktopServer user interface to be displayed is the ‘Created Website’ screen (creating.php). This screen initially appears with an overlay and progress bar while multiple background workflows will run (create workflow, scrub workflow, etc.). After workflows complete, the overlay will disappear and reveal a hyperlink to the newly created site (see Figure 4 – Created Website Screen).

Additional action hooks are fired for the ‘Created Website’ screen are executed in the order they appear in the table below; these action hooks are apart of the same, single process that displays the ‘Created Website’ screen (i.e. global and procedural variables will maintain their values within these action hooks) and are separate from the workflow processes.

Action Hook	Description
ds_created_script	This action hook allows for the injection of custom JavaScript to be executed after the website is created and the hyperlink is displayed on the screen (as depicted in Figure 4).
ds_head_creating	This action hook typically contains the inside of the page’s <head> and </head> tag contents. From here, a blueprint.php file can insert references to additional CSS and script tags, and/or modify the existing header contents.
ds_init_sidebar	The initialization function for sidebar menus. This is NOT a filter function.
ds_sidebar	The sidebar “flyout” menu; see using Extending the Navigation Bar Menus.
ds_navbar	The top navigation bar and upper right-hand user menu.
ds_app_creating	The main application title and body area, including the hyperlink of the newly created website.
ds_actionbar_creating	This action hook contains the HTML markup that displays the action bar at the bottom. The button area includes the View Sites, Close, and Next buttons.
ds_overlay	This action hook contains the overlay that appears with progress appears while the background workflow processes are running.
ds_footer_creating	This action hook is empty by default; it contains any markup to appear above the closing </body> tag for the ‘Created Website’ screen.

Blueprint Access to Workflows

Workflows are background processes that run independent of the DesktopServer user interface. The action hooks that occur during background processes may vary depending on activated plugins, set options, and conditions. A blueprint will have access to the ‘Create’ workflow, in addition to the ‘Config’ workflow. However, unless a database is present in the blueprint, the optional ‘Scrub’ workflow may or may not be invoked along with the corresponding action hooks.

The Create Workflow

The ‘Create’ workflow occurs after the ‘Created Website’ screen (creating.php) is displayed (but is hidden by an overlay).; during which an active overlay appears obfuscating the ‘Created Website’ screen, instead displaying status icons and a progress bar. The action hooks will fire in the sequence depicted in the table below. Note that plugins may alter the sequence and/or change inject additional action hook sequences/iterations. Please review the description for details.

Action Hook	Description
ds_utils_copy_folder	DS_Utlils::copy_folder invoked during the copying of files from the blueprints folder. Multiple instances of this action hook may be called to copy core files, .ds/database, and other files. Developers should examine the content of the incoming parameter to determine the significance of the action hook as it applies to your desired behavior.
ds_utils_execute_sql	DS_Utils::execute_sql invoked during the creation of a new WordPress website. At least one instance of this action hook is called during the ‘Create’ workflow to allocate a new database and user credentials for the virtually hosted website.
ds_utils_find_first_file	DS_Utils::find_first_file invoked. This action hook typically occurs one or more times to located the wp-config.php file before it is dynamically updated. If the wp-config.php cannot be found, an additional action hook is invoked to locate the wp-config-sample.php file.
ds_utils_update_wp_config	DS_Utils::update_wp_config invoked. This usually occurs when updating the database credentials, WP prefix, and randomization of the SALT values in the wp-config.php file.
ds_utils_update_preferences	DS_Utils::update_preference invoked. This action hook occurs during the ‘Create’ workflow when updating the preferences.json file.
ds_workflow_create_done	This action hook is invoked when the ‘Create’ workflow has finished.

The Config Workflow

The ‘Config’ workflow occurs when DesktopServer is ready to add the a new website to the operating system’s host file, and when it is ready to add the new website to the vhosts configuration file. These actions are followed by a cycling of the Apache web server; turning it off and then on again to read the new configuration and begin serving files over the HTTP/HTTPS protocol.

Action Hook	Description
ds_workflow_config_hosts	The operating system hosts file is copied to .ds/data/hosts and is about to be modified. The ‘Config’ workflow will append the new website domain to the hosts file. After this action is invoked; the hosts file will be copied back to the operating system under an elevated/privileged process.
ds_workflow_config_vhosts	The Apache web server’s vhosts file is copied to .ds/data/httpd-vhosts.conf and is about to be modified. The ‘Config’ workflow will append the new domain to the the Apache vhosts file along with relevant aliases, SSL certificate definitions, etc. After this action is invoked; the Apache web server will be restarted to reload the new configuration.

The Scrub Workflow

The ‘Scrub’ workflow occurs when a new site is created from a blueprint that contains a valid database (.ds/database sub-folder). The scrubbing process is a search and replace process that follows per-determined rules; namely the replacement of the original domain name the blueprint contained with new domain name specified by the user on the ‘Create new website’ screen. In addition to the domain name, a search and replace rule may also contain the original domain root folder of the native operating system; this value will need to be updated to reflect the new path of the created website. Additional rules may be added or omitted depending third party plugins that manipulate the action hook API.

Action Hook	Description
ds_utils_reload_db	DS_Utils::reload_db invoked. A blueprint will be able to hook this event only if a database is present (files within the blueprint’s .ds/database folder exists). This action signifies that a database reload is about to take place.
ds_utils_execute_sql	DS_Utils::execute_sql invoked. Multiple instances of this action hook are called during the ‘Scrub’ workflow
ds_workflow_scrub_excludes	Occurs when scrubbing is gathering files to exclude from the scrubbing process. An array of filenames to exclude is passed in as an argument.
ds_workflow_scrub_filetypes	Occurs when scrubbing is gathering files to process. An array of filetypes to include, with file patterns (i.e. *.json, etc.) is passed in as an argument.
ds_workflow_scrub_files	Occurs when scrubbing is finished gathering files. An array of all files to be scrubbed is passed in as an argument.
ds_workflow_scrub_search	Occurs when scrubbing is about to take place. An array of search strings to be replaced (must match the array length in the action hook ds_workflow_scrub_replace).
ds_workflow_scrub_replace	Occurs when scrubbing is about to take place. An array of replacement strings to be inserted (must match the array length in the action hook ds_workflow_scrub_search).
ds_workflow_scrub_done	Occurs after a search and replace scrubbing process has completed.

Useful DesktopServer API Methods in Blueprints

The following methods are highlighted for use when authoring dynamic blueprints. Additional APIs for both JavaScript (when displaying a optional blueprint options page in the DesktopServer UI), and for PHP can be located in the documented DesktopServer 5 API.

Method or Property	Description
$ds_runtime->exec( $cmd, $cd )	Executes the given bash compatible shell command within the optional given native folder. This function allows a developer to execute given command (in $cmd) as if typed on the DesktopServer Command Line Interface (DS-CLI). Access to built-in tools such as WP-CLI, composer, phpunit, etc. are accessible with this method. The optional $cd parameter can be used to specify an initial working folder.
$ds_runtime->read_session()	Provides read-only access to the JavaScript ds.session object. This object is often used in the DesktopServer UI to store form values (i.e. site root and domain name when creating a new website). It returns the temp/session.json file as a json decoded object or null if none.
$ds_runtime->preferences	This property contains the preferences file. This file contains all the sites and configuration information for DesktopServer. It is typically located on Macintosh operating systems at: /Users/Shared/.ds/data/preferences.json and on Windows operating systems at: C:\ProgramData\.ds\data\preferences.json.