Documentation

SE_Role extends SC_Element
in package

Application

Base class for all SimplOn Elements.

Elements are fundamental building blocks in SimplOn, representing a set of related data and providing a standardized way to interact with that data. They include the information required to allow datastorage and render clases extend traditional object capabilities capabilities allowing for common tasks such as displaying, storing, searching, and generating user interfaces like forms.

Elements work in conjunction with SimplON Data objects. Each attribute of an Element that holds data intended for interaction (display, storage, etc.) should be an instance of a SimplON Data class (or a class extending SC_Data). These Data objects encapsulate the data itself along with important metadata about how the data should be handled (e.g., whether it should be shown in a view, included in a form, searchable, validated, etc.).

By combining the Element's methods and the metadata within its Data attributes, SimplOn's Renderers and DataStorage classes can automatically generate interfaces and interact with data storage without needing specific knowledge of each Element's internal structure. This allows for seamless integration and automatic updates of the interface and storage mechanisms as the Element's definition changes.

Inherits from SC_BaseObject for fundamental SimplOn object capabilities.

$AdminMsg : mixed
$CancelBtnMsg : mixed
$CreateBtnMsg : mixed
$CreatedMsg : mixed
$CreateError : mixed
$CreateMsg : mixed
$DeleteBtnMsg : mixed
$DeletedMsg : mixed
$DeleteError : mixed
$DeleteMsg : mixed
$formMethods : mixed
$methodsFamilies : mixed: Keeps the relationship between the methods and the datasMode so that is simplier to write the permissions.
$onTheFlyAttributes : mixed: Used to store Data atributes added on the fly for all the instances of the class usually links to actions like edit delete or view.
$permissions : mixed: Array containing the acces rules for the datas and methods.
$quickDelete : string: Flag to allow deletion without confirmation
$ReturnBtnMsg : mixed
$SearchBtnMsg : mixed
$SearchMsg : mixed
$storageChecked : bool: Flag to avoid the system to validate DataStorage more than once.
$UpdateBtnMsg : mixed
$UpdatedMsg : mixed
$UpdateError : mixed
$UpdateMsg : mixed
$ViewBtnMsg : mixed
$ViewMsg : mixed
$dataAttributes : array<string|int, mixed>: Stores a list of Element's attributes of type SC_Data.
$datasMode : mixed: Determines the kind of permissions that are given to the attributes.
$dataStorage : SDS_DataStorage: The DataStorage instance used by this Element to interact with the underlying data source.
$defaultAction : mixed
$deleteCriteria : string: Criteria to use for selection on the time of deletion in the dataStorage.
$exceptionMessages : mixed: Array with the exception Messages
$fieldId : string|null: Name of the Data attribute that represents the unique identifier field of the Element.
$filterCriteria : string: Criteria to use for searching in the dataStorage.
$fullyset : mixed: Flag to indicate that the whole constructor has finished. Used to avoid cicles with SC_ElementBased PERMISSIONS like SE_User but can be used to prevent other kind of infite loops and problems.
$Name : mixed
$nameInParent : mixed
$NamePlural : mixed
$OrderCriteria : mixed: How to order the elements when listing them
$parent : SC_Element|null: Elements can be nested using a special kind of data called ElementContainer.
$renderer : SR_htmlJQuery
$storage : string: The name of the data storage location associated with this Element.
__call() : mixed: Auto Makes the Setters and Getters
__construct() : mixed: Constructs a new SimplOn Element instance.
__toString() : string: Returns a string representation of the Element.
addData() : SC_Element: Adds a Data attribute to the Element instance dynamically.
addDatas() : mixed: Adds dynamically defined Data attributes to the current Element instance.
assignAsDatasParent() : mixed: Sets the current instance the as "logical" parent of the Datas.
assignDatasName() : mixed: Assigns the name attribute of each Data object within the Element instance.
asureRole() : mixed
attributesOfClass() : array<string|int, mixed>: Returns an array of attribute names (properties) of the Element instance that are instances of the specified class type.
attributesTypes() : array<string|int, mixed>: Returns an array of attribute names (properties) of the Element instance that are instances of the specified class type.
attributesTypesWith() : array<string|int, mixed>: Returns an array of attribute names (properties) of the Element instance that are instances of the specified class type and have a specific flag or method returning true.
clear() : mixed: Clears the value of a property or attribute
clearId() : mixed
clearValues() : mixed
construct() : mixed: User defined constructor, called within {@link __constructor()}, useful to declare specific Data attributes.
create() : mixed: Creates a new record for the element in the configured DataStorage.
dataAttributes() : array<string|int, mixed>: Returns an array containing the names of all Data attributes belonging to this Element instance.
datasWith() : array<string|int, mixed>|string: Returns an array of Element Data objects or their representations based on a specified flag and return type.
debug() : string: Returns a string containing debugging information about the Element.
defaultAction() : string: Gets or sets the default action for the Element.
defaultDeleteCriteria() : string: Generates the default delete criteria string based on fetched Data attributes that have values.
defaultFilterCriteria() : string: Generates the default filter criteria string based on searchable and fetched Data attributes.
delete() : mixed: Deletes the element from the configured DataStorage.
deleteCriteria() : string: Gets or sets the criteria string to use for selecting elements to delete from the dataStorage.
Elements() : array<string|int, mixed>: Obtain an array with all results from Element's table to be used in SD_ElementContainer.
fieldId() : string|null: Gets or sets the name of the Data attribute that represents the unique identifier field of the Element.
fillFromArray() : int: Fills the Element's Data attributes with values from a given array.
fillFromDSById() : void: Retrieves the element's Data attribute values from the configured DataStorage.
fillFromRequest() : bool: Fills the Element's Data attributes with values from the $_REQUEST and $_FILES superglobal arrays.
filterCriteria() : string: Gets or sets the filter criteria string for searching in the dataStorage.
getClass() : string: Returns the object's class
getId() : mixed: Returns the value of the Element's unique identifier field.
getLabelsAndNames() : array<string|int, mixed>: Generates an associative array mapping Data attribute labels to their names.
hasAttribute() : bool: Checks if a an object has a specific method
hasProperty() : bool: Checks if a an object has a specific property
instanceId() : mixed: Run time id of the object used to creat ids to link things in the interface like Labels and Inputs
Name() : string: Gets or sets the singular name of the Element.
NamePlural() : string: Gets or sets the plural name of the Element.
ObjectId() : mixed: Class and instance id
parent() : SC_Element|null: Gets or sets the parent element of this instance.
permissions() : array<string|int, mixed>: Returns the static permissions array for the Element.
processAdmin() : string: Processes the administration view's search request and returns the results.
processContinusCreate() : string: Processes the continuous creation of a new Element record via a JSON request.
processCreate() : string: Processes the creation of a new Element record and returns a JSON response.
processCreateJSon() : string: Processes the creation of an Element via a JSON request.
processData() : array<string|int, mixed>: Applies a method to all the Datas and returns an array containing all the responses.
processDelete() : string: Processes the deletion of an Element record.
processReport() : string: Processes a report request for the Element.
processSearch() : mixed: Processes a search request for the Element.
processUpdate() : string: Processes the update of an Element record and returns a JSON response.
processUpdateJSon() : string: Generates the proper response JSON for the update of an Element .
removeData() : SC_Element: Removes a dynamically added Data attribute from the Element instance.
requiredCheck() : array<string|int, mixed>: Checks if all required Data attributes of the Element have values.
save() : mixed: Saves the element to the configured DataStorage.
setId() : SC_Element: Sets the value of the Element's unique identifier field.
showAdmin() : SI_systemScreen: Renders the administration view for the Element.
showContinusCreate() : mixed: Renders a form for continuous creation of new Element instances.
showCreate() : SI_systemScreen: Renders a form for creating a new instance of the Element.
showCreateSelect() : mixed: Renders a form for creating a new instance of the Element, intended for scenarios where the newly created element should be selected before the creation of another element usually using SD_ElementContainer.
showDelete() : SI_systemScreen: Renders a confirmation form for deleting an Element.
showEmbeded() : mixed
showEmbededStrip() : string: Displays a stripped-down, embedded representation of the Element.
showNoAccess() : SI_systemScreen: Displays a message indicating that the user does not have sufficient permissions to access the requested resource or perform the requested action.
showSearch() : string: Processes the creation of a new Element record and appends it to a container in the parent's interface via a JSON response.
showUpdate() : mixed
showUpdateSelect() : mixed
showView() : mixed
toArray() : array<string|int, mixed>: Returns an array representation of the Element, mapping each Data attribute's name as the key and the data attribute's current value as the value.
update() : mixed: Updates the element's data in the configured DataStorage.
validateForDB() : mixed: Validates the Element's Data attributes before interacting with the DataStorage (e.g., before creating or updating a record).
viewVal() : mixed: Returns the main value of the Element in a format adecute for human reading.

