HOME | DOCUMENTATION

📗 Front widgets

Introduction
Add view
forms field
Breadcrumb
Pagination
Charts
Answers messages
Ajax Request

# Introduction

The Epaphrodites framework incorporates a variety of specific widgets nested within macros. These preconfigured widgets represent modular templates usable in components such as forms, pagination systems, breadcrumbs, and more. Their versatility lies in simplifying the design and integration process, thereby contributing to an optimal and seamless user experience. Leveraging these predefined functionalities firmly establishes Epaphrodites-framework as a robust foundation, fostering intuitive navigation and user-friendly interactions within your application or website.

# Add view

To quickly generate a view, run the command heredia create:front from the terminal or PowerShell. By default, all views for your application are stored in the public/views/main directory when you use main or public/views/admin directory when you use admin

This example shows the command to create a view file in the main/ folder.

php heredia create:front main test_new_view

This example shows the command to create a view file in the admin/ folder.

php heredia create:front admin@folder_choosen_or_controllers_folder test_new_view

When generating a view, you have the option to adapt it according to the specific needs of your project. Epaphrodites uses technologies such as twig, HTML, CSS, and JavaScript on the client side, requiring knowledge of these technologies to customize the display according to your requirements.
A view is defined between the {% block content %} and {% endblock %} tags and inherits from a global layout file called layouts.

Here is an example of a View generated from the previous command :

                    
                    
                        {% extends layouts %}
{% from breadcrumb import breadcrumb_field %}
{% from message import alert_msg %}
{% from forms import input_field , loader , import_field , submit %}
{% from pagination import dataTable_pagination, pagination_field %}
{% block content %}
  <div class='container-fluid admin'>
    <h1>SUCCESS - VIEWS CREATED</h1>
    <hr>
    {{ __msg('site-title') }}
  </div>
{% endblock %}

from	import	Description
`breadcrumb`	`breadcrumb_field`	Displays the breadcrumb trail for structured navigation within the application.
`message`	`alert_msg`	Displays alert messages to inform the user of actions or errors.
`forms`	`input_field`	Creates an input form field with the provided parameters.
`forms`	`select_field`	Creates a selection field in a form with the specified options.
`forms`	`textarea_field`	Creates a multiline text field for entering more detailed information.
`forms`	`radio_field`	Creates a form field with radio options, allowing the user to choose one option from several.
`forms`	`checkbox_field`	Creates a form field with checkboxes allowing multiple options to be selected.
`forms`	`multiSelect_field`	Creates a form field that allows multiple options to be selected simultaneously.
`forms`	`import_field`	Creates a form field for importing a file or data.
`forms`	`submit`	Creates a button to submit a form with the filled data.
`pagination`	`dataTable_pagination`	Adds pagination to data tables for easy navigation between pages.
`pagination`	`pagination_field`	Enables navigation between different result pages in a data table.
`charts`	`charts`	Displays various types of charts such as pie charts, bar charts, line charts, and more.
`charts`	`echarts`	Integrates the `echarts` library to render dynamic charts like bars, lines, or pies.
`charts`	`xChart`	Uses the `xChart` library to generate clean and minimalist charts.
`charts`	`scattedChart`	Displays scatter plots only, typically used to represent data point clouds.

# forms field

Epaphrodites-framework offers a variety of form field templates available in the following file: public/layouts/widgets/__widgets.forms.html.twig. These templates include options such as selection fields, input areas, buttons, and a wide range of other functionalities. You have the freedom to customize them and even add new fields to specifically cater to the needs of your various projects. This is some exemples :

input_field

                    
                    
                        {{ input_field(
    {
     label : 'your input label',
     name : 'your_input_name',
     type : 'text',
     placeholder : 'your input placeholder',
     value : 'if_init_value_exist',
     id : 'input_id',
     upper : true,
     maxlength : 30,
     require : true,
     character : 'string',
     feedback :'Please enter your feedback and continue.'
    }
)}}

key	Description
`label`	Defines the label that will be displayed for a form field or input element.
`name`	Specifies the name of the form element, used for identifying the data when submitting the form.
`type`	Defines the type of input (e.g., text, password, email) for a form element.
`placeholder`	Provides a hint to the user about what to enter in the form field, typically shown as grayed-out text within the input.
`value`	Specifies the default or current value of the form field, often used to pre-fill inputs or capture user input.
`id`	Assigns a unique identifier to a form element, useful for styling or targeting the element via JavaScript.
`upper`	Determines if the input value should be converted to uppercase automatically.
`maxlength`	Specifies the maximum number of characters allowed in an input field.
`require`	Indicates whether the form field is mandatory to be filled out before submission.
`character`	Specifies the type of characters allowed in an input field (e.g., letters, numbers, special characters).
`feedback`	Provides feedback or messages about the validity or status of the input field, often used to indicate success or errors.

