The Component Class

The Component Class is the base class from which most components are extended. This class contains a core set of methods which can be overwritten, as well as methods critical to system processes. This document describes how to use the Component class methods and properties to interact with the Nestor system.

Nestor provides a robust scaffolding onto which you can build features in your component to plug into the system at multiple execution points. There are also many opportunities to invoke a custom component method using system hooks. Refer to the Hooks section for more details about using hooks. Also, the Page Build process section refers to a series of flow diagrams that map the main processes executed to build a page. These diagrams visually depict where hooks are invoked throughout the Page Build process, as well as how the Component class methods and properties interact with the Nestor Core Engine classes.

Properties

There are no properties set directly in the base Component class. Properties are assigned to the component in a few different ways:

Properties that you assign programmatically. The most common way to add them is to put them in the properties array in the component_info() method.
The parent/child/sibling relationships recorded in the [your_db]_components table are added to components in the global $page object component array during Page Build.
Properties assigned when the component is added to a Recipe using the Manage Recipes page, stored in the database.
Properties assigned when a component is installed, activated or deleted using the Manage Components page, stored in the database.

Name	Type	Description
$component_id	Int	Component ID from the [your_db]_components table. Specifies a particular component associated with a page. There can be many instances of components with the same component type in the [your_db]_components table
$parent_id	Int	Parent ID from the [your_db]_components table. Component will have a parent if it’s nested under another component in a Recipe, or has been added to a page by an end user
$sequence	Int	The order in which this component is rendered on a page, related to other components on the same page. From the [your_db]_components table.
$url	String	The url property is only assigned if this component is an “anchor” in a recipe. This value specifies the path used to load the page, and is stored in the [your_db] _components table.
$recipe	String	JSON encoded string that represents the Recipe for a page. This will be added to the component if it’s an “anchor” for a Recipe. From the [your_db]_components_meta table.
$created_at	String	Timestamp that represents when the component was installed from the Manage Components page. From the[your_db]_components_meta table.
$created_by	String	ID of the user that created the component. From the [your_db]_components_meta table.
$title	String	Title that is set in component properties when it’s added to a Recipe. Shows up in various areas of the page UX. From the [your_db]_components_meta table.
$type	String	Name of the class from which this component is created. From the [your_db]_components_meta table.
$template	String	Specifies a template if this component uses any template other than the default. From the [your_db] _components_meta table.
[key]	String	Other key/value pairs associated with this component found in the [your_db]_components_meta table. Examples are class-specific role permissions. Can be assigned in component_info() or other component methods.

Color Key:

Purple – values that every component will have, normally from the database

Orange – values that a component may have, source indicated in the description

Methods

Name/Syntax	Description
activated ( )	Called when the component is activated
add_component ($each_recipe_component, $vce)	Creates and adds the HTML content to allow an end user to add a component of this type to the page
add_component_finish ($each_component, $vce)	Creates the HTML content to bookend the add_component( ) content.
allow_sub_components ($each_component, $vce)	Checks that sub_components listed in recipe are allowed to be created.
as_content ($each_component, $vce)	Adds HTML content that will be rendered on the page. Omitting will cause errors in page build
as_content_finish ($each_component, $vce)	Book end of as_content.
as_link ($each_component, $vce) ***	Create a link to represent component on a page, links to the component rendered content on a separate page
auto_created (new_component)	Protected function, called after a component has been auto_created
build_sub_components ($each_component, $vce)	Check if page object should build sub_components for this component
check_access ($each_component, $vce)	Check to see if this component should be displayed.
checkurl ($input)	Protected function
component_configuration ( )	Creates unique configuration fields that appear on the Manage Components page for this component.
component_info ( )	Returns an array with basic info about the component. Omitting the basic properties will cause issues with your component
create ($input)	Protected function, calls self::create_component method to create a component and any associated auto-create components
create_component ($input)	Protected function, creates component by adding database records, also creates any auto-create forward or reverse components associated with this component
delete ($input)	Protected function, calls delete_component method to delete all traces of component from the system.
delete_component ($input)	Protected function, checks that we’re deleting correct component, finds parent url, and calls extirpate to delete component, its children, and all associated meta-data.
disabled ( )	Called when the component is disabled
edit_component ($each_component, $vce)	Create content to allow an end user to edit component properties on a page.
extirpate_component ($component_id)	Protected function, deletes component, its children, and all associated meta-data.
find_sub_components ($requested_component, $vce, $components, $sub_components)	Determines if get_sub_components method should be called for this component during Page Build
form_input ($input)	Processes input from a form submission. Will decrypt the dossier and route form data to the class/method indicated in the dossier.
installed ( )	Called when the component is installed
preload_component ( )	Called when component is pre-loaded during build process. Can use to add your custom method to a system hook
Static recipe_components ($each_component, $vce, $auto_create_reverse = null)	Goes through the recipe and creates the components.
recipe_fields ($recipe)	Adds component fields used in ManageRecipes
recipe_manifestation ($each_recipe_component, $vce)	Allows for content to be displayed when component is contained within the recipe, regardless if a component was created. This is a ghostly apparition of a sub recipe item.
recipe_manifestation_finish ($each_recipe_component, $vce)	Closes the content to be displayed when component is contained within the recipe, regardless if a component was created. This is a ghostly apparition bookend for recipe_manifestation and occures after sub_component item
revise_component ($each_component, $vce)	Creates dossiers that are used by the edit component form on a page, then calls self::edit_component().
removed ( )	Called when the component is deleted
update ($input)	Protected function, Kicks off the process to update a component.
update_component ($input)	Protected function, updates the component and data passed in the $input array