$AdminMsg


    public
    static    mixed
    $AdminMsg

$CancelBtnMsg


    public
    static    mixed
    $CancelBtnMsg

$CreateBtnMsg


    public
    static    mixed
    $CreateBtnMsg

$CreatedMsg


    public
    static    mixed
    $CreatedMsg

$CreateError


    public
    static    mixed
    $CreateError

$CreateMsg


    public
    static    mixed
    $CreateMsg

$DeleteBtnMsg


    public
    static    mixed
    $DeleteBtnMsg

$DeletedMsg


    public
    static    mixed
    $DeletedMsg

$DeleteError


    public
    static    mixed
    $DeleteError

$DeleteMsg


    public
    static    mixed
    $DeleteMsg

$formMethods


    public
    static    mixed
    $formMethods
     = ['showSearch', 'showCreate', 'showUpdate']

$methodsFamilies

Keeps the relationship between the methods and the datasMode so that is simplier to write the permissions.


    public
    static    mixed
    $methodsFamilies
     = array('showView' => 'View', 'showSearch' => 'View', 'showList' => 'View', 'showEmbed' => 'View', 'showEmbededStrip' => 'View', 'processReport' => 'View', 'showAdmin' => 'Admin', 'showUpdate' => 'Update', 'showUpdateSelect' => 'Update', 'processUpdate' => 'Update', 'processUpdateJSon' => 'Update', 'processUpdateSelect' => 'Update', 'showCreate' => 'Create', 'showContinusCreate' => 'Create', 'showCreateAppend' => 'Create', 'showCreateSelect' => 'Create', 'processContinusCreate' => 'Create', 'processCreate' => 'Create', 'processCreateAppend' => 'Create', 'processCreateJSon' => 'Create', 'processCreateSelect' => 'Create', 'processCreprocessUpdateate' => 'Create', 'showDelete' => 'Delete', 'processDeletePage' => 'Delete', 'showSearch' => 'Search', 'showSearchSelect' => 'Search', 'processAdmin' => 'Search', 'processSearch' => 'Search', 'logout' => 'logout', 'showLogin' => 'showLogin', 'processLogin' => 'processLogin')

$onTheFlyAttributes

Used to store Data atributes added on the fly for all the instances of the class usually links to actions like edit delete or view.


    public
    static    mixed
    $onTheFlyAttributes
     = array()

TODO: Evalute if can be mixed/integrated with $dataAttributes

$permissions

Array containing the acces rules for the datas and methods.


    public
    static    mixed
    $permissions
     = array('admin' => array('*' => 'allow'), '*' => array('*' => 'deny'))

Example: admin' => array(''=>'allow'), 'Asesor' => array( 'View'=>array( 'updateAction'=>'viwableWhen_id_=_CurrentUserId', 'deleteAction'=>'hide', ), 'Search'=>'allow', 'Update'=>array( 'asesor'=>'fixed_CurrentUserId', ), 'Create'=>array( 'asesor'=>'fixed_CurrentUserId', ), 'Delete'=>'deny', ), '' => array('showView'=>'allow','*'=>'deny')