select_field

                    
                    
                        {{ select_field(
    {
     label : 'your input label',
     name : 'your_input_name',
     class : 'select_class',
     init : 'your select content init',
     value : 'label',
     selected : 'label',
     datas : [ { '_id' : 1, 'label' : 'Test label 1' }, { '_id' : 2, 'label' : 'test label 2' } ],
     id : 'select_id',
     require : true,
     onchange : "testForm();",
     position : position
    }
)}}

key	Description
`label`	Defines the label that will be displayed for a form field or input element. This key allows specifying descriptive text for the element.
`name`	Specifies the name of the form element. This name is essential for identifying and retrieving data upon form submission.
`class`	CSS classes applied for styling or JavaScript interactions.
`init`	Initial value or example text displayed by default.
`value`	Designates a data key.
`selected`	Designates a data key.
`datas`	Array containing available options as objects with keys and values such as `_id` and `label`.
`id`	Unique identifier for the field, useful for CSS and JavaScript targeting.
`require`	Indicates whether the field is mandatory and must be filled before the form can be submitted.
`onchange`	Specifies actions to take when a field's value changes, enabling dynamic responses to user input.
`position`	The default value.
`select2`	This key is used to indicate the integration of the Select2 library, which enhances the interface of select elements such as dropdown menus.

import_field

                    
                    
                        {{ import_field(
    {
     label : 'your import label',
     name : 'your_import_name',
     size : '5Mo',
     accept : '.png/.jpg',
     id : 'import_id',
     value : 'import_init_value',
     feedback : 'import field feedback',
     placeholder : 'your input placeholder',
    }
)}}

Key	Description
`label`	The display label for the import field (e.g., `'your import label'`).
`name`	The identifier for the field when the form is submitted (e.g., `'your_import_name'`).
`size`	Maximum allowed file size (e.g., `'5Mo'` for 5 megabytes).
`accept`	Allowed file extensions (e.g., `'.png/.jpg'`).
`id`	Unique HTML ID for the field (e.g., `'import_id'`).
`value`	Initial/prefilled value (e.g., `'import_init_value'`).
`feedback`	User guidance or validation message (e.g., `'import field feedback'`).
`placeholder`	Hint text displayed when the field is empty (e.g., `'your input placeholder'`).

textarea_field

                    
                    
                        {{ textarea_field(
    {
     label : 'your textarea label',
     name : 'textarea_name',
     class : 'select_class',
     value : 'init_value',
     maxlength : 100,
     rows : 3,
     feedback :'Please enter your feedback and continue.',
     placeholder :'your input placeholder'
    }
)}}

Key	Description
`label`	The display label for the textarea field (e.g., `'your textarea label'`).
`name`	The identifier for the field when the form is submitted (e.g., `'textarea_name'`).
`class`	CSS classes for styling or JavaScript targeting (e.g., `'select_class'`).
`value`	Initial/prefilled text content (e.g., `'init_value'`).
`maxlength`	Maximum number of characters allowed (e.g., `100`).
`rows`	Visible number of text lines (e.g., `3`).
`feedback`	Guidance or validation message (e.g., `'Please enter your feedback and continue.'`).
`placeholder`	Hint text displayed when the field is empty (e.g., `'your input placeholder'`).

checkbox_field

                    
                    
                        {{ checkbox_field(
    {
     class : 'checked_class',
     name : 'checked_name',
     id : 'checked_id',
     require : 'true',
     disabled : 'false',
     label : 'your_checked_label'
})}}

Key	Description
`class`	CSS classes for styling the checkbox
`name`	Name attribute for form submission
`id`	Unique identifier for the checkbox
`require`	Whether the checkbox must be checked to submit the form
`disabled`	Whether the checkbox is interactive
`label`	Text displayed next to the checkbox

radio_field

                    
                    
                        {{ radio_field(
    {
     class : 'radio_class',
     name : 'radio_name',
     id : 'radio_id',
     checked : 1,
     value : [1, 0],
     label : ['Active', 'Disabled']
})}}