Method Details

Activated

Method that is called when the component is activated. Method is empty in the base class and is meant to be overwritten. The activated() method is invoked when a component is activated using the Manage Components page included with the basic Nestor Install.

activated()

Parameters

No parameters

Return

No return values

Example – Overwriting this method

In this example the method creates an empty index.php file, if it doesn’t already exist, when this component is activated.

public function activated() {
  $mpx_directory = 'mpx';
  $mpx_path = BASEPATH . $mpx_directory;
  if (!file_exists($mpx_path)) {
    mkdir($mpx_path);
    $content = "/* empty file */";
    $fp = fopen($mpx_path . "/index.php","wb");
    fwrite($fp,$content);
    fclose($fp);
  }
}

Add Component

Create the HTML content that will be added to allow an end user to add a component of this type to the page.

add_component ($each_recipe_component, $vce)

Parameters

$each_recipe_component	Object	The recipe component for which you are creating content
$vce	Object	The global $vce object, passed for convenience

Return

No return values

Example – Calling the function

add_component() is called from the Component recipe_components() method.

this_component->add_component((object) $each_recipe_component, $vce);

Example – Overwriting this function

This example shows how to create and add a dossier to a form for submission. To learn more about dossiers and the form input/submission setup, visit the Form Submission section.

$dossier_for_create = $vce->generate_dossier($recipe_component->dossier);

// create dossier for checkurl functionality
$dossier = array('type' => $recipe_component->type, 'procedure' => 'checkurl' );

// add dossier, which is an encrypted json object of details uses in the form

$dossier_for_checkurl = $vce->generate_dossier($dossier);
$content =
<<<EOF
<div class="clickbar-container admin-container add-container">
<div class="clickbar-content">
<form id="create_items" class="asynchronous-form" method="post" action="$vce->input_path" autocomplete="off">
<input type="hidden" name="dossier" value="$dossier_for_create">
<label>
<input id="create-title" type="text" name="title" tag="required" autocomplete="off">
<div class="label-text">
<div class="label-message"> Name of $recipe_component->title</div>
<div class="label-error">Enter a Title</div>
</div>
</label>
<label>
<input class="check-url" type="text" name="url" value="" parent_url="$recipe_component->parent_url/" dossier="$dossier_for_checkurl" tag="required" autocomplete="off">
<div class="label-text">
<div class="label-message">URL</div>
<div class="label-error">Enter a URL</div>
</div>
</label>
<input type="submit" value="Create">
</form>
</div>
<div class="clickbar-title clickbar-closed"><span>Add A New $recipe_component->title</span></div>
</div>
EOF;

$vce->content->add('main', $content); }

Add Component Finish

Create the HTML content to bookend the add_component( ) content.

add_component_finish ($each_component, $vce)

Parameters

$each_recipe_component	Object	The recipe component for which you are creating content
$vce	Object	The global vce object, passed for convenience

Return

No return values

Example – Calling the function

Add_component_finish() is called from the Page build_content() method, near the end of each component processing cycle.

// call book end for recipe_components, similar to as_content_finish

$previous_component->add_component_finish($each_component, $this);

Example – Overwriting the function

In the Comments component, if there are exiting comments at this level, then "Add Comments" would be placed under comments.

public function add_component_finish($each_component, $vce) {
  // check for special property main_*parent_id*
  $add_component = 'main_' . $each_component->component_id;   if (!empty($vce->content->$add_component)) {
    $vce->content->add('main',
    $vce->content->$add_component);
   }
}

Allow Sub Components

Checks that sub_components listed in recipe are allowed to be created. Called during the Page Build process to see if recipe_components should be called for the component being processed.

allow_sub_components($each_component, $vce)

Parameters

$each_component	Object	A component that can be used to generate content. Generally, this is the component currently being processed by $page during the Page Build process. It originates from the page component array.
$vce	Object	The global $vce object, passed for convenience.

Return

Boolean

Return true if sub_components under $each component can be built out, false if they should not be built out. Returns true by default.

Example – Calling the method

if ($this_component->allow_sub_components($each_component, $vce)) {
$this_component->recipe_components($each_component, $vce);
}

Example – Overwriting the method

In this example, the component has set a limit of how many sub_components can be rendered. When this number is reached, allow_sub_components returns false.

public function allow_sub_components($each_component, $vce){
  if (isset($each_component->components) && isset($each_component->components_limit)) {
    if (count($each_component->components) >= $each_component->components_limit) {
      return false;
    }
  }
  return true;
}

As Content

Allows you to add HTML content to the page. This method must contain code to add your content to the global $content object. as_content( ) is called during the page build process, so is a critical function for your custom component. Removing this function from your class file will cause errors. Also, if the method returns false, the page build process will be halted after outputting the content added to the global $content object by this method.

as_content ($each_component, $vce)

Parameters

$each_component	Object	A component that can be used to generate content. Generally, this is the component currently being processed by $page during the Page Build process. It originates from the page component array.
$vce	Object	The global $vce object, passed for convenience. Can be used to access the global $content object.

Return

boolean

Only use if you want to stop the page build process, in which case return false. By default no return.

Example – Calling this method

//if user has permission to view content, display component content

if ($this_component->check_access($each_component, $vce)) {
$as_content = $this_component->as_content($each_component, $vce);
}

Example – Overwriting this method