$quickDelete

Flag to allow deletion without confirmation


    public
    static    string
    $quickDelete

By default it uses the value of SC_MAIN::$QUICK_DELETE

$ReturnBtnMsg


    public
    static    mixed
    $ReturnBtnMsg

$SearchBtnMsg


    public
    static    mixed
    $SearchBtnMsg

$SearchMsg


    public
    static    mixed
    $SearchMsg

$storageChecked

Flag to avoid the system to validate DataStorage more than once.


    public
    static    bool
    $storageChecked

$UpdateBtnMsg


    public
    static    mixed
    $UpdateBtnMsg

$UpdatedMsg


    public
    static    mixed
    $UpdatedMsg

$UpdateError


    public
    static    mixed
    $UpdateError

$UpdateMsg


    public
    static    mixed
    $UpdateMsg

$ViewBtnMsg


    public
    static    mixed
    $ViewBtnMsg

$ViewMsg


    public
    static    mixed
    $ViewMsg

$dataAttributes

Stores a list of Element's attributes of type SC_Data.


    protected
        array<string|int, mixed>
    $dataAttributes

TODO: Evalute if can be made static

containing objects of type SC_Data

$datasMode

Determines the kind of permissions that are given to the attributes.


    protected
        mixed
    $datasMode

Depending on the $methodsFamilies array each method is assigned a DatasMode View, Update, Create, Delete, Search or the method it static. This way the permissions don't have to be asigned for each method but for DatasMode and special methods.

$dataStorage

The DataStorage instance used by this Element to interact with the underlying data source.


    protected
        SDS_DataStorage
    $dataStorage

By default, it is initialized with the global DataStorage instance configured in SC_Main::$DATA_STORAGE.

$defaultAction


    protected
        mixed
    $defaultAction
     = \null

$deleteCriteria

Criteria to use for selection on the time of deletion in the dataStorage.


    protected
        string
    $deleteCriteria

By default builds it using the Data attributes' default criteria and the delete flags of each

$exceptionMessages

Array with the exception Messages


    protected
        mixed
    $exceptionMessages
     = array()

Used for example when validating for Storing Data

$fieldId

Name of the Data attribute that represents the unique identifier field of the Element.


    protected
        string|null
    $fieldId

This typically corresponds to the primary key column name in an SQL database.

$filterCriteria

Criteria to use for searching in the dataStorage.


    protected
        string
    $filterCriteria

By default builds it using the Data attributes' default criteria and the search flags of each

$fullyset

Flag to indicate that the whole constructor has finished. Used to avoid cicles with SC_ElementBased PERMISSIONS like SE_User but can be used to prevent other kind of infite loops and problems.


    protected
        mixed
    $fullyset
     = \false

$Name


    protected
        mixed
    $Name

$nameInParent


    protected
        mixed
    $nameInParent

$NamePlural


    protected
        mixed
    $NamePlural

$OrderCriteria

How to order the elements when listing them


    protected
        mixed
    $OrderCriteria
     = 'SimplOn_id desc'

$parent

Elements can be nested using a special kind of data called ElementContainer.


    protected
        SC_Element|null
    $parent

If an element is contained within another element, the containing element can be accessed via this attribute.

NOTE: This property is NOT the same as the parent:: keyword used to call a parent class's methods or access parent properties.

The parent element, or null if this element is not nested.

$renderer


    protected
        SR_htmlJQuery
    $renderer

$storage

The name of the data storage location associated with this Element.


    protected
        string
    $storage

This could be a table name in a relational database, a collection name in a NoSQL database, or a path in a file system. By default, this is set to the class name of the Element (without the namespace).

__call()

Auto Makes the Setters and Getters


    public
                    __call( $name,  $arguments) : mixed

Parameters

$name :
$arguments :

Return values

mixed —

__construct()

Constructs a new SimplOn Element instance.


    public
                    __construct([mixed $id_or_array = null ][, string|null $storage = null ][, SDS_DataStorage|null $specialDataStorage = null ]) : mixed

The constructor performs several key initializations:

Sets the storage location based on the provided $storage parameter or defaults to the class name.
Assigns the global renderer instance.
Determines and assigns the appropriate DataStorage instance (either a special one provided or the global one).
Initializes the Element's singular and plural names if they are not already set.
Sets various static message properties used for UI elements (e.g., AdminMsg, CreateMsg) using the localization function SC_MAIN::L().
Calls the user-defined construct() method, allowing subclasses to perform their own specific initializations and declare Data attributes.
Adds any Data attributes defined on the fly.
Assigns the name of each Data attribute within the Element instance.
Sets the current Element instance as the logical parent for its Data attributes.
Ensures the element's storage structure exists in the DataStorage.
Attempts to fill the Element's Data values from the provided $id_or_array (either an array of values or an ID to fetch from storage).
Sets the $fullyset flag to true, indicating that the initialization is complete.

Parameters

$id_or_array : mixed = null: Optional. The unique identifier (ID) of the Element to load from storage, or an array of key-value pairs to pre-fill the Element's Data attributes. Defaults to null.
$storage : string|null = null: Optional. The specific name of the data storage location for this Element. If not provided, the class name is used.
$specialDataStorage : SDS_DataStorage|null = null: Optional. A specific DataStorage instance to use for this Element, overriding the global one. Defaults to null, which means the global DataStorage will be used.

Return values

mixed —

__toString()

Returns a string representation of the Element.


    public
                    __toString() : string

This method is automatically called when an Element object is treated as a string. By default, it returns the result of calling the showView() method, which provides a human-readable representation of the Element.

Return values

string —

A string representation of the Element, typically the output of showView().

addData()

