[moodle.git] / backup / util / ui / base_ui.class.php

<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * This file contains the backup user interface class
 *
 * @package   moodlecore
 * @copyright 2010 Sam Hemelryk
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

/**
 * This is the backup user interface class
 *
 * The backup user interface class manages the user interface and backup for
 * Moodle.
 *
 * @copyright 2010 Sam Hemelryk
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
abstract class base_ui {
    /**
     * The progress of this instance of the backup ui class
     */
    const PROGRESS_INTIAL = 0;
    const PROGRESS_PROCESSED = 1;
    const PROGRESS_SAVED = 2;
    const PROGRESS_EXECUTED = 3;
    /**
     * The controller
     * @var backup_controller|restore_controller
     */
    protected $controller;
    /**
     * The current stage
     * @var base_ui_stage
     */
    protected $stage;
    /**
     * The current progress of the UI
     * @var int One of self::PROGRESS_*
     */
    protected $progress;
    /**
     * The number of changes made by dependency enforcement
     * @var int
     */
    protected $dependencychanges = 0;

    /**
     * Yay for constructors
     * @param backup_controller $controller
     */
    public function __construct($controller, array $params=null) {
        $this->controller = $controller;
        $this->progress = self::PROGRESS_INTIAL;
        $this->stage = $this->initialise_stage(null, $params);
        // Process UI event before to be safe
        $this->controller->process_ui_event();
    }
    /**
     * Intialises what ever stage is requested. If none are requested we check
     * params for 'stage' and default to initial
     *
     * @param int|null $stage The desired stage to intialise or null for the default
     * @return base_ui_stage
     */
    abstract protected function initialise_stage($stage = null, array $params=null);
    /**
     * This processes the current stage of the backup
     * @return bool
     */
    public function process() {
        if ($this->progress >= self::PROGRESS_PROCESSED) {
            throw new backup_ui_exception('backupuialreadyprocessed');
        }
        $this->progress = self::PROGRESS_PROCESSED;

        if (optional_param('previous', false, PARAM_BOOL) && $this->stage->get_stage() > self::STAGE_INITIAL) {
            $this->stage = $this->initialise_stage($this->stage->get_prev_stage(), $this->stage->get_params());
            return false;
        }

        // Process the stage
        $processoutcome = $this->stage->process();

        if ($processoutcome !== false) {
            $this->stage = $this->initialise_stage($this->stage->get_next_stage(), $this->stage->get_params());
        }

        // Process UI event after to check changes are valid
        $this->controller->process_ui_event();
        return $processoutcome;
    }
    /**
     * Saves the backup controller.
     *
     * Once this has been called nothing else can be changed in the controller.
     *
     * @return bool
     */
    public function save_controller() {
        if ($this->progress >= self::PROGRESS_SAVED) {
            throw new base_ui_exception('backupuialreadysaved');
        }
        $this->progress = self::PROGRESS_SAVED;
        // First enforce dependencies
        $this->enforce_dependencies();
        // Process UI event after to check any changes are valid
        $this->controller->process_ui_event();
        // Save the controller
        $this->controller->save_controller();
        return true;
    }
    /**
     * Displays the UI for the backup!
     *
     * Note: The UI makes use of mforms (ewww!) thus it will automatically print
     * out the result rather than returning a string of HTML like other parts of Moodle
     *
     * @return bool
     */
    public function display() {
        if ($this->progress < self::PROGRESS_SAVED) {
            throw new base_ui_exception('backupsavebeforedisplay');
        }
        $this->stage->display();
    }
    /**
     * Gets all backup tasks from the controller
     * @return array Array of backup_task
     */
    public function get_tasks() {
        $plan = $this->controller->get_plan();
        $tasks = $plan->get_tasks();
        return $tasks;
    }
    /**
     * Gets the stage we are on
     * @return int
     */
    public function get_stage() {
        return $this->stage->get_stage();
    }
    /**
     * Gets the name of the stage we are on
     * @return string
     */
    public function get_stage_name() {
        return $this->stage->get_name();
    }
    /**
     * Gets the backup id from the controller
     * @return string
     */
    abstract public function get_uniqueid();
    /**
     * Executes the backup plan
     * @return bool
     */
    abstract public function execute();
    /**
     * Enforces dependencies on all settings. Call before save
     * @return bool True if dependencies were enforced and changes were made
     */
    protected function enforce_dependencies() {
        // Get the plan
        $plan = $this->controller->get_plan();
        // Get the tasks as a var so we can iterate by reference
        $tasks = $plan->get_tasks();
        $changes = 0;
        foreach ($tasks as &$task) {
            // Store as a var so we can iterate by reference
            $settings = $task->get_settings();
            foreach ($settings as &$setting) {
                // Get all dependencies for iteration by reference
                $dependencies = $setting->get_dependencies();
                foreach ($dependencies as &$dependency) {
                    // Enforce each dependency
                    if ($dependency->enforce()) {
                        $changes++;
                    }
                }
            }
        }
        // Store the number of settings that changed through enforcement
        $this->dependencychanges = $changes;
        return ($changes>0);
    }
    /**
     * Returns true if enforce_dependencies changed any settings
     * @return bool
     */
    public function enforce_changed_dependencies() {
        return ($this->dependencychanges > 0);
    }
    /**
     * Loads the backup controller if we are tracking one
     * @return backup_controller|false
     */
    abstract public static function load_controller($uniqueid=false);
    /**
     * Gets an array of progress bar items that can be displayed through the backup renderer.
     * @return array Array of items for the progress bar
     */
    abstract public function get_progress_bar();
    /**
     * Gets the format for the backup
     * @return int
     */
    public function get_format() {
        return $this->controller->get_format();
    }
    /**
     * Gets the type of the backup
     * @return int
     */
    public function get_type() {
        return $this->controller->get_type();
    }
    public function get_controller() {
        return $this->controller;
    }
    /**
     * Gets the ID used in creating the controller. Relates to course/section/cm
     * @return int
     */
    public function get_controller_id() {
        return $this->controller->get_id();
    }
    /**
     * Gets the requested setting
     * @param string $name
     * @return mixed
     */
    public function get_setting($name, $default = false) {
        try {
            return $this->controller->get_plan()->get_setting($name);
        } catch (Exception $e) {
            debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
            return $default;
        }
    }
    /**
     * Gets the value for the requested setting
     *
     * @param string $name
     * @return mixed
     */
    public function get_setting_value($name, $default = false) {
        try {
            return $this->controller->get_plan()->get_setting($name)->get_value();
        } catch (Exception $e) {
            debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
            return $default;
        }
    }

    abstract public function get_name();

    abstract public function get_first_stage_id();
}