public function as_content($each_component, $vce) {
$my_content = "Blog-o-rama is loaded!";
$vce->content->add('main', "My content: " . $my_content);
}

As Content Finish

Allows you to add “bookend” HTML content to the page. This is called near the end of the build_content( ) method in Page, and provides a way to add content after recipe components are created.

as_content_finish ($each_component, $vce)

Parameters

$each_component	Object	A component that can be used to generate content. Generally, this is the component currently being processed by $page during the Page Build process. It originates from the page component array.
$vce	Object	The global $vce object, passed for convenience. Can be used to access the global $content object.

Return

No return value by default

Example – Calling this method

$this_component->as_content_finish($each_component, $vce);

Example – Overwriting this method

public function as_content_finish($each_component, $vce) {
$vce->content->add('main','</div>');
}

As Link

Create a link to represent component on a page, links to the component rendered content on a separate page. Then adds this link to the content object for page rendering. This can happen in a Recipe with nested URLs – this component has an associated URL but a previous component with a URL was the requested id.

as_link($each_component, $vce)

Parameters

$each_component

Object

Instance of component for which you are generating an HTML link

Return

Boolean

Return false if…

Example – Calling the Method

While building content for the page, the $page object checks each component in the hierarchy after the requested component. If a subordinate component has its own URL, $page generates a link to this component’s page instead of rendering its content.

$this_component->as_link($each_component, $vce);

Example – Overwriting the Method

The default method in Component generates a simple HTML link. You could overwrite this to provide more information, add a graphic, or customize as you wish.

public function as_link($each_component, $vce) {
   $title = “Click here for a really cool page”;
   $vce->content->main .= '<div class="items-link">
  <a href="' . $vce->site_url . '/' . $each_component->url . '">' . $title . '</a></div>' . PHP_EOL;
}

Auto Created

This function is called after a component has been auto-created. Empty in parent Component class, meant to be overwritten. Is called in the $auto_create_components anonymous function within the create_component method, after the auto-create component is created.

auto_created($new_component)

Parameters

$new_component

Array

Array containing properties of component which has been created.

Return

No return values by default

Example – Calling the Method

When components are auto-created in the create_component method, auto-created is called from the Class type of the component that has been created.

$new_component['type']::auto_created($new_component);

Build Sub Components

Check if page object should build sub_components for this component during the Page Build Process. Building involves creating and displaying content.

build_sub_components ($each_component, $vce)

Parameters

$each_component	Object	A component that can be used to generate content. Generally, this is the component currently being processed by $page during the Page Build process. It originates from the page component array.
$vce	Object	The global $vce object, passed for convenience.

Return

Boolean

Return true if sub_components under $each component can be built out, false if they should not be built out. Returns true by default.

Example – Calling the method

/* Called in Page class, in the build_content() method. Determines if recursive calls should be ** made to build out sub-components for the current component */

if ($this_component->build_sub_components($each_component, $vce)) {
// recursive call for sub component

self::build_content($sub_components, $recipe, $requested_id, $linked, $recipe_tracker);
}

Example – Overwriting the method

// only show sub-components if current user created the component, meaning they added it to the page

public function build_sub_components($each_component, $vce) {
  if ($each_component->created_by == $vce->user->user_id) {
    return true;
  }
return false;
}

Check Access

Checks to see if this component should be displayed. This is fired within class.page.php in build_content(). Also, if you would like to add something to the $page object that can be used by sub_components, this would be where to add that sort of thing $vce->page->key = "value".

check_access($each_component, $vce)

Parameters

$each_component	Object	The current component being processed by Page
$vce	Object	Global $vce object, passed for convenience

Return

Boolean

Returns true by default. If this function returns false, content will not be built for this component

Example – Calling the method

//if a component’s check_access() returns true, then display content if ($this_component->check_access($each_component, $vce) {
$as_content = $this_component->as_content($each_component, $vce);
}

Example – Overwriting the method

//check that user has role that will allow access

public function check_access($each_component, $vce) {
  global $user;
  if (isset($user->role_id)) {
    // check if user_id is in role_access
    if (!in_array($user->role_id, explode('|',$each_component->role_access))) {
       return false;
    }
  } else {
    // no user role.
    if (count($each_component->role_access)) {
      return false;
    }
  }
  return true;
}

Check URL

Checks that a url has not already been assigned to another component. In most cases this is used when the component is added, and the $input array passed is data entered into form fields when the component is created.

checkurl($input)

Parameters

$input	Array	Array that contains value of url to check
Required member of $input Array
url	String	URL value to check for

Return

No return value, display response from AJAX call

Example – Calling the method

$input = array("url"=>"blogorama");
checkurl($input);

Component Configuration

Creates unique configuration fields that appear on the Manage Components page for this component. When this method is left in the default state of returning false, the component will not be available to add to a recipe. The parent Component method is empty so this method will need to be fleshed out for any custom component that you want to be configurable in Manage Components.

component_configuration()

Parameters

No default parameters

Return

Boolean	Returns false by default, which will prevent ManageComponents from adding the configuration element to this component (prevent a component from being available to add to a recipe)
String	Returns HTML content to create unique configuration fields for this component

Example – Calling this Method

When ManageComponents builds out the Manage Components page, it looks at each component and checks if the component is active and if it returns anything besides false from component_configuration. If content is returned, that content is added to an expandable configuration area that contains these unique configuration fields.

Notice that this code block creates a dossier called “$dossier_for_configure”. When this form is submitted, this dossier routes the submitted data to a method called “configure” in the ManageComponents class. This method encrypts a json-encoded string that represents all input, and inserts this into the [your_db]_site_meta table.