Adds a Data attribute to the Element instance dynamically.


    public
                    addData(string $attributeName, SC_Data $attribute) : SC_Element

This method allows adding new Data objects to an Element instance at runtime. It assigns the provided $attribute (an instance of SC_Data) to the Element instance as a property with the name specified by $attributeName. It also sets the name of the Data attribute itself and adds it to the list of data attributes for the Element.

Parameters

$attributeName : string: The name of the attribute to add to the Element.
$attribute : SC_Data: The SC_Data object to add as an attribute.

Return values

SC_Element —

The current Element instance, allowing for method chaining.

addDatas()

Adds dynamically defined Data attributes to the current Element instance.


    public
                    addDatas() : mixed

This method iterates through the static list of on-the-fly attributes (static::$onTheFlyAttributes) and clones each attribute, assigning it as a property to the current Element instance. It also ensures that the cloned attribute is added to the instance's list of data attributes. This is typically called during the Element's construction to include attributes defined dynamically.

Return values

mixed —

assignAsDatasParent()

Sets the current instance the as "logical" parent of the Datas.


    public
                    assignAsDatasParent([mixed &$parent = null ]) : mixed

Thus the datas may access other element's datas and methods if required Comments: This is useful in many circumstances for example it enables the existence of ComplexData.

Parameters

$parent : mixed = null

Return values

mixed —

assignDatasName()

Assigns the name attribute of each Data object within the Element instance.


    public
                    assignDatasName() : mixed

This method iterates through the properties of the Element. If a property is an instance of SC_Data and its name property is not already set, this method sets the Data object's name property to the name of the attribute in the Element instance.

This is useful for Data objects to know their corresponding attribute name within the parent Element, which can be used for generating and handling filter criteria and other operations.

Return values

mixed —

asureRole()


    public
                    asureRole(mixed $role) : mixed

Parameters

$role : mixed

Return values

mixed —

attributesOfClass()

Returns an array of attribute names (properties) of the Element instance that are instances of the specified class type.


    public
                    attributesOfClass(string $type) : array<string|int, mixed>

Parameters

$type : string: The class type to filter attributes by.

Return values

array<string|int, mixed> —

An array of attribute names that are instances of the specified type.

attributesTypes()

Returns an array of attribute names (properties) of the Element instance that are instances of the specified class type.


    public
                    attributesTypes([string $type = 'SC_Data' ]) : array<string|int, mixed>

Parameters

$type : string = 'SC_Data': The class type to filter attributes by. Defaults to 'SC_Data'.

Return values

array<string|int, mixed> —

An array of attribute names that are instances of the specified type.

attributesTypesWith()

Returns an array of attribute names (properties) of the Element instance that are instances of the specified class type and have a specific flag or method returning true.


    public
                    attributesTypesWith([string $type = 'SC_Data' ][, string $what = 'fetch' ]) : array<string|int, mixed>

Parameters

$type : string = 'SC_Data': The class type to filter attributes by. Defaults to 'SC_Data'.
$what : string = 'fetch': The name of the method or attribute to check for a true value. Defaults to 'fetch'.

Return values

array<string|int, mixed> —

An array of attribute names that match the criteria.

clear()

Clears the value of a property or attribute


    public
                    clear(string $name) : mixed

Parameters

$name : string

Return values

mixed —

clearId()


    public
                    clearId() : mixed

Return values

mixed —

clearValues()


    public
                    clearValues([mixed $clearID = false ]) : mixed

Parameters

$clearID : mixed = false

Return values

mixed —

construct()

User defined constructor, called within {@link __constructor()}, useful to declare specific Data attributes.


    public
                    construct([mixed $id = null ][, mixed &$specialDataStorage = null ]) : mixed

Parameters

$id : mixed = null
$specialDataStorage : mixed = null

Return values

mixed —

create()

Creates a new record for the element in the configured DataStorage.


    public
                    create() : mixed

This method first calls processData('preCreate') to execute any pre-creation processing defined for the element's Data attributes. It then delegates the creation process to the DataStorage instance's createElement method. Upon successful creation, it sets the ID of the current Element instance with the newly generated ID returned by the DataStorage. Finally, it calls processData('postCreate') to execute any post-creation processing defined for the element's Data attributes.

Return values

mixed —

The result of the DataStorage creation operation, typically the new unique identifier (ID) for the created record on success, or false on failure.

dataAttributes()

Returns an array containing the names of all Data attributes belonging to this Element instance.


    public
                    dataAttributes() : array<string|int, mixed>

If the list of data attributes has not been initialized, it calls attributesTypes() to generate it.

Return values

array<string|int, mixed> —

An array of strings, where each string is the name of a Data attribute.

datasWith()

Returns an array of Element Data objects or their representations based on a specified flag and return type.


    public
                    datasWith(string $what[, string $retType = 'strings' ]) : array<string|int, mixed>|string

This method iterates through the Element's Data attributes and filters them based on whether they have the flag or method specified by $what returning true. The return type of the array can be controlled by the $retType parameter.

Parameters

$what : string: The name of the VCRSL flag or method to check on each Data object.
$retType : string = 'strings': Optional. The desired return type. 'strings' returns an array of Data attribute names, 'show' returns an array of the results of calling the 'show' method with the flag name (e.g., showView), and 'objects' returns an array of the Data objects themselves. Defaults to 'strings'.

Return values

array<string|int, mixed>|string —

An array of Data attributes (names, show output, or objects) that have the specified flag set, or the string 'NotVCRSL' if the flag is not a recognized VCRSL method.

debug()

Returns a string containing debugging information about the Element.


    public
                    debug() : string

This method provides a simple way to inspect the current state of the Element, including its class name and the names and values of its Data attributes.

Return values

string —

A string containing the class name of the Element and a list of its Data attributes with their current values.

defaultAction()

Gets or sets the default action for the Element.


    public
                    defaultAction([string|null $defaultAction = null ]) : string