Key	Description
`class`	CSS classes for styling or JavaScript interactions (e.g., `'radio_class'`).
`name`	Radio group identifier (e.g., `'radio_name'`). All buttons sharing the same name belong to the same group.
`id`	Unique field identifier (e.g., `'radio_id'`).
`checked`	Determines if the option is selected by default (e.g., `1` or `0`).
`value`	Array of values for each option (e.g., `[1, 0]`). The first value corresponds to the first label, etc.
`label`	Array of display labels for each option (e.g., `['Active', 'Disabled']`). Must match the length of the value array.

actions_field

                    
                    
                        {{ actions_field(
    {
     name : 'your_action_name'|default('_sendselected_'),
     datas : data.ActionsUsers(),
     export : 'your_export_list_title',
     pagination : pagination_field( current , nbrePage , total ),
    }
)}}

Key	Description
`name`	Action identifier name. Defaults to `'_sendselected_'` if not specified. Format: `'your_action_name'\|default('_sendselected_')`
`datas`	Dataset containing available actions. Typically generated from `data.ActionsUsers()`. Structure: Array of objects with action definitions (e.g., buttons, dropdown items).
`export`	Title for export functionality (e.g., `'your_export_list_title'`). Enables data export features when specified.
`pagination`	Pagination configuration using `pagination_field()` with: - `current`: Current page number - `nbrePage`: Items per page - `total`: Total items count Example: `pagination_field(current, nbrePage, total)`

submit

                    
                    
                        {{ submit(
    {
     label : 'your submit label',
     class : 'select_class',
     icon : 'bi bi-save',
     color : '#d32b01'
    }
)}}

Key	Description
`label`	The text displayed on the submit button (e.g., `'your submit label'`).
`class`	CSS classes for styling the button (e.g., `'select_class'`).
`icon`	Icon class(es) to display alongside the label (e.g., `'bi bi-save'` for Bootstrap Icons).
`color`	Custom color for the button in HEX format (e.g., `'#d32b01'`).

# Breadcrumb

Breadcrumbs are quick and easy ways to navigate between pages. Epaphrodites-framework offers predefined templates that you can use or modify according to the needs of your project. This is the Breadcrumbs file path : public/layouts/widgets/__widgets.breadcrumb.html.twig

                    
                    
                        {{ breadcrumb_field({
     'your title' : 'path',
     'your title' : 'path',
     'your title' : 'path',
     'your title' : null
})}}

Key	Value	Description
`title`	string	Display text for the breadcrumb item (e.g., `'Home'`)
`path`	string\|null	Clickable link (e.g., `'/home'`) or `null` for the current non-clickable item

# Pagination

Epaphrodites offers two distinct pagination models: a standard model suitable for a variety of content and a specific model optimized for dataTables. The standard model ensures classic navigation between pages, while the dataTable model is designed for more efficient handling of tabular data, providing specific features for optimized exploration and navigation. These diverse pagination models aim to precisely address the specific requirements of content presentation and manipulation for different data types and uses.
This is the pagination file path : public/layouts/widgets/__widgets.pagination.html.twig

Standart pagination

                    
                    
                        {{ pagination_field(
     'current_page',
     'page_number',
     'total_datas',
)}}

Parameter	Type	Description
`current_page`	integer	The currently active page number (1-based index)
`page_number`	integer	Number of items to display per page
`total_datas`	integer	Total number of items across all pages

dataTable pagination

                    
                    
                        {{ dataTable_pagination(
     "This parameter is optional: you can input 'true' or leave it blank.")}}

# Charts

Displaying graphs in an application generally requires the use of graphical libraries, user interface frameworks, or specialized tools, while considering the specific needs for customization and interoperability of the application. The Epaphrodites framework offers predefined templates that you can use as-is or customize according to your project requirements.. This is the Breadcrumbs file path : public/layouts/widgets/__widgets.charts.html.twig

                    
                    
                        <canvas id="your_id" style="width:100%;max-width:100%" align="center"></canvas>