Refer to the Form Submission section for more information.

if (isset($activated_components[$type]) && $fields = $current_component->component_configuration()) {
  $dossier_for_configure = $vce->user->encryption(json_encode(array('type' => 'ManageComponents',
     'procedure' => 'configure', 'component' =>$type)),$vce->user->session_vector);
  $content .=
<<<EOF <div class="clickbar-container">
<div class="clickbar-content">
<form id="$type-configuration"class="configure-component" method="post" action="$vce->input_path" autocomplete="off">
<input type="hidden" name="dossier" value="$dossier_for_configure">
EOF;

  $content .= $fields;
  $content .=
<<<EOF
<input type="submit" value="Save">
</form>
</div>
<div class="clickbar-title clickbar-closed"><span>Configure</span></div>
</div>
EOF;
}

Example – Overwriting this Method

The Blog-o-rama component has code to add configuration elements to allow a user to submit an author alias. This example receives data from the user but doesn’t display any previously submitted data. Note it doesn’t associate data with a specific user.

On submission, the configure() method in the ManageComponents class encrypts a json-encoded string that represents all field input, and inserts this into the [your_db]_site_meta table. You would need to retrieve and decrypt this string and use it in this method to reflect any user-submitted data.

public function component_configuration() {
  global $vce;
  $author_alias = $vce->user->first_name;
  $elements =
<<<EOF
<label>
<input type="text" name="author_alias" value="$author_alias" autocomplete="off">
<div class="label-text">
<div class="label-message">Author Alias</div>
<div class="label-error">Enter Your Author Alias</div>
</div>
</label>
EOF;
  return $elements;
}

Component Info

Returns an array with basic info about the component. This array has an optional array of permissions - see the Site Roles section in the Site Class API for more information about how these are set and used in the Nestor system. You can extend this method to add custom properties to your component by adding key/value pairs to the return array.

component_info()

Parameters

No parameters

Return array

	Array	Contains basic info about the component
Potential members of the returned array
name	String	Name of the Component
description	String	Description of the Component
category	String	Component category in which the Component belongs. This can be used to filter views of the components; an example is the Manage Components Page installed with Nestor.
[key]	String	Any key/value pairs that you add to the return array to customize your component
permissions	Array (Optional)	Assigns unique permissions to Site roles; these permissions will be defined in and used by your Component.
Values set in component info permissions array
name	String		Name of the unique permission
description	String		Description of how this permission is used
type	String (Optional)		If set to ‘singular’, role options will be shown as radio buttons. If not set to ‘singular’, options will have check boxes.

Example - Calling this method

//call component_info() from as_content() function of the same class

public function as_content($each_component, $vce) {
$my_content = $this->component_info();
$vce->content->add('main', "My content: " . var_dump($my_content));
}

Example - Overwriting this method

//alter return array in component_info()

public function component_info() {
  return array(
  'name' => 'Blog-o-rama',
  'description' => 'Create and display blog posts and comments',
  'category' => 'blog',
  'permissions' => array(
    array(
      'name' => 'Read',
      'description' => 'Can read posts'
    ),
    array(
      'name' => 'Write',
      'description' => 'Can add and update posts'
    ),
    array(
      'name' => 'Delete',
      'description' => 'Can delete posts'
    )
  )
  );
}

Create

Kicks off the process to create a component. Receives component info and calls to create_component method to have database records created for the component. Is called asynchronously when a new component is added to a page, and the component’s form has a dossier with ‘procedure’ set to ‘create’. Adds a site attribute with a message that the specified component was created.

This is a good function to customize if there is something extra you’d like done when your component is added to a page, such as adding a hook to fire each time a component of this type is created.

create($input)

Parameters

$input	Array	Array that contains properties of new component that will be created
Potential members of the $input array
title	String (optional)	Title if it’s set in $input, type if it’s not set
parent_id	String (optional)	ID of parent, if it’s not set in $input this will be set to ‘0’
auto_create	array (optional)	Array of components which can be auto-created
url	String (optional)	url associated with the component, if set in $input will be cleaned by url_checker method
type	String	Class type of component
sequence	String (optional)	Order in which this component will be rendered on the page, will be set to 1 if not set in $input
[key]	String	Any other key/value pairs added to input will be added to [your_db]_components_meta

Return

Echos success or failure message

Example – Calling the method

The create method is not normally called verbatim in PHP code, but instead is triggered when the procedure value in a dossier is set to ‘create’, and a form with this dossier is submitted from a page. See the Form Input section for more details.

Example – Overwriting the method

protected function create($input) {
  // media_create_component

  if (isset($site->hooks['media_create_component'])) {
    foreach($site->hooks['media_create_component'] as $hook) {
      $input = call_user_func($hook, $input);
    }
  }
  $component_id = self::create_component($input);
  echo json_encode(array(
    'response' =>'success','procedure' =>'create','action' => 'reload','message' => 'New Component Was Created'));
  return;
}

Create Component

Called by Component create method. Receives an array of properties and uses these properties to create records in the database. Add created_by and created_at properties, using current user ID and timestamp.

Creates a new component in [your_db]_components table using parent_id, sequence, and url. Adds any other data as key/value pairs to [your_db]_components_meta table.

Will create the new component specified, then look through the recipe for any components with auto_create set and will create those according to their setting – ‘forward’ or ‘reverse’. Auto_create array is built and added to the dossier by the recipe_component method during Page Build process.

create_component($input)

Parameters