If a default action is provided, it sets the internal defaultAction property. If no default action is provided, it returns the currently set default action. If no default action is set, it returns the default action configured in SC_Main::$DEFAULT_ELEMENT and SC_Main::$DEFAULT_METHOD rendered by the renderer.

Parameters

$defaultAction : string|null = null: Optional. The default action to set. Defaults to null.

Return values

string —

The default action URL or identifier.

defaultDeleteCriteria()

Generates the default delete criteria string based on fetched Data attributes that have values.


    public
                    defaultDeleteCriteria([string $operator = 'AND' ]) : string

This method iterates through the Element's Data attributes and builds a delete criteria string including attributes that are marked as fetchable (fetch()) and have a non-empty value. The criteria are joined by the specified operator.

Parameters

$operator : string = 'AND': Optional. The logical operator to use between criteria (e.g., 'AND', 'OR'). Defaults to 'AND'.

Return values

string —

The default delete criteria string.

defaultFilterCriteria()

Generates the default filter criteria string based on searchable and fetched Data attributes.


    public
                    defaultFilterCriteria([string $operator = 'AND' ]) : string

This method iterates through the Element's Data attributes and builds a filter criteria string including attributes that are marked as searchable (search()) and fetchable (fetch()) and have a non-empty value. The criteria are joined by the specified operator.

Parameters

$operator : string = 'AND': Optional. The logical operator to use between criteria (e.g., 'AND', 'OR'). Defaults to 'AND'.

Return values

string —

The default filter criteria string.

delete()

Deletes the element from the configured DataStorage.


    public
                    delete() : mixed

This method first calls processData('preDelete') to execute any pre-deletion processing defined for the element's Data attributes. It then delegates the actual deletion operation to the DataStorage instance's deleteElement method. After the deletion is performed, it calls processData('postDelete') to execute any post-deletion processing.

Return values

mixed —

The result of the DataStorage deletion operation, which typically indicates the success or failure of the deletion (e.g., number of affected rows).

deleteCriteria()

Gets or sets the criteria string to use for selecting elements to delete from the dataStorage.


    public
                    deleteCriteria([string|null $deleteCriteria = null ]) : string

If a criteria string is provided, it sets the internal deleteCriteria property. If no criteria string is provided, it returns the currently set delete criteria. If no delete criteria has been set, it generates the default delete criteria using defaultDeleteCriteria().

The criteria string can contain placeholders that will be replaced, similar to filterCriteria().

Parameters

$deleteCriteria : string|null = null: Optional. The delete criteria string to set. If null, the current criteria is returned.

Return values

string —

The delete criteria string.

Elements()

Obtain an array with all results from Element's table to be used in SD_ElementContainer.


    public
                    Elements() : array<string|int, mixed>

This method uses the search functionality to retrieve all records for the Element

Return values

array<string|int, mixed> —

An array containing all results from the Element's data storage.

fieldId()

Gets or sets the name of the Data attribute that represents the unique identifier field of the Element.


    public
                    fieldId([string|null $val = null ]) : string|null

If the field ID is not already set and no value is provided, it attempts to automatically detect the first attribute of type SD_Id.

Parameters

$val : string|null = null: Optional. The name of the attribute to set as the unique identifier field. If null, the current field ID is returned.

Return values

string|null —

The name of the unique identifier field.

fillFromArray()

Fills the Element's Data attributes with values from a given array.


    public
                    fillFromArray(array<string|int, mixed> &$array_of_data) : int

This method iterates through the provided array, and for each key-value pair, it attempts to assign the value to the corresponding Data attribute within the Element instance. It also performs validation for each Data attribute during the assignment process.

Parameters

$array_of_data : array<string|int, mixed>: An associative array where keys are the names of the Data attributes and values are the data to be assigned. The array is passed by reference.

Return values

int —

The number of Data attributes successfully filled.

fillFromDSById()

Retrieves the element's Data attribute values from the configured DataStorage.


    public
                    fillFromDSById([mixed $id = null ]) : void

It uses the provided $id to fetch the record. If no $id is provided, it attempts to use the element's currently set ID (retrieved via getId()). The fetched data is then used to fill the Element's Data attributes by calling fillFromArray().

Parameters

$id : mixed = null: Optional. The unique identifier of the element to fetch from the data storage. If null, the element's current ID is used.

Return values

void —

fillFromRequest()

Fills the Element's Data attributes with values from the $_REQUEST and $_FILES superglobal arrays.


    public
                    fillFromRequest() : bool

This method processes data submitted via a request. It first checks if $_REQUEST is populated. If so, it iterates through $_FILES and, for any entry corresponding to an SD_File attribute on the element, it incorporates the file data into the $_REQUEST array before passing the combined data to fillFromArray for assignment and validation.

This is necessary because fillFromArray is designed to handle a single array of data, but file uploads are provided in the separate $_FILES superglobal.

Return values

bool —

True if $_REQUEST was processed, false otherwise.

filterCriteria()

Gets or sets the filter criteria string for searching in the dataStorage.


    public
                    filterCriteria([string|null $filterCriteria = null ]) : string

If a criteria string is provided, it sets the internal filterCriteria property. If no criteria string is provided, it returns the currently set filter criteria. If no filter criteria has been set, it generates the default filter criteria using defaultFilterCriteria().

The criteria string can contain placeholders that will be replaced:

.dataName: Replaced by the filterCriteria defined in the corresponding Data attribute.
:dataName: Replaced by the current value of the corresponding Data attribute.

Parameters

$filterCriteria : string|null = null: Optional. The filter criteria string to set. If null, the current criteria is returned.

Return values

string —

The filter criteria string.

getClass()

Returns the object's class


    public
                    getClass() : string

Return values

string —

The short class name of the object instance.

getId()

Returns the value of the Element's unique identifier field.


    public
                    getId() : mixed

The field used as the ID is determined by the fieldId property.

Return values

mixed —

The value of the unique identifier field, or null if not set.