/**
 * Backup user interface exception. Modelled off the backup_exception class
 */
class base_ui_exception extends backup_exception {}
Commit	Line	Data
785d6603 SH	1	<?php
	2
	3	// This file is part of Moodle - http://moodle.org/
	4	//
	5	// Moodle is free software: you can redistribute it and/or modify
	6	// it under the terms of the GNU General Public License as published by
	7	// the Free Software Foundation, either version 3 of the License, or
	8	// (at your option) any later version.
	9	//
	10	// Moodle is distributed in the hope that it will be useful,
	11	// but WITHOUT ANY WARRANTY; without even the implied warranty of
	12	// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	13	// GNU General Public License for more details.
	14	//
	15	// You should have received a copy of the GNU General Public License
	16	// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
	17
	18	/**
	19	* This file contains the backup user interface class
	20	*
	21	* @package moodlecore
	22	* @copyright 2010 Sam Hemelryk
	23	* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
	24	*/
	25
	26	/**
	27	* This is the backup user interface class
	28	*
	29	* The backup user interface class manages the user interface and backup for
	30	* Moodle.
	31	*
	32	* @copyright 2010 Sam Hemelryk
	33	* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
	34	*/
	35	abstract class base_ui {
	36	/**
	37	* The progress of this instance of the backup ui class
	38	*/
	39	const PROGRESS_INTIAL = 0;
	40	const PROGRESS_PROCESSED = 1;
	41	const PROGRESS_SAVED = 2;
	42	const PROGRESS_EXECUTED = 3;
	43	/**
	44	* The controller
	45	* @var backup_controller\|restore_controller
	46	*/
	47	protected $controller;
	48	/**
	49	* The current stage
	50	* @var base_ui_stage
	51	*/
	52	protected $stage;
	53	/**
	54	* The current progress of the UI
	55	* @var int One of self::PROGRESS_*
	56	*/
	57	protected $progress;
	58	/**
	59	* The number of changes made by dependency enforcement
	60	* @var int
	61	*/
	62	protected $dependencychanges = 0;
	63
	64	/**
65	* Yay for constructors
66	* @param backup_controller $controller
67	*/
68	public function __construct($controller, array $params=null) {
69	$this->controller = $controller;
70	$this->progress = self::PROGRESS_INTIAL;
71	$this->stage = $this->initialise_stage(null, $params);
72	// Process UI event before to be safe
73	$this->controller->process_ui_event();
74	}
75	/**
76	* Intialises what ever stage is requested. If none are requested we check
77	* params for 'stage' and default to initial
78	*
79	* @param int\|null $stage The desired stage to intialise or null for the default
80	* @return base_ui_stage
81	*/
82	abstract protected function initialise_stage($stage = null, array $params=null);
83	/**
84	* This processes the current stage of the backup
85	* @return bool
86	*/
87	public function process() {
88	if ($this->progress >= self::PROGRESS_PROCESSED) {
89	throw new backup_ui_exception('backupuialreadyprocessed');
90	}
91	$this->progress = self::PROGRESS_PROCESSED;
92
93	if (optional_param('previous', false, PARAM_BOOL) && $this->stage->get_stage() > self::STAGE_INITIAL) {
94	$this->stage = $this->initialise_stage($this->stage->get_prev_stage(), $this->stage->get_params());
95	return false;
96	}
97
98	// Process the stage
99	$processoutcome = $this->stage->process();
100
101	if ($processoutcome !== false) {
102	$this->stage = $this->initialise_stage($this->stage->get_next_stage(), $this->stage->get_params());
103	}
104
105	// Process UI event after to check changes are valid
106	$this->controller->process_ui_event();
107	return $processoutcome;
108	}
109	/**
110	* Saves the backup controller.
111	*
112	* Once this has been called nothing else can be changed in the controller.
113	*
114	* @return bool
115	*/
116	public function save_controller() {
117	if ($this->progress >= self::PROGRESS_SAVED) {
118	throw new base_ui_exception('backupuialreadysaved');
119	}
120	$this->progress = self::PROGRESS_SAVED;
121	// First enforce dependencies
122	$this->enforce_dependencies();
123	// Process UI event after to check any changes are valid
124	$this->controller->process_ui_event();
125	// Save the controller
126	$this->controller->save_controller();
127	return true;
128	}
129	/**
130	* Displays the UI for the backup!
131	*
132	* Note: The UI makes use of mforms (ewww!) thus it will automatically print
133	* out the result rather than returning a string of HTML like other parts of Moodle
134	*
135	* @return bool
136	*/
137	public function display() {
138	if ($this->progress < self::PROGRESS_SAVED) {
139	throw new base_ui_exception('backupsavebeforedisplay');
140	}
141	$this->stage->display();
142	}
143	/**
144	* Gets all backup tasks from the controller
145	* @return array Array of backup_task
146	*/
147	public function get_tasks() {
148	$plan = $this->controller->get_plan();
149	$tasks = $plan->get_tasks();
150	return $tasks;
151	}
152	/**
153	* Gets the stage we are on
154	* @return int
155	*/
156	public function get_stage() {
157	return $this->stage->get_stage();
158	}
159	/**
160	* Gets the name of the stage we are on
161	* @return string
162	*/
163	public function get_stage_name() {
164	return $this->stage->get_name();
165	}
166	/**
167	* Gets the backup id from the controller
168	* @return string
169	*/
170	abstract public function get_uniqueid();
171	/**
172	* Executes the backup plan
173	* @return bool
174	*/
175	abstract public function execute();
176	/**
177	* Enforces dependencies on all settings. Call before save
178	* @return bool True if dependencies were enforced and changes were made
179	*/
180	protected function enforce_dependencies() {
181	// Get the plan
182	$plan = $this->controller->get_plan();
183	// Get the tasks as a var so we can iterate by reference
184	$tasks = $plan->get_tasks();
185	$changes = 0;
186	foreach ($tasks as &$task) {
187	// Store as a var so we can iterate by reference
188	$settings = $task->get_settings();
189	foreach ($settings as &$setting) {
190	// Get all dependencies for iteration by reference
191	$dependencies = $setting->get_dependencies();
192	foreach ($dependencies as &$dependency) {
193	// Enforce each dependency
194	if ($dependency->enforce()) {
195	$changes++;
196	}
197	}
198	}
199	}
200	// Store the number of settings that changed through enforcement
201	$this->dependencychanges = $changes;
202	return ($changes>0);
203	}
204	/**
205	* Returns true if enforce_dependencies changed any settings
206	* @return bool
207	*/
208	public function enforce_changed_dependencies() {
209	return ($this->dependencychanges > 0);
210	}
211	/**
212	* Loads the backup controller if we are tracking one
213	* @return backup_controller\|false
214	*/
215	abstract public static function load_controller($uniqueid=false);
216	/**
217	* Gets an array of progress bar items that can be displayed through the backup renderer.
218	* @return array Array of items for the progress bar
219	*/
220	abstract public function get_progress_bar();
221	/**
222	* Gets the format for the backup
223	* @return int
224	*/
225	public function get_format() {
226	return $this->controller->get_format();
227	}
228	/**
229	* Gets the type of the backup
230	* @return int
231	*/
232	public function get_type() {
233	return $this->controller->get_type();
234	}
235	public function get_controller() {
236	return $this->controller;
237	}
238	/**
239	* Gets the ID used in creating the controller. Relates to course/section/cm
240	* @return int
241	*/
242	public function get_controller_id() {
243	return $this->controller->get_id();
244	}
245	/**
246	* Gets the requested setting
247	* @param string $name
248	* @return mixed
249	*/
250	public function get_setting($name, $default = false) {
251	try {
252	return $this->controller->get_plan()->get_setting($name);
253	} catch (Exception $e) {
254	debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
255	return $default;
256	}
257	}
258	/**
259	* Gets the value for the requested setting
260	*
261	* @param string $name
262	* @return mixed
263	*/
264	public function get_setting_value($name, $default = false) {
265	try {
266	return $this->controller->get_plan()->get_setting($name)->get_value();
267	} catch (Exception $e) {
268	debugging('Failed to find the setting: '.$name, DEBUG_DEVELOPER);
269	return $default;
270	}
271	}
272
273	abstract public function get_name();
274
275	abstract public function get_first_stage_id();
276	}
277
278	/**
279	* Backup user interface exception. Modelled off the backup_exception class
280	*/
281	class base_ui_exception extends backup_exception {}