$input	Array	Array that contains properties of new component that will be created
Potential members of the $input array
title	String (optional)	Title if it’s set in $input, type if it’s not set
parent_id	String (optional)	ID of parent, if it’s not set in $input this will be set to ‘0’
auto_create	array (optional)	Array of components which can be auto-created
url	String (optional)	url associated with the component, if set in $input will be cleaned by url_checker method
type	String	Class type of component
sequence	String (optional)	Order in which this component will be rendered on the page, will be set to 1 if not set in $input
[key]	String	Any other key/value pairs added to input will be added to [your_db]_components_meta

Return

Int	ID of new component

Hooks

create_component_before invoked before component is created, receives and returns altered $input array

Example – Calling the Method

$component_id = self::create_component($input);

Example – Overwriting the Method

This method is fleshed out in the parent Component Class, and we don’t recommend overwriting it. If you need to customize the component creation process, use the create method or add a create_component_before hook.

Delete

Kicks off the process to delete a component. Calls delete_component method to delete all traces of component from the system. Is called asynchronously when a user chooses to remove a component from a page, and submits a component form with a dossier with ‘procedure’ set to ‘delete’. Adds a site attribute with a message that the specified component was deleted.

This is a good function to customize if there is something extra you’d like done when your component is deleted from a page, such as adding a hook to fire each time a component of this type is deleted.

delete($input)

Parameters

$input	Array	Array that contains properties of component to delete
Potential members of the $input array
component_id	Int	ID of component to be deleted
parent_url	String (optional)	url associated with top level parent of the recipe/page this component belongs to.
created_at	String	Timestamp of when component was created.

Return

Echos success or failure message

Example – Calling the method

The delete method is not normally called verbatim in PHP code, but instead is triggered when the procedure value in a dossier is set to ‘delete’, and a form with this dossier is submitted from a page. See the Form Input section for more details.

Example – Overwriting the method

protected function delete($input) {
  global $vce;
  // media_delete_component

  if (isset($vce->site->hooks['media_delete_component'])) {
    foreach($$vce->site->hooks['media_delete_component'] as $hook) {
      $input = call_user_func($hook, $input);
    }
  }
  $parent_url = self::delete_component($input);
  if (isset($parent_url)) {
    echo json_encode(array('response' => 'success', 'procedure' => 'delete','action' => 'reload',
      'url' => $parent_url, 'message' => "Deleted"));
    return;
  }

Delete Component

Checks that certain values are present in $input to get component ready for deletion. If no component_id is set, echos an error message and then returns. If parent_url is not set, calls an anonymous function recursively to find the url associated with top level parent of the recipe/page this component belongs to. Check that $input[‘created_at’] matches the value in the database associated with the component ID as a security check to make sure we are deleting the correct component. Call extirpate_component method if all checks pass.

delete($input)

Parameters

$input	Array	Array that contains properties of component to delete
Potential members of the $input array
component_id	Int	ID of component to be deleted
parent_url	String (optional)	url associated with top level parent of the recipe/page this component belongs to.
created_at	String	Timestamp of when component was created.

Return

String	url associated with top level parent of the recipe/page this component belongs to.
Boolean	Returns with error message if no component ID
Boolean	Returns false if $input[‘created_at’] and database value for ‘created_at’ don’t match (and function hasn’t already returned)

Example - Calling the Method

$parent_url = self::delete_component($input);

Example – Overwriting the Method

This method is fleshed out in the parent Component Class, and we don’t recommend overwriting it. If you need to customize the component deletion process, use the delete method .

Disabled

Method that is called when the component is disabled. Method is empty in the base class and is meant to be overwritten. The disabled() method is invoked when a component is disabled using the Manage Components page included with the basic Nestor Install.

disabled()

Parameters

No parameters

Return

No return values

Example – Calling the function

When a component is marked disabled in ManageComponents, it goes through and calls the disabled function of the component.

foreach ($disable_items as $type=>$path) {
  // load class

  require_once(BASEPATH . $path);
  $disabled = new $type();
  // fire installed function
  $disabled->disabled();
}

Edit Component

Creates the HTML that allows the end user to edit or delete the component on a page. Is called during Page build process from build_content( ). The parent Component method is empty so this method will need to be fleshed out for any custom component that you want to be editable by an end user.

edit_component ($each_component, $vce)

Parameters

$each_recipe_component	Object	The recipe component for which you are creating content
$vce	Object	The global vce object, passed for convenience

Return

Datatype

desc

Example – Calling the Method

Page::build content( ) checks that the component is allowed to be edited, then calls the component’s edit_component( ) method.

if (!isset($each_component->prevent_editing) || $each_component->prevent_editing === false) {
$this_component->edit_component($each_component, $this);
}

Example – Overwriting the Method

In order to function, this method should:

1) Call $vce->page->can_edit() to make sure user has permissions to edit the component

2) Generate dossiers for edit and delete

3) Build HTML content to allow a user to edit properties of the component on a page. The content should encapsulate a form submission element that contains the component dossiers as properties.

4) Add generated HTML content to the global $content object

Refer to the Form Submission section for more information about submitting and receiving form data in the Nestor system.