getLabelsAndNames()

Generates an associative array mapping Data attribute labels to their names.


    public
                    getLabelsAndNames() : array<string|int, mixed>

This method iterates through the Element's Data attributes. For each attribute that is an instance of SC_Data, is configured to be fetched (fetch() is true), has a non-empty label, and is not an instance of SD_AutoIncrementId, it adds an entry to the result array where the key is the attribute's label and the value is the attribute's name.

Return values

array<string|int, mixed> —

An associative array where keys are Data attribute labels and values are Data attribute names.

hasAttribute()

Checks if a an object has a specific method


    public
                    hasAttribute(mixed $attribute) : bool

Parameters

$attribute : mixed

Return values

bool —

hasProperty()

Checks if a an object has a specific property


    public
                    hasProperty(string $propName) : bool

Parameters

$propName : string

Return values

bool —

instanceId()

Run time id of the object used to creat ids to link things in the interface like Labels and Inputs


    public
                    instanceId() : mixed

Return values

mixed —

Name()

Gets or sets the singular name of the Element.


    public
                    Name([string|null $name = null ][, bool $captalize = false ]) : string

If no name is provided, it attempts to derive the name from the class name. The name is then passed through the localization function.

Parameters

$name : string|null = null: Optional. The singular name to set. If null, the current name is returned or derived.
$captalize : bool = false: Optional. Whether to capitalize the first letter of the returned name. Defaults to false.

Return values

string —

The singular name of the Element.

NamePlural()

Gets or sets the plural name of the Element.


    public
                    NamePlural([string|null $namePlural = null ][, bool $captalize = false ]) : string

If no plural name is provided, it attempts to derive it by appending 's' to the singular name. The plural name is then passed through the localization function.

Parameters

$namePlural : string|null = null: Optional. The plural name to set. If null, the current plural name is returned or derived.
$captalize : bool = false: Optional. Whether to capitalize the first letter of the returned plural name. Defaults to false.

Return values

string —

The plural name of the Element.

ObjectId()

Class and instance id


    public
                    ObjectId() : mixed

Return values

mixed —

parent()

Gets or sets the parent element of this instance.


    public
                    parent([SC_Element|null &$parent = null ]) : SC_Element|null

This is used when elements are nested within ElementContainer.

Parameters

$parent : SC_Element|null = null: Optional. The parent element to set. If null, the current parent element is returned.

Return values

SC_Element|null —

The parent element, or null if not set.

permissions()

Returns the static permissions array for the Element.


    public
                    permissions() : array<string|int, mixed>

This array defines the access rules for the element's data and methods.

Return values

array<string|int, mixed> —

The permissions array.

processAdmin()

Processes the administration view's search request and returns the results.


    public
                    processAdmin([int $start = 1 ][, int $limit = null ]) : string

This method is typically called when the search form in the administration view is submitted. It handles the search criteria, retrieves the relevant data from the data storage, and formats it for display in the administration view, including handling paging.

Parameters

$start : int = 1: Optional. The starting record number for the results. Defaults to 1.
$limit : int = null: Optional. The maximum number of records to include per page. Defaults to null (no limit).

Return values

string —

The rendered search results for the administration view, typically an HTML string containing a table and paging links.

processContinusCreate()

Processes the continuous creation of a new Element record via a JSON request.


    public
                    processContinusCreate([string|null $nextStep = null ]) : string

This method is the target of the form submission from showContinusCreate(). It handles incoming request data, validates it, attempts to create a new record, and returns a JSON response.

Unlike processCreateJSon(), upon successful creation, this method generates a $nextStep that points back to showContinusCreate() with the newly created element's ID (though the ID might not be strictly necessary for displaying an empty form, it's included in the action URL). This allows the renderer to stay on the creation form and display a success message, facilitating continuous creation.

If validation fails, it returns a JSON object containing commands for the renderer to display validation messages, similar to processCreateJSon(). If a database error occurs during creation, it triggers a user error.

Parameters

$nextStep : string|null = null: Optional. The URL or action to redirect to after successful creation. If null, it defaults to calling showContinusCreate again with the newly created element's ID.

Return values

string —

A JSON string containing commands for the renderer or error information.

processCreate()

Processes the creation of a new Element record and returns a JSON response.


    public
                    processCreate() : string

This method prepares the necessary data and delegates the actual creation and JSON response generation to processCreateJSon(). It sets a success message and determines the next step (typically redirecting to the admin view) before calling the JSON processing method.

Return values

string —

A JSON string containing commands for the renderer, typically a redirect command.

processCreateJSon()

Processes the creation of an Element via a JSON request.


    public
                    processCreateJSon([string|null $nextStep = null ]) : string

This method handles incoming request data, validates it, attempts to create a new record for the element in the data storage, and returns a JSON response indicating the result or validation errors.

On successful creation, it returns a JSON object containing commands for the renderer, typically a command to redirect to the next step. If validation fails, it returns a JSON object containing commands for the renderer to display validation messages for specific data attributes. If a database error occurs during creation, it triggers a user error.

Parameters

$nextStep : string|null = null: Optional. The URL or action to redirect to after successful creation. Defaults to null.

Return values

string —

A JSON string containing commands for the renderer or error information.

processData()

Applies a method to all the Datas and returns an array containing all the responses.


    public
                    processData(string $method) : array<string|int, mixed>

This method iterates through all the Data attributes of the Element and calls the specified method on each Data object. It collects and returns an array of all non-null responses from these method calls.

Parameters

$method : string: The name of the method to call on each Data object. This method must be common to all relevant Data objects.

Return values

array<string|int, mixed> —

An array containing the non-null results of calling the specified method on each Data attribute.

processDelete()

Processes the deletion of an Element record.


    public
                    processDelete([string|null $nextStep = null ][, string $format = 'json' ]) : string