{{ charts(
    {
     id : 'your_id',// Unique identifier for your chart
     label : 'your_chart_name',// Name of your chart
     orientation : 'chart_orientation',
     position : 'legend_position',
     pourcentage : 'chart_in_precentage',
     datasets : [
          {
             chartType : 'line',// Chart type (accepts: pie, doughnut, bar, line, polarArea, radar)
             label : 'dataset_label',// Label for the dataset
             values : [ 'value', 'value1', 'value2', 'value3' ],,// Key representing the values of your dataset
             keys : [ 'title', 'title1', 'title2', 'title3' ],// Key representing the titles of your dataset
             data: [// Chart data
                { "value": 12969, "title": "JANUARY" },
                { "value1": 1530, "title1": "FEBRUARY" },
                { "value2": 24593, "title2": "MARCH" },
                { "value3": 6465, "title3": "APRIL" }
             ],
             border : 0.5,// Border thickness
             radius : 0.4,// Radius (relevant for circular charts)
             borderColor : '#d32b01',// Border color
             color: ['#056daa', '#ca9802', '#00738c' , '#6c048e']// Colors of the chart elements
          }
     ]
    }
)}}

Key	Description
CHART CONFIGURATION
`id`	Unique DOM identifier for the chart container
`label`	Title/name of the chart
`orientation`	Chart display orientation
`position`	Legend position relative to chart
`pourcentage`	Display values as percentages
DATASET CONFIGURATION
`chartType`	Type of chart visualization
`label`	Dataset label for legend/tooltips
`values`	Key for numeric values in data objects
`keys`	Key for labels in data objects
`data`	Chart data points
`border`	Border thickness (in pixels)
`radius`	Radius percentage for circular charts (0-1)
`borderColor`	Border color (hex/rgb/hsl)
`color`	Color palette for chart elements

# Answers messages

Epaphrodites-framework offers various methods to handle displaying messages after sending client-side requests to the server. These methods enable effective communication of server responses to the user interface, thereby simplifying the management and presentation of the obtained responses following request execution. Additionally, this feature provides the flexibility to customize these messages or add new ones, tailored to the specific needs of the application. This is the Breadcrumbs file path : public/layouts/widgets/__widgets.messages.html.twig

                    
                    
                        {{ alert_msg(
     'anwser_content',
     'bootstrap color (e.g : danger/succes)'
)}}

                    
                    
                        /**
 * @param string $alert
 * @param string $answers
 * @return string
*/
public function msgStandart(string $alert , string $answers):string
{
    $icon = ($alert == 'alert-success') ? '<i class="bi bi-check-square me-2">' : '<i class="bi bi-exclamation-triangle me-2">';
}

# Ajax Request

Epaphrodites-framework provides a straightforward method for sending Ajax requests, utilizing a simplified implementation model. This method ensures optimal handling of Ajax requests by ensuring seamless integration. Its functionality is based on the structure specified in the following file: public/layouts/widgets/__widgets.ajax.html.twig.

Send with ajax request

                    
                    
                        {{ send_ajax_request(
    {
     method : 'POST',
     form : '#your_form_id',
     submit : '#your_submit_id',
     msg : '#your_result_id',
     value : [ 'param' ],
     url : 'your_path',
    }
)}}

Key	Description
`method`	HTTP request method (e.g., `'POST'` or `'GET'`). Default: Typically 'POST' for form submissions Determines how form data is transmitted to the server.
`form`	CSS selector for the form element (e.g., `'#your_form_id'`). All form data will be automatically collected and sent.
`submit`	CSS selector for the submit button (e.g., `'#your_submit_id'`). Used to trigger the AJAX request when clicked.
`msg`	Response container selector (e.g., `'#your_result_id'`). Displays server responses or validation messages.
`value`	Additional parameters to send (e.g., `['param']`). Array of key-value pairs to include with the form data.
`url`	Target endpoint URL (e.g., `'your_path'`). Note: Can be relative (e.g., '/api/submit') or absolute.

Get with ajax request

                    
                    
                        {{ get_ajax_request(
    {
     method : 'POST',
     msg : '#your_result_id',
     url : 'your_path',
     type : 'data_type',
     time : 'your_timer'
    }
)}}

Key	Description
`method`	HTTP method used for the request (e.g., `'POST'` or `'GET'`). Determines how data is sent to the server.
`msg`	CSS selector for the element displaying the response (e.g., `'#your_result_id'`). This element's content will be updated with the server response.
`url`	API endpoint path to query (e.g., `'your_path'`). Can be a relative or absolute URL.
`type`	Expected response data type (e.g., `'data_type'`). May influence response processing (JSON, HTML, text, etc.).
`time`	Execution delay timer (e.g., `'your_timer'`). Can specify a delay in milliseconds before sending the request.

Previous Next