public function edit_component($each_component, $page) {
  if ($vce->page->can_edit($each_component)) {
    // the instructions to pass through the form

    $dossier = array(
      'type' => $each_component->type,
      'procedure' => 'update',
      'component_id' => $each_component->component_id,
      'created_at' => $each_component->created_at
    );
    // generate dossier

    $dossier_for_update = $vce->generate_dossier($dossier);
    $content =
<<<EOF <div class="clickbar-container admin-container edit-container">
<div class="clickbar-content">
<form id="update_$each_component->component_id" class="asynchronous-form" method="post" action="$ vce->input_path" autocomplete="off">
<input type="hidden" name="dossier" value="$dossier_for_update">
<label>
<input type="text" name="title" value="$each_component->title" tag="required" autocomplete="off">
<div class="label-text">
<div class="label-message">Title</div>
<div class="label-error">Enter a Title</div>
</div>
</label>
<label>
<input type="text" name="url" value="$each_component->url" dossier="$dossier_for_checkurl" autocomplete="off">
<div class="label-text">
<div class="label-message">URL</div>
<div class="label-error">Enter a URL</div>
</div>
</label>
<label>
<input type="text" name="sequence" value="$each_component->sequence">
<div class="label-text">
<div class="label-message">Order Number</div>
<div class="label-error">Enter an Order Number</div>
</div>
</label>
<input type="submit" value="Update">
</form>
EOF;
    if ($page->can_delete($each_component)) {
      // the instructions to pass through the form

      $dossier = array(
        'type' => $each_component->type,
        'procedure' => 'delete',
        'component_id' => $each_component->component_id,
        'created_at' => $each_component->created_at
      );
      // generate dossier
      $dossier_for_delete = $vce->generate_dossier($dossier);
      $content .=
<<<EOF
<form id="delete_$each_component->component_id" class="delete-form float-right-form asynchronous-form" method="post" action="$vce->input_path">
<input type="hidden" name="dossier" value="$dossier_for_delete">
<input type="submit" value="Delete">
</form>
EOF;
    }
    $content .=
<<<EOF
</div>
<div class="clickbar-title clickbar-closed"><span>Edit $each_component->title</span></div>
</div>
EOF;
    $vce->content->add('admin', $content);
  }
}

Extirpate Component

Takes component ID and searches for all children. For the component and then for each of its children - looks for and deletes any related media/files and any datalists. Deletes the component and then recursively calls extirpate_component for each child. Note that each child could potential have its own children, each of these would also be extirpated recursively.

extirpate_component($component_id)

Parameters

component_id

Int

ID of component to be obliterated from the system

Return

No return value

Hooks

delete_extirpate_component called before component and it’s children are deleted. Receives component ID and array of children component IDs, and returns altered $components array.

Example – Calling the Method

self::extirpate_component($input['component_id']);

Example – Overwriting the Method

This method is fleshed out in the parent Component Class, and we don’t recommend overwriting it. If you need to customize the component deletion process, use the delete method.

Find Sub Components

This method is called by the Page object during the page build process. It checks if the Page get_sub_components method should be called for this component, and is checked in both get_components and get_sub_components, which is why both variables are available. The return value is set to true by default, but can be set to false if there is a reason you wouldn’t want to build out the full component tree under your component.

public function find_sub_components($requested_component, $vce, $components, $sub_components)

Parameters

$requested_component	Object	The requested component is the component that $page has identified either by the requested URL path, or by a component ID supplied on a querystring. This component will contain the Recipe that the $page uses to render the page content.
$vce	Object	The global $vce object, passed for convenience
$components	Array	The $components array being built by the $page process. At the point that it’s passed into this function, it will contain the requested component and any components upstream in the recipe inclusive of its branch, but not necessarily other branches.
$sub_components	Array	The $sub_components array being built by the $page process. At the point that it’s passed into this function, it will contain the requested component and any components upstream in the recipe inclusive of its branch, but not necessarily other branches.

Return

Boolean

Returns true by default

Example - Calling the Method

//call from the global $page object from get_components method

$find_sub_components = $current_component->find_sub_components (
$requested_component, $this, $components, $sub_components = array());
if ($find_sub_components) {
  //get sub-components
  $nested_components = self::get_sub_components($requested_id, $requested_id, $components);

  // add sub_components to components list

  $components[(count($components)-1)]->components = $nested_components;
}

Form Input

Processes input from a form submission. Will decrypt the dossier and route form data to the class/method indicated in the dossier. Your component will need to contain a method that processes the data.

form_input($input)

Parameters

$input

Array

Contains key/value pairs representing the form data submitted, and the dossier data.

Return

No values returned, will echo an error if method is not known

Example – Calling the Method

The Input component catches any form submissions and then routes the data to form_input( ) method of the class and method indicated in the dossier. If the class/method don’t exist, will default to the parent Component class method.

if (method_exists($this_component,'form_input')) {
  name="form_input"$this_component->form_input($input);
} else {
  // default to Component
  $this_component = new Component;
  $this_component->form_input($input);
}

Example – Overwriting the Method

The form_input( ) method was written to interact with the Nestor Core Engine and really shouldn’t be overwritten. It will route the data to the class and method indicated in the dossier submitted with the form.

Installed

Method that is called when the component is installed. Method is empty in the base class and is meant to be overwritten. The installed() method is invoked when a component is installed using the Manage Components page included with the basic Nestor Install. If your component will need to add anything into the system, such as Roles or datalists, this would be a good place to add them.

installed()

Parameters

No parameters

Return

No return values

Example - Calling this function

// cycle though newly installed items
foreach ($install_items as $type=>$path) {
  // load class

  require_once(BASEPATH . $path);
  $activated = new $type();
  // fire installed function

  $activated->installed();
}

Example - Overwriting the function