This method handles the request to delete an element. It performs the deletion operation in the data storage and returns a JSON response indicating the result. Upon successful deletion, the JSON response typically contains commands for the renderer to redirect to another page (e.g., the admin view) and potentially display a success message. If the deletion fails, it triggers a user error.

Parameters

$nextStep : string|null = null: Optional. The URL or action to redirect to after successful deletion. Defaults to the admin view with a deleted message.
$format : string = 'json': Optional. The desired response format. Defaults to 'json'. (Note: Currently only JSON output is implemented).

Return values

string —

A JSON string containing commands for the renderer or error information.

processReport()

Processes a report request for the Element.


    public
                    processReport(int $start[, int $limit = null ]) : string

This method prepares and executes a report based on the Element's data. It typically involves setting search flags, processing request data, retrieving results from the data storage using a reporting mechanism, and generating formatted output with paging.

Parameters

$start : int: The starting record number for the report.
$limit : int = null: Optional. The maximum number of records to include in the report page. Defaults to null (no limit).

Return values

string —

The rendered report output, typically an HTML string containing the report table and paging links.

processSearch()

Processes a search request for the Element.


    public
                    processSearch() : mixed

This method handles incoming search criteria, performs the search using the configured DataStorage, formats the results into a table, and renders the table for display.

Return values

mixed —

The rendered search results, typically an HTML string representing a table.

processUpdate()

Processes the update of an Element record and returns a JSON response.


    public
                    processUpdate() : string

This method prepares the necessary data and delegates the actual update and JSON response generation to processUpdateJSon(). It sets a success message and determines the next step (typically redirecting to the admin view) before calling the JSON processing method.

Return values

string —

A JSON string containing commands for the renderer, typically a redirect command.

processUpdateJSon()

Generates the proper response JSON for the update of an Element .


    public
                    processUpdateJSon([string|null $nextStep = null ]) : string

This method handles incoming request data, validates it, attempts to update an existing record for the element in the data storage, and returns a JSON response indicating the result or validation errors.

On successful update, it returns a JSON object containing commands for the renderer, typically a command to redirect to the next step. If validation fails, it returns a JSON object containing commands for the renderer to display validation messages for specific data attributes. If a database error occurs during update, it triggers a user error.

Parameters

$nextStep : string|null = null: Optional. The URL or action to redirect to after successful update. Defaults to null.

Return values

string —

A JSON string containing commands for the renderer or error information.

removeData()

Removes a dynamically added Data attribute from the Element instance.


    public
                    removeData(string $attributeName) : SC_Element

This method removes a Data attribute that was previously added dynamically using addData(). It unsets the property from the Element instance, removes it from the static list of on-the-fly attributes, and updates the list of data attributes for the current instance.

Parameters

$attributeName : string: The name of the attribute to remove from the Element.

Return values

SC_Element —

The current Element instance, allowing for method chaining.

requiredCheck()

Checks if all required Data attributes of the Element have values.


    public
                    requiredCheck([array<string|int, mixed> $array = array() ]) : array<string|int, mixed>

This method iterates through all Data attributes marked as 'required'. If a required Data attribute is empty and is not an auto-incrementing field, it adds a validation message to the provided array.

Parameters

$array : array<string|int, mixed> = array(): An associative array to which validation messages will be added. The keys are the names of the Data attributes that failed validation.

Return values

array<string|int, mixed> —

The updated array containing validation messages for any required fields that are empty.

save()

Saves the element to the configured DataStorage.


    public
                    save() : mixed

This method checks if the element instance has a unique identifier (ID) set. If an ID is present, it calls the update() method to update the existing record in the data storage. If no ID is present, it calls the create() method to create a new record in the data storage.

Return values

mixed —

The result of the update() or create() operation, typically the number of affected rows or the new ID.

setId()

Sets the value of the Element's unique identifier field.


    public
                    setId(mixed $id) : SC_Element

The field used as the ID is determined by the fieldId property.

Parameters

$id : mixed: The value to set as the unique identifier.

Return values

SC_Element —

The current Element instance, allowing for method chaining.

showAdmin()

Renders the administration view for the Element.


    public
                    showAdmin() : SI_systemScreen

This method generates the main administrative interface for managing Element records. It includes a search form, a list or table displaying existing records, and links or buttons for creating, viewing, updating, and deleting elements.

Return values

SI_systemScreen —

A system screen object containing the administration interface.

showContinusCreate()

Renders a form for continuous creation of new Element instances.


    public
                    showContinusCreate([string|null $template = null ][, bool $partOnly = false ][, string|null $action = null ][, string|null $nextStep = null ]) : mixed

This method is similar to showCreate() but is intended for scenarios where the user needs to create multiple instances consecutively. After a successful creation, the form is typically re-displayed with a success message, allowing the user to immediately create another element without navigating away.

It sets a success message and defines the form action to point to processContinusCreate() which handles the continuous flow. The actual rendering of the form is delegated to the renderer's render method, using the 'showCreate' method as the basis for the form structure.

Parameters

$template : string|null = null: Optional. The template to use for rendering. Defaults to the default template for 'showCreate'.
$partOnly : bool = false: Optional. If true, renders only the content part, not the full page. Defaults to false.
$action : string|null = null: Optional. The URL or action for the form submission. If not provided, it defaults to the result of processContinusCreate().
$nextStep : string|null = null: Optional. The URL or action to redirect to after a sequence of continuous creations is finished. Not typically used in the continuous flow itself, but can be passed.

Return values

mixed —

The rendered output, typically an HTML string representing the continuous creation form.

showCreate()

Renders a form for creating a new instance of the Element.


    public
                    showCreate() : SI_systemScreen

This method generates a user interface for creating a new Element record. It includes a title, a form containing input fields corresponding to the Element's Data attributes that are marked for 'create' and 'show', and submit/cancel buttons. The form is configured to submit data to the processCreate method.

Return values

SI_systemScreen —

A system screen object containing the creation form.

showCreateSelect()

Renders a form for creating a new instance of the Element, intended for scenarios where the newly created element should be selected before the creation of another element usually using SD_ElementContainer.


    public
                    showCreateSelect([string|null $template = null ][, bool $partOnly = false ][, string|null $action = null ][, string|null $nextStep = null ]) : mixed

This method delegates the rendering of the creation form to the renderer, typically reusing the structure defined for showCreate. The form's action is set to processCreateSelect, which handles the creation and subsequent selection logic.

Parameters

$template : string|null = null: Optional. The template to use for rendering. Defaults to the default template for 'showCreate'.
$partOnly : bool = false: Optional. If true, renders only the content part, not the full page. Defaults to false.
$action : string|null = null: Optional. The URL or action for the form submission. If not provided, it defaults to the result of processCreateSelect().
$nextStep : string|null = null: Optional. This parameter is typically not directly used in this method but is included for consistency with other show methods.

Return values

mixed —

The rendered output, typically an HTML string representing the creation form for selection.

showDelete()

Renders a confirmation form for deleting an Element.


    public
                    showDelete() : SI_systemScreen

This method displays the details of the element to be deleted and provides a form with "Delete" and "Cancel" buttons to confirm or abort the deletion. The element's data is first fetched from the data storage using its ID.

Return values

SI_systemScreen —

A system screen object containing the deletion confirmation form.

showEmbeded()


    public
                    showEmbeded() : mixed

Return values

mixed —

showEmbededStrip()

Displays a stripped-down, embedded representation of the Element.


    public
                    showEmbededStrip() : string

This method retrieves Data attributes marked with the "embeded" flag. If the Element has an ID, it first fills the Element's data from the data storage. It then iterates through the embedded Data attributes and concatenates their stripped-down embedded representations, typically suitable for displaying within a compact space.

Return values

string —

A string containing the stripped-down embedded representation of the Element.

showNoAccess()

Displays a message indicating that the user does not have sufficient permissions to access the requested resource or perform the requested action.


    public
                    showNoAccess() : SI_systemScreen

This method creates a simple interface with a title showing the "cannot access" message and a link to a default action or home page, as configured in the SC_Main::$PERMISSIONS. It returns a system screen object containing this content.

Return values

SI_systemScreen —

A system screen object displaying the no access message.

showSearch()

Processes the creation of a new Element record and appends it to a container in the parent's interface via a JSON response.


    public
                    showSearch() : string

usually used with SD_ElementsContainer.

This method handles incoming request data, validates it, attempts to create a new record for the element in the data storage. Upon successful creation, it calls makeChangeSelection() to generate a JSON response containing commands for the renderer to append the newly created element's representation to a container and close any open lightboxes.

If validation fails, it returns a JSON object containing commands for the renderer to display validation messages. If a database error occurs during creation, it triggers a user error.

Return values

string —

A JSON string containing commands for the renderer or error information.

showUpdate()


    public
                    showUpdate() : mixed

Return values

mixed —

showUpdateSelect()


    public
                    showUpdateSelect([mixed $template = null ][, mixed $output = 'AE_basicPage' ][, mixed $messages = null ]) : mixed

Parameters

$template : mixed = null
$output : mixed = 'AE_basicPage'
$messages : mixed = null

Return values

mixed —

showView()


    public
                    showView() : mixed

Return values

mixed —

toArray()

Returns an array representation of the Element, mapping each Data attribute's name as the key and the data attribute's current value as the value.


    public
                    toArray() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An associative array where keys are Data attribute names and values are their current values.

update()

Updates the element's data in the configured DataStorage.


    public
                    update() : mixed

This method first calls processData('preUpdate') to execute any pre-update processing defined for the element's Data attributes. It then delegates the actual update operation to the DataStorage instance's updateElement method. After the update is performed, it calls processData('postUpdate') to execute any post-update processing.

Return values

mixed —

The result of the DataStorage update operation, which typically indicates the success or failure of the update (e.g., number of affected rows).

validateForDB()

Validates the Element's Data attributes before interacting with the DataStorage (e.g., before creating or updating a record).


    public
                    validateForDB() : mixed

This method primarily checks for required Data attributes by calling requiredCheck(). If any required attributes are missing or validation fails during the requiredCheck, it collects the validation messages and throws an SC_ElementValidationException.

This method is typically called internally by methods like create() and update().

Return values

mixed —

viewVal()

Returns the main value of the Element in a format adecute for human reading.


    public
                    viewVal() : mixed

Return values

mixed —

The value of the Element.

SE_Role extends SC_Element in package Application

Table of Contents

Properties

$AdminMsg

$CancelBtnMsg

$CreateBtnMsg

$CreatedMsg

$CreateError

$CreateMsg

$DeleteBtnMsg

$DeletedMsg

$DeleteError

$DeleteMsg

$formMethods

$methodsFamilies

$onTheFlyAttributes

$permissions

$quickDelete

$ReturnBtnMsg

$SearchBtnMsg

$SearchMsg

$storageChecked

$UpdateBtnMsg

$UpdatedMsg

$UpdateError

$UpdateMsg

$ViewBtnMsg

$ViewMsg

$dataAttributes

$datasMode

$dataStorage

$defaultAction

$deleteCriteria

Tags

$exceptionMessages

$fieldId

Tags

$filterCriteria

Tags

$fullyset

$Name

$nameInParent

$NamePlural

$OrderCriteria

$parent

$renderer

$storage

Methods

__call()

Parameters

Return values

__construct()

Parameters

Return values

__toString()

Return values

addData()

Parameters

Return values

addDatas()

Return values

assignAsDatasParent()

Parameters

Tags

Return values

assignDatasName()

Return values

asureRole()

Parameters

Return values

attributesOfClass()

Parameters

Return values

attributesTypes()

Parameters

Return values

attributesTypesWith()

Parameters

Return values

clear()

SE_Role extends SC_Element
in package

Application