public function installed() {
  global $vce;
  $attributes = array (
    array (
      'role_name' => 'Moderator',
      'role_hierarchy' => '2'
    ),
    array (
      'role_name' => 'Author',
      'role_hierarchy' => '3'
    )
  );

  $vce->site->add_site_roles($attributes);
}

Preload Component

Method that is called when the component is pre-loaded during the page build process. This is where you would add definitions for any hooks you want to invoke. A hook tells the Nestor core engine to call a method in this Component at a defined time. See the Hooks section for information about where and when specific hooks are invoked. Can also fire stuff off, before page object is built. Could use for logging, change theme based on the site role, redirect URL for temp site maintenance.

When this method returns false, it is informing the system that it does not want to add any hooks into the system.

preload_component()

Parameters

No parameters

Return

	Boolean	Returns false by default, which indicates that this component is not adding any hooks into the system.
	Array	Contains arrays which define each individual hook to add. When this component is installed by Manage Components, if this method does not return false this component is added to the preloaded_components list in the [your_db ]_site_meta table. This tells the $site object to call this component during the page build process, and it’s hooks are loaded into the $site->hooks array.
Members of the returned array
[hook name]	String	The value should be the Class name and method that this hook will call, formatted in this manner: [Class_Name]::[Method_Name] The method must be in the Class indicated, or the system will throw an error. The hook name must be an existing hook that is called somewhere in the system. See the Hooks section for a list of existing hooks used by the core engine.

Example - Overwriting the Method

// add a hook that fires at initiation of site hooks

public function preload_component() {
  $content_hook = array (
    'site_hook_initiation' =>'Media::require_once_mediatype'
  );
  return $content_hook;
}

Recipe Components

Called from Page::build_content( ), goes through the recipe and creates components. Instantiates each component, then checks if user can add this component to a page. If so, creates dossiers for the component that are used for form submissions. Calls add_content( ) which adds content that will allow users to add, update, or delete this component on a page. Also will call recipe_manifestation() to show a representation of the component even if component has not yet been created, which can be useful for testing your component.

Recipe Components uses the concepts of auto_create forward/reverse to determine if components before or after the current component in the hierarchy should be automatically created. For example:

component_2 has auto_create = forward

component_1

- component_2

When you create component_1, component_2 will be automatically created. Used a lot, like when using Access.

- - - - - - - - - -

component_1 has auto_create = backwards

component_1

- component_2

Nestor will allow you to create component_2, and when you do, component_1 will be automatically created. Very rare, only used to allow people to upload and create a media item immediately. Upload a video, then asset component gets created to create context.

Technically, you can do both:

- auto_create_backwards

- - The Component Being Created

- - - auto_create_forwards

This method is critical for page build so we highly recommend not overwriting it or changing it.

recipe_components($each_component, $vce, $auto_create_reverse = null)

Parameters

$each_component	Object	The component currently being processed by the Page Build
$vce	Object	The global $vce object, passed for convenience
$auto_create_reverse	String	Determines if components can automatically be created ahead of or following the current component

Return

No return values

Hooks

page_requested_components receives $each_recipe_component before checking if the user can add the component. $each_recipe_component is the recipe for the next possible component after the component currently being processed.

Example – Calling this Method

build_content method in Page checks that component allows sub components to be built. If true, call to recipe_components to build out sub components for the current component.

if ($this_component->allow_sub_components($each_component, $vce)) {
  // check if prevent_sub_components has been set by previous allow_sub_components call

  if (!isset($this->prevent_sub_components)) {
    $this_component->recipe_components($each_component, $vce);
  }
}

Recipe Fields

Adds component fields used in ManageRecipes.

recipe_fields($recipe)

Parameters

$recipe

Array

Contains all the information for the page recipe

Return

Boolean	Return false if you do not want the component to be available to add to a recipe
String	Return HTML text that will create the recipe fields for the component

Example – Calling the Method

recipe_fields( ) is called by ManageRecipes to determine if a component should be available to add to a recipe, and to create the fields used to configure the component when it’s added to a recipe.

$recipe_fields = $access->recipe_fields(array('type'=>$key));

Example – Overwriting the Method

public function recipe_fields($recipe) {
  $title = isset($recipe['title']) ? $recipe['title'] : self::component_info()['name'];
  $elements =
<<<EOF
<input type="hidden" name="auto_create" value="forward"> <label> <input type="text" name="title" value="$title" tag="required" autocomplete="off">
<div class="label-text">
<div class="label-message">Title</div>
<div class="label-error">Enter a Title</div>
</div> </label>
EOF;
  return $elements;
}

Recipe Manifestation

Allows for content to be displayed when component is contained within the recipe, regardless if a component was created.

This is a ghostly apparition of a sub recipe item.

recipe_manifestation ($each_recipe_component, $page)

Parameters

$each_recipe_component	Object	The recipe component for which you are creating content
$vce	Object	The global vce object, passed for convenience

Return

No return value by default

Example – Calling the Method

recipe_manifestation is called from Component recipe_components during the Page Build. If the current component doesn’t exist, call the parent Component class. Either way, this content will be added to the page.

$this_component = new $component_type();
$this_component->recipe_manifestation((object) $each_recipe_component, $vce);

Example – Overwriting the Method

In this example, the method prints out function to show that this show that this component is included in the current recipe.

public static function recipe_manifestation($each_recipe_component, $vce) {
$content =
<<<EOF <div class="clickbar-container
create-observation-container"> <div class="clickbar-content">
EOF;
$vce->content->add('main',$content);
}

Recipe Manifestation Finish

Closes the content to be displayed when component is contained within the recipe, regardless if a component was created.

This is a ghostly apparition bookend for recipe_manifestation and occures after sub_component item.

recipe_manifestation_finish ($each_recipe_component, $vce)

Parameters

$each_recipe_component	Object	The recipe component for which you are creating content
$vce	Object	The global vce object, passed for convenience

Return

No return value by default

Example – Calling the Method

recipe_manifestation_finish() is called from Component::recipe_components() during the Page Build. It closes the content from recipe_manifestation().

$previous_component = new $component_type();
previous_component->recipe_manifestation_finish((object) $each_recipe_component, $vce);

Example – Overwriting the Method

In this example, the method closes out the recipe manifestation.

public static function recipe_manifestation_finish($each_recipe_component, $vce) {
$content =
<<<EOF
<div>end manifestation</div>
EOF;
$vce->content->add('main',$content);
}

Revise Component

Creates dossiers that are used by the edit component form on a page and adds them to $each_component. Then calls self:: edit_component () to integrate them into HTML on a page. The method is fairly fleshed out in the parent Component class, you can overwrite it to include other values in the dossier that your component may need to update itself.

*note that this method isn’t currently called within Nestor, but has been added for consistency

revise_component($each_component, $vce)

Parameters

$each_recipe_component	Object	The recipe component for which you are creating content
$vce	Object	The global vce object, passed for convenience

Return

No return by default

Example – Calling the Method

$this_component->revise_component($each_component, $vce);

Removed

Method that is called when the component is removed. Method is empty in the base class and is meant to be overwritten. The removed() method is invoked when a component is deleted using the Manage Components page included with the basic Nestor Install. If your component has added anything into the system, such as Roles or datalists, this would be a good place to remove them.

removed()

Parameters

No parameters

Return

No return values by default

Example – Calling the Method

This example shows removed() being called from the ManageComponents component, when a user clicks the delete button for a component.

$removed = $component->removed();

Example – Overwriting the Method

This example shows how associated datalists and metadata are removed from the database when the component is removed.

public function removed() {
  global $site;
  $attributes = array ('datalist' => 'institutions_datalist');
  $site->remove_datalist($attributes);
  global $db;
  $meta_data = array('institution','program');
  foreach ($meta_data as $each_data) {
    // delete user from database

    $where = array('meta_key' => $each_data);
    $db->delete('users_meta', $where);
  }
}

Update

Kicks off the process to update a component. Calls update_component method to update the component and data passed in the $input array. Is called asynchronously when a user chooses to update a component a page, and submits a component form with a dossier with ‘procedure’ set to ‘update’. Adds a site attribute with a message that the specified component was updated.

update($input)

Parameters

$input	Array	Array that contains properties of new component that will be created
Potential members of the $input array
component_id	String (optional)	ID of component to update
created_at	String	Timestamp of when the component was created, is used to compare with database entity to make sure we’re updating the right component
url	String (optional)	url associated with the component, if set in $input will be cleaned by url_checker method
sequence	String (optional)	Order in which this component will be rendered on the page
[key]	String	Any other key/value pairs in $input. Metadata will be updated if the key exists for this component, and added if the key doesn’t already exist. These key/value pairs will most likely come from from form fields from which this request was submitted, but could be added in the update() function.

Return

Echos success or failure message

Example – Calling the Method

The update method is not normally called verbatim in PHP code, but instead is triggered when the procedure value in a dossier is set to ‘create’, and a form with this dossier is submitted from a page. See the Form Input section for more details.

Example – Overwriting the Method

The Media class invokes a hook and then returns a message indicating success or error depending on the return value of its update_component method.

protected function update($input) {
  global $vce;
  // load media_update_component hooks

  if (isset($site->hooks['media_update_component'])) {
    foreach($site->hooks['media_update_component'] as $hook){
      $input = call_user_func($hook, $input);
    }
   }
  if (self::update_component($input)) {
    echo json_encode(array('response' => 'success',
      'procedure' => 'update','action' => 'reload', 'message' => "Updated"));
    return;
  }
  echo json_encode(array('response' => 'error', 'procedure' => 'update','message' => "Error"));
  return;
}

Update Component

Called by Component update method. Receives an array of properties and uses these properties to update records in the database for the specified component.

Updates an existing component in [your_db]_components table using parent_id, sequence, and url. Updates or adds any other data as key/value pairs to [your_db]_components_meta table.

If the component has an alias_id set in the [your_db ]_components_meta table, only sequence and URL are updated and none of the metadata will be updated.

update_component($input)

Parameters

$input	Array	Array that contains properties of new component that will be created
Potential members of the $input array
component_id	String (optional)	ID of component to update
created_at	String	Timestamp of when the component was created, is used to compare with database entity to make sure we’re updating the right component
url	String (optional)	url associated with the component, if set in $input will be cleaned by url_checker method
sequence	String (optional)	Order in which this component will be rendered on the page
[key]	String	Any other key/value pairs in $input. Metadata will be updated if the key exists for this component, and added if the key doesn’t already exist. These key/value pairs will most likely come from from form fields from which this request was submitted, but could be added in the update() function.

Return

Boolean

True if component is successfully updated, false if unsuccessful update, which can be due to $input[‘created_at’] value not matching the value for the specified component in the [your_db ]_components_meta table.

Example – Calling the Method

$update_status = self::update_component($input);

Example – Overwriting the Method

This method is fleshed out in the parent Component Class, and we don’t recommend overwriting it. If you need to customize the component update process, use the update method .