Get Started
Download or clone whole repository Rberry. Place content of the src folder into "rberry" folder (or other, but then you have to update paths in config.ini) in the htdocs (or similar folder on web server). Rename app/config.ini.example to config.ini and update accordingly. Rename .htaccess.example to .htaccess and update if neccessary.
Raspberry framework requires Apache (or other web server with PHP) with PHP 7 installed and enabled. You can use for example xampp as your environment. Rberry uses several javascript libraries, that can be accessed from CDN (by default provided in config file) or you can download and installed locally:
- Chart JS for charts
- Font Awesome for icons
- Bootstrap as frontend toolkit
- Cookie js
- Table export
- JSPDF debug
- Vis JS
Paths to libraries are stored in /rberry/app/config.ini
Framework also utilize several js libraries, that are included within project structure and lightweight PHP Fat Free Framework (https://fatfreeframework.com/3.6/home)
To start using Raspberry after installation go to /app/config.ini file and configure database connection. Then go to /rberry/assets and create new application.
To access screen creator for application (for example "demo") you can open browser and enter http://yourhost.com/rberry/demo/edit. "demo" part in the url is name of the folder (application name) in the rberry/assets.
Design page in Screen creator
To access user application (for example "demo") you can use http://yourhost.com/rberry/demo/run in your browser.
Run the page in browser
If you use login screen in your application, you can also access http://yourhost.com/rberry/demo/login.
For configuration of the framework, you need to modify only /app/config.ini file. To start working with framework and open screen creator, you need to configure at least database connection.
- AUTOLOAD - path to framework PHP Core - you don't need to modify
- DEBUG - debug level of the framework
- APP_MODE - DEVEL or PROD
- LOGS - Path to store logs
- LOG_LEVEL (not fully utilized yet) - 0-no log, 1-error, 2-warning, 3-info, 4-trace, 5-trace-with-data
- ONERROR - error handler function - you don't need to modify
- UI - path to UI temlates - you don't need to modify
- UPLOADS - not used yet
- GC_PROJ - name of the framework folder
- site - Name for screen creator
- db - DB Connection string
- db_type - type of database (ORACLE, MSSQL, MYSQL)
- sql_template - path to templates for generating SQL - you don't need to modify
- user_id - if you using user/password for DB connection
- password - if you using user/password for DB connection
- expiry - Number of hours before session expires
- time_format - how timestamps look like on the pages
- max_kb - not used yet
- allowed - not used yet
- eurocookie - display eurocookie notices
- path_gui - path to gui folder
- path_core - path to fremework core folder
- path_apps - path to application subfolders
- path_ui_templates - path to ui template files
- path_ui - path to core UI templates
- path_sql - path to SQL templates
- main_boot_css - path to main bootstrap css file
- path_jquery - path to jquery.min.js file
- path_popper - path to popper.min.js
- path_bootstrap_min - path to bootstrap.min.js
- path_charts - chart.js
- path_font_awesome - path to font-awesome.min.css
- path_chart_js - path to chart.js@2.8.0
Connection to database is provided by SQL class from Fat-Free Framework, which is basically superset of the php PDO class. The connection is created in /app/gen_common class and uses 3 paremters from /app/config.ini file - db (DB Connection), user_id (DB user), password (password).
SQL class supports following database engines:
- MySQL
- sqlite
- PostgreSQL (pgsql)
- SQL Server (sqlsrv)
- Oracle (OCI) (you have to have driver installed and configured for php)
- ODBC
Example of connect string for MySQL stored in config.ini file:
db="mysql:host=db.server.sk;port=3306;dbname=db_test"
-
/rberry
- /app/gen_gui.php - core php framework code used for generating pages
- /app/gen_common.php - common functions (logging, DB connection, error handling), that can be changed based on integration or running environment (specific DB)
- /app/routes.ini - PHP routes for Screen creator and running application
- /app/config.ini - Framework configurations - paths, DB connections, ..
- /app/admin.php - authorization/authentification functions
- /assets/ - 1 folder = 1 application. Application subfolder stores screen configurations in JSON format.
- /db/sql/ - SQL templates for various database systems
- /lib/ - included libraries
- /logs/ - log files
- /tmp/ - runtime temporary files
- /ui/ - Core htm templates for screen creator and general part of the screens (standard headers, javascripts, ..)
- /ui/css/ - bootstrap css files
- /ui/templates/ - UI component templates (for buttons, inputs, tables..)
- /ui/fonts/ - specific fonts (ttf files)
- /ui/images/ - image files
- /ui/js/gs.js - Screen creator javascript code
- /ui/js/help.js - Help text for Screen Creator
- /ui/js/type.js - File with element template configuration. File stores metadata for screen creator - which parameters can be set for elements in screen creator
Database connection, logging and error handling is placed in a simple gen_common class (/app/gen_common.php). You can modify or enhance this file, if you prefer specific features for database connections (sessions, authorization type, PDO parameters..). SQL class from F3 (fatfreeframework) is used, which is basically superset of the PHP PDO class, so you can utlizie the functions and options of the standard PDO driver (for more info about database connection see F3 help: https://fatfreeframework.com/3.6/sql). Log files are stored (standard for F3) in /logs/ folder and files are created per day (one file for all applications). If you want to change the structure of the log, you can modify gen_common->wlog function. gen_common->error function is standard general error handler for framework (if page generation crash).
/app/routes.ini file contains framework routing. Here you can find 3 sections:
- Login pages - you don't need to modify these routes if you want to use framework login. If you want to use some external authentification, you can change routes here
- Application routes - These are standard runtime routes, you don't need to modify these
- Screen Createor routes - If you want to hide screen creator (you only want runtime mode), you can comment out these routes
If you want to use Raspberry without Screen creator (development mode) the best way is to:
- Open app/routes.ini and comment out all Screen Creator routes - this disables access to all Screen Creator screens and APIs
- Remove all assets/*/hist folders with all development history
- Update app/config.ini accordingly (change to prod mode, update log level..)
You can easily enhance or change page rendering with changing element configurations and its template. There are 2 main parts you need to change to modify the way, how the page is rendered.
1. Element metadata - defines, what can be configured via screen creator. It basically describes the parameter name and its type (how it is presented in Screen Creator - text, textarea, select,..). This can be defined in /ui/js/type.js file. In this file you will find common part - these are parameters, that can be configured for every element - and specific elements (for example table, text, button,..).
You can add new parameter prototype /ui/js/type.js file for existing element type or create whole new element type.
Example of "text" element type in type.js file:
"text":{
"subtype":{
"type":"select",
"values":["", "h1", "h2", "h3", "h4","h5", "h6"],
"label":"Heading",
"tooltip":"Heading",
"mandatory":"",
"default":"",
"tab":"Common"
},
"color":{
"type":"select",
"values":["primary", "secondary", "success", "info", "warning", "danger", "light", "dark", "body", "muted", "black-50"],
"label":"Color",
"tooltip":"Text color",
"mandatory":"",
"default":"",
"tab":"Common"
},
"text":{
"type":"textarea",
"label":"Text",
"tooltip":"Text",
"mandatory":"",
"default":"",
"tab":"Common",
"col":"12"
}
}
For every parameter you can define how it will be shown in Screen Creator:
- type - type of field for attribute configuration : text, textarea, select, table, color
- label - label for field
- tooltip - text defined as help for the configuration
- mandatory - Y/N mandatory field
- default - default value for field
- tab - in which tab of Screen creator screen the field will be shown
- helper - context helper (right click) defined for the field: context-input, context-button, context-page, context-css-text, context-css-flex, context-permission, context-fa, context-element, context-modal
2. Element Template HTM templates for elements are stored in /ui/temlates folder. The Raspberry framework renders pages from templates using configuration defined for pages (based on the type.js element prototypes) in /assets/"application"/"page".j files. Fat-Free templating engine is used, so you can use any syntax in the documentation of the F3 framework: https://fatfreeframework.com/3.6/views-and-templates
For standard elements (not more complex like divs or tables) whole configuration is stored in @T_GUI object during page rendering from template, so you can reference element parameters from this variable to get configured value (from page.j file).
Example:
<check if="{{ @T_GUI->fa != '' }}">
<span class="icon {{ @T_GUI->fa }}"></span>
</check>
If you create whole new element you should create new template file (in /ui/temlates) and add path to ui/Screen_template.htm file. Template for new element should be enclosed in the condition for element prototype. Element prototype is stored in variable @T_CODE.
Example of the template for text element:
<check if="{{ @T_CODE=='text' }}">
<div class="form-group
{{ @T_COMMON }}
<check if="{{ @T_GUI->subtype != '' }}">
{{ @T_GUI->subtype }}
</check>
<check if="{{ @T_GUI->color != '' }}">
text-{{ @T_GUI->color }}
</check>
{{ @T_GUI->class }}
">
<span id="{{ @T_ID }}">{{ @T_GUI->text }}</span>
</div>
</check>
Raspberry framework has two main jobs to do:
- Renders pages based on the one-file page configuration (JSON format) from prepared templates.
- Helps user to easily prepare page configuration with Screen creator
Page rendering in Raspberry has basically two modes - preview mode and run mode. Preview mode is GUI generated from templates without data and shown in part of the Screen creator. Run mode is live page rendering mode, where all data is loaded into components (tables, data cards, charts,..) and all processes and checks are fired. To access the page in live (run) mode, you can access URL:
Run mode page rendering consists of several steps:
- Meta generation - Loading bootstrap theme, check or redirect login, home redirect, menu rendering
- Get POST/GET parameters
- Execute SQL before processes
- Generate HTML page tree (based on the page configuration file) from templates
- Load data to components (for tables, data cards, charts an progress bars)
When the button is clicked on the page, these steps are executed:
- Javascript after checks (checks on client side in JS)
- Javascript after processes (executed on client side in JS)
- Get POST parameters
- Execute SQL checks defined for button or general SQL checks
- Execute SQL after processes defined for button or general SQL processes
- Go to page (if defined)
Easy way to prepare page configuration file (page.j stored in the application folder) is to access Screen creator (http://yourhost/rberry/application/edit) and configure the page with live page preview (you can see, how the page will look like in run mode). Other option is to edit the file directly.
Page configuration contains several parts:
- name - page name
- template - not used yet
- settings - contains general page settings. Parameters:
- title
- permission - not used yet
- js - custom javascript
- cass - custom page css
- category - form, report, detail, dashboard
- desc - page description
- before - contains two sections
- Process
- type - SQL/JS
- desc
- code
- mapping - comma separated list of elements used as output from SQL (for select statements)
- binds - comma separated list of elements binded to SQL/JS
- Check
- type - SQL/JS
- level - info, warning, danger
- message - error message shown on the screen
- el - comma separated list of elements, that should be mentioned in the message
- desc - description
- code
- Process
- page - contains page element tree
- after - contains two sections - Check, Process
- Process
- type - SQL/JS
- button - only execute if button (ID) is pressed
- desc
- code
- binds - comma separated list of elements binded to SQL/JS
- Check
- type - SQL/JS
- button - only execute if button (ID) is pressed
- level - info, warning, danger
- message - error message shown on the screen
- el - comma separated list of elements, that should be mentioned in the message
- desc - description
- code
- Process
Process configuration
Page element tree (under page section) contains list of all elements and "sort" array that contains ordering of the elements on top level. Every element contains information about his parent div (parameter "parent") or "Start" if the element is on the top level (start of the tree). Div element types can contain other elements (also another divs) and every div element contain its own "sort" array, which contains ordering of the child elements. From the tree point of view - div elements represent nodes (top node is Start) and other element types are leaves. Rendering of the page is done in the order of the page tree (from top to bottom).
Example of the page configuration file:
{
"name": "form_city",
"template": "Simple",
"settings": {
"title": "Form City",
"permission": "",
"js": "",
"css": "",
"category": "form",
"desc": ""
},
"before": {
"Process": {
"get_id": {
"type": "SQL",
"desc": "Obtain ID",
"code": "select max(id_city)+1 as i_id from L_CITY",
"mapping": "i_id",
"binds": "",
"message": ""
}
},
"Check": {}
},
"page": {
"sort": [
"d_blaank",
"d_top"
],
"d_top": {
"label": "",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "shadow",
"padding": "",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"border": "dark",
"border_radius": "rounded",
"template": "container",
"position": "",
"flex_align_items": "",
"flex_align_self": "",
"flex_justify_content": "",
"flex_grow": "",
"flex_direction": "column",
"flex": "Y",
"carausel_active": "",
"collapse_show": "",
"type": "div",
"sort": [
"d_center",
"d_bottom"
],
"parent": "Start"
},
"d_bottom": {
"label": "",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "3",
"bg_color": "",
"shadow": "",
"padding": "",
"flex_width": "25",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"border": "",
"border_radius": "",
"template": "btn-group",
"position": "",
"flex_align_items": "",
"flex_align_self": "",
"flex_justify_content": "",
"flex_grow": "",
"flex_direction": "",
"flex": "Y",
"carausel_active": "",
"collapse_show": "",
"type": "div",
"sort": [
"b_back",
"b_create"
],
"parent": "d_top"
},
"i_key": {
"label": "Key",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"subtype": "text",
"placeholder": "",
"mandatory": "Y",
"type": "input text",
"parent": "d_center"
},
"i_name": {
"type": "input text",
"label": "Name",
"tooltip": "",
"mandatory": "Y",
"permission": "",
"parent": "d_center",
"padding": "2"
},
"i_valid_from": {
"label": "Valid From",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"subtype": "date",
"placeholder": "",
"mandatory": "N",
"type": "input text",
"parent": "d_center"
},
"i_valid_to": {
"label": "Valid To",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"subtype": "date",
"placeholder": "",
"mandatory": "N",
"type": "input text",
"parent": "d_center"
},
"d_blaank": {
"label": "",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "2",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"border": "",
"border_radius": "",
"template": "",
"position": "",
"flex_align_items": "",
"flex_align_self": "",
"flex_justify_content": "",
"flex_grow": "",
"flex_direction": "",
"flex": "Y",
"carausel_active": "",
"collapse_show": "N",
"type": "div",
"sort": [],
"parent": "Start"
},
"b_back": {
"label": "Back",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"color": "info",
"size": "",
"fa": "",
"action": "",
"goto_page": "report_city",
"mapping": [],
"refresh": "",
"click_js": "",
"modal": "",
"ignore_valid": "Y",
"type": "button",
"parent": "d_bottom"
},
"b_create": {
"label": "Create",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"color": "primary",
"size": "",
"fa": "",
"action": "goto",
"goto_page": "report_city",
"mapping": [],
"refresh": "",
"click_js": "",
"modal": "",
"ignore_valid": "N",
"type": "button",
"parent": "d_bottom"
},
"i_id": {
"label": "",
"label_class": "",
"col": "",
"small": "N",
"tooltip": "",
"margin": "",
"bg_color": "",
"shadow": "",
"padding": "2",
"flex_width": "",
"flex_height": "",
"float": "",
"class": "",
"show_if": "",
"show_if_txt": "",
"read_if": "",
"read_if_txt": "",
"permission": "",
"badge_text": "",
"badge_color": "",
"type": "input hidden",
"parent": "d_center"
}
},
"after": {
"Check": {
"check": {
"type": "SQL",
"level": "danger",
"btn": "b_create",
"message": "Name already exists",
"el": "i_name",
"desc": "",
"code": "select 1 from L_CITY where t_name = :i_name",
"binds": "i_name"
}
},
"Process": {}
}
}
HTM Templates for rendering pages use standard Bootstrap classes (from version 4.3). Style of the components depends on the provided bootstrap css file (or css min file). You can build your css file directly in rberry\ui\css folder from scss or you can use online boostrap builder to generate css file (https://bootstrap.build/app)
Each application can use different bootstrap css file. You can set this in application configuration in Screen Creator or directly in _meta.j file in application folder (parameter "theme"). You can use different style (css file) for screen creator (page preview) and run mode.
One screen configuration, various css templates
Screen creator is page configurator for Raspberry framework. User can organize and configure UI components like inputs, tables, buttons on page with live preview. Preview is without data querying, so user doesn't need all objects accessible in the database. Screen creator doesn't automatically save work to server or file, you need to publish configuration or download (and later import) configuration in the file. If you refresh browser window all work is lost (and you need to load new configuration or start from template).
Top toolbar contains buttons:
- Page structure toggle - You can hide or show page structure tree
- Page configuration - You can open page configuration screen by clicking on the icon. In the text area you can see complete page configuration. You can copy&paste or modify page configurations this way. To load configuration you can click "Import" button. You can also import file with page configuration (upload) or download configuration to the file.
- Publish/Save - Publish page configuration to server (save to application folder). You can see changes in the run mode after publishing.
- Open - Open page configuration from server (from specific appliacation folder). Card icon is shown based on page type (dashboard, report, form, detail..)
- Page Common - You can set title, page type or other general settings for the page.
- Run Page - Run page in new window
- SQL Workbench - SQL Editor for preparing SQL statements for GUI components (for example tables)
- Wizards - Wizards and utilities to create page items faster
- Application logs
- (right part of screen) Application configuration - You can define page theme (name of the bootstrap file) application menu and general settings (login, permissions,..)
- Page name - name of the configuration file as stored in application folder
Left sidebar contains 3 main parts:
-
Before Page Render - Before page render contains two parts - Process and Check. Process part contains two types of commands - SQL and Javascript. SQL process commands can be used to load data (or execute some commands) before the page is rendered (before the HTML is send to client). Javascript commands are executed on document ready part of the screen. Checks are SQL or javascript commands used to generate some messages on the screen (or stop other processing in case of error checks). Same as in the Process part - SQL commands are executed before page render on the backend and javascript commands are executed on document ready. Checks can be of 3 severity levels - info, warning, error. Only errors will stop processing/rendering.
-
Page Tree - "Page" part contains the page elements tree. You can add or remove components under "div" components by right clicking on element and selecting new element type. You can configure element by clicking on the element name in the tree or by double-clicking on the component in the screen preview. The elements on the page are rendered in the order they are defined in the structure tree. You can change order (or parent) by dragging to different location in the tree (dragging icon appears at the end of the element name). You can also change parent div of the item in the element configuration window (after click on the name or double click on element in screen preview). Only "div" elements can contain child elements.
-
After Page Render - After page render also contains two parts - Check and Process (different order as in Before) Two types of checks - SQL and javascript. Javascript checks are executed on client side before page is submited, SQL checks are executed after page submit before after processes. Checks can be assigned to specific button click and can be of 3 severity levels - info, warning, error. Only errors will stop processing/rendering.
Left panel under "Page" part contains the page elements tree. You can add or remove components under "div" components by right clicking on element and selecting new element type. You can configure element by clicking on the element name in the tree or by double-clicking on the component in the screen preview (4). The elements on the page are rendered in the order they are defined in the structure tree. You can change order (or parent) by dragging to different location in the tree (dragging icon appears at the end of the element name). You can also change parent div in the element configuration window (after click on the name or double click on element in screen preview). Only "div" elements can contain child elements.
You can see the preview of the created screen (generated live from page structure) in the right part of the screen. Components are rendered with screen creator default theme (bootstrap file defined in framework config). Running application can use different theme (bootstrap file defined in application configuration). You can double-click on the elements in the preview to open element configuration screen. You can't move the elements or create new elements - you can do that only in the structure tree. Screen preview is not connecting to database, so for example data in tables or select boxes are visible only in run mode. Also checks and processes are executed only in run mode (not preview mode).
To create new application (set of pages with specific menu and style) you need to create new folder in /assets folder (for example demo). Here you need to create application configuration file _meta.j with at least application name (app_name) and used theme (theme). You can change both later via Screen Creator (folder name can't be changed via screen creator). You can access screen creator for new application with url: http://yourhost/rberry/demo/edit (demo is name of the created folder).
{
"theme": "boot",
"app_name": "Demo"
}
To setup general application settings click on the button in the top right corner of screen creator next to the page name. You can setup here:
- CSS Bootstrap File Name - name of the file placed in the /rberry/ui/css folder.
- Application Name - Name of the application shown on the home page
- Use Login - Enable or disable login for users. If enabled, you need to create usr table in the database (script stored in \rberry\db\sql).
- Use Permissions - Not used yet.
You can enable simple user authentication for application in general application settings (enable Use Login). To use this feature, you need to create "usr" table in database accessible by DB user (create script in \rberry\db\sql). When the feature is enabled, created application require users to put login before accessing application pages. Users can also change their passwords. Passwords are stored encrypted in the database table "usr".
When you want to create new user you need to insert new line into "usr" table with only user name (user_txt) filled and leave password (pwd_crypt) empty. User needs to go to to change password screen (from login screen) and change password (old password is same as user name). After changing password database column (pwd_crypt) is filled with encrypted password and user can login to application. Same approach is for resetting password - update column pwd_crypt with null and user can change password trough application (old password is then same as user name).
In the application configuration screen you can setup menu for home page and navigation toolbar. In the menu configuration you can set:
- Group - "HOME" - Menu entry will be placed on the home screen as a card, "TOP" - Menu entry will be placed on the top navigation toolbar, "LEFT" for left navigation menu
- Menu - Menu group in which menu entry will be shown
- Item - Name of the menu entry
- Page - Page name (file name without postfix)
- Permission - Not used yet
- Icon - Font-awesome class to show icon on the home page card
- Description - Description text for the menu entry (shown on home page)
To create new page open Screen Creator (http://yourhost/rberry/demo/edit demo is name of the application folder) in web browser, specify name for the page (top right corner of the screen creator) and you can start adding and configuring elements. After adding elements on the page (inputs, buttons, tables,..) you can publish (save) page and run in run mode (button in the toolbar).
To setup basic page settings click on the 5th button in the toolbar of the Screen Creator. In the page settings, you can set:
- Page Title - used as standard page title
- Description - used for documentation (shown in the card, when browsing pages in the Screen Creator)
- Page Category - used for page categorization (there is also icon shown on the page card based on the category when browsing pages in Screen Creator)
- Permissions - Not used yet
- Javascript - Custom javascript rendered on the page
- CSS Style - Custom css rendered on the page
For creating new HTML elements right click on the respective place in the page tree in the right panel of the Screen Creator and choose element you would like to create. If you right click on the div, new element will be created inside this div. You can't change change element type after creating. You can reorder elements (and divs with underlying elements) with drag and drop functionality (start drag on the icon next to the element).
If you want to open configuration for specific element click on the element name in the page tree or double click directly on the rendered element in the page preview.
The element configuration window (modal popup) contains header section where you define unique element ID and parent div (div elements can be reorganized only via drag&drop function in the page tree) and main area with element configuration organized in the tabs. Except common parameters, every element type contains different set of configurable parameters.
Some of the parameter text fields contain context menu helpers (right mouse button) with recommended values (for example for binding input parameters in SQL in mapping fields, recommending modal divs for buttons,..). Description for the parameters is shown always under parameter label.
Parameters can have default values, that are automatically set for the new element. This can be modified in the element type configuration in /rberry/ui/js/type.js for every parameter.
Some of the parameters, that are rendered as text (for example labels), can contain specific {{ i_input }} syntax for placing values from input elements.
For better styling reasons you can use only basic bootstrap color schema for coloring the components. If you want to change one of the color from the schema, create your own bootstrap template (css file) with custom colors. For more info see Bootstrap documentation (https://getbootstrap.com/docs/4.0/utilities/colors/)
Basic colors:
- primary
- secondary
- success
- danger
- warning
- info
- light
- dark
There are several parameters, that can be set for all element types. Parameters, that can be set for all element types, are defined by /rberry/ui/js/type.js in section common and rendered (most of them) with /rberry/ui/templates/common.htm.
There are 4 type of parameters, that can be set for most of the elmenets:
- Common parameters - general parameters like label, label class, small, tooltip, component shadow..
- Layout parameters - layout parameters for elements like padding, margin and how they are placed within the flex system (aligning, stretching,..)
- Render conditions - you can define conditions (SQL or javascript types) for rendering the compoment or setting the compomenet to be read only.
- Badge - many elements can have badge (small notificaiton icon with info) to show some value. Here you can set text (you can use input replace syntax - {{ i_input }}) and color for this.
Div represents standard HTML div and is main element for organizing other elements to specific layout. Div is only element, that can be used as node in the page tree (can have child elements).
There are several templates of div:
- jumbotron - standard Bootstrap Jumbotron. It serves as big box for calling extra attention for content or information
- card - small container with specific header
- form-group - container for grouping several inputs together
- form-row - grid system for organizing inputs in the container
- container/container-fluid - standard container for storing other elements
- list-group - container for organizing elements in list
- btn-group - container for organizing buttons
- modal - specific type of div to create modal window.
- carousel/carousel-item - specific divs for creating sliding containers
- collapse - collapsible container useful when you want to hide and show content. You can set, if the collapsible div is by default collapsed in the "Custom" tab with "Collapse default show" parameter
If you want to create a modal window you need to create specific div with "modal" template. You can place him anywhere in the page tree, because everything inside this div will be only visible in the specific modal popup after button click (or manual modal show). When you have modal div in your page tree, you can start placing other elements (divs, inputs, ..) into the div subtree to create the content of the modal popup window.
To open a modal window, you need a button, where you can set action type to "modal" and in the "Open Modal DIV" parameter place ID of the modal div (you can use context menu helper with right click on the text field).
You can create sliding regions (divs) with carousel template. First you need to create in your page tree one div with "carousel" template. Then you can create several child divs with "carousel-item" templates. One of the carousel item divs should be set as default active (will be shown as first on the page load) in the "Custom" tab in "Carousel active" parameter. Carousel div should contain only carousel-item divs as child nodes.
Div elements are main elements for creating page layout and organizing other elements. You can set parameters under "Layout" tab to configure the behavior of the div element and it's child elements. To understand the flex attributes of the Bootstrap see Documentation.
Element for creating buttons. You can set custom buttom parameters (in addition to common parameters) like button color (using Bootstrap color schema in "Common" section.
You can set 3 main types of actions for button (you can add others with javascripts) after click:
- goto - submit page and goto specified page after processes and checks are executed (After part defined in the page configuration. more ). If you want to stay on same page (with inputs maintained) put . in "Goto page" parameter. To go to other page withing application set the name of the page (page file name without postfix) in the "Goto page" parameter. If you want to push some parameters to other page remap parameters in the "Parameter mapping" table.
- refresh - you can refresh data in table, chart, progress and data card elements. You can put comma separated list of elements (ID) in the "Refresh Element".
- modal - open a modal window specified in the "Open Modal DIV". You can also specify "Refresh Element" list to refresh specific elements together with modal open.
If you want to create custom action, you can put the javascript code in the "On Click" text area. This will be executed on the on click event.
By default, after button click all general validations (not configured on the specific element) and mandatory checks (for inputs, that are set as mandatory) are executed. If you want to skip these (for example for back buttons), set "Ignore general validations" to Y. Validations specified directly on this element will be executed always.
Inputs are (like in html) elements to transport values between client and server. Input elements can be referenced as bind variables in the SQL queries for example in before/after processes and checks, data queries (for tables, charts,..) or mapping variables for before process (load data into elements).
By default, pages are submited as POST action, so no values are visible in the URL. If you want to set some value in the URL (GET method), set "GET Allowed" in "Common" tab to Y. You can set the value for such input in URL: page?i_parameter=value.
There are 4 types of input elements:
Standard one row text field. You can set subtype of the text field (text, number, date,..) to help browser and user type of values, that can be entered. You can set text field as mandatory ("Common" tab).
Multi-row text area field. You can set number of rows in "Common" section.
Select one value input. You have two options ("Subtype of field") to set the values in the list:
- list - in the values you will specify all options with syntax: label1:value1,label2:value2
- sql - you specify sql query, that will return two columns - label and value
"label" is shown in the screen and "value" is the value set in the input element as selected value.
You can add empty option (NULL value) by setting "Add NULL" parameter in the "Common" tab.
input hidden
Hidden input is not visible on the page screen but is rendered as "hidden" input type html element. You can create hidden inputs if you need to store values, but you don't need to modify them or show them on the form. You can still show values from hidden inputs on some text parameters (like labels, text in the text element,..) when refrencing hem with replace syntax {{ i_input }}, where such input will be replaced with respective value.
Text element is simple element to present text. You can enhance text with values from the inputs by using replace syntax {{ i_input }}.
This is specific version of text element, where you can use MD syntax and this will be autatically rendered using markdown engine implemented in Fat-Free framework to html. To see available syntax see Markdown documentation
This is specific version of text element, where you can use HTML syntax.
Table is one of the data element (element, that can load data from database), that renders results from database query into html table. The main configuration section for table is "Data" tab, where you specify SQL statement and define columns.
You can place SQL query in the text area parameter "SQL" together with bind variables (syntax :i_input) that you explicitly specify in comma separated format in the "binds" text area (you can use right click to recommend the inputs). SQL statements should be without "order by" clause. Easy way to prepare SQL statemnt (together with columns) is to open the SQL Workbench (7th button in the toolbar), select the table element ID from dropdown (table element must exists and contain at least some text in SQL) and prepare the query in the text area. When you execute the statement, you will obtain results in the table with two headers - DB column name and recommended label. You can change the label direclty here (if you want to ignore it, put "." as the label). You can test queries also with bind variables. When you finished working on the SQL you can store it (together with column and label definitions) by clicking on the arrow button next to dropdown list.
In the column definition ("Data"->"Columns") you can configure:
- column - name of the DB column as is returned by SQL statement. You can get names automatically from query result in the SQL Workbench
- label - rendered column header in the page
- page - you can put name of the page (file name without postfix), if you want to create link to other page on this column.
- parameter - you can specify parameter name in target page (if the page is set) or input element in the page when using select into function
- value constant value, that will replace the value from data. This can be used, if the column is link and you want to place label on the link rather then column value (for example "edit" label)
- icon - FA class, that will be used in button, that will replace value from database
- class - CSS class used to style the column (or component if selected)
-
component - value from the column will be rendered as component:
- FA - value returned from the query result will be rendered as font awesome icon
- PROGRESS - value returned from the query result should be numeric value between 0-100 and will be rendered as progress bars
- YN - value returned from the query result should have values Y or N and will be rendered as icon
- BADGE - value will be placed in badge (style defined in class)
- HIGHLIGHT - value should be color (primary, secondary, warning, danger,..) to highlight row. Column is not visible in table.
- CHART_LINE - value should be comma separated list of numbers (example:13,4,5)
- CHART_PIE - value should be comma separated list of numbers. Colors are assigned based on position in the list (primary, secondary,..)
- LONG - long texts are shortened. Full text is in tooltip.
You can create input element from table by putting value (name of the DB column) into "Input column" parameter ("Data" tab). When filled, check button appears as first column in table and element can be used as standard input (for example as bind variable).
You can set several specific parameters in "Table" tab:
- Rows per page - if set, not all rows will be rendered in the table, but paging will be used on the table with specified number of records per page
- Sortable - if set, column headers will contain arrows to order query result in ascending or descending order
- Autoload data - if set, data is automatically loaded into table on page load. If not set, you need to trigger refresh with button to load data.
- Select into - Rows will have button to store row values to input parameters specified in columns->parameter. Value is Font awesome class for icon.
- Select into - hide modal - Hide modal windows after click on the row button
You can change responsivness (responsive or specific table size) in the "Common"->"Table Responsive" parameter
Data card is one of the data element (element, that can load data from database), that renders results from database query into name-value lines. The main configuration section is "Data" tab, where you specify SQL statement and define columns.
You can set SQL statement and define column same way as for table except links configuration (goto page or select into).
You can specify parameters for lines in the "Lines" tab:
- Justify Lines - justify label and values in the line (common value is between and around)
- Line Classes - you can specify class for lines
Progress is one of the data element (element, that can load data from database), that renders results from database query into progress bar. The main configuration section is "Data" tab, where you specify SQL statement. SQL statement can contain bind variables, that are explicitly specified in comma separated list in "Binds" text area.
You can set autorefresh for progress bar in "Auto Refresh (in sec)" parameter.
Chart is one of the data element (element, that can load data from database), that renders results from database query into chart using chart.js charting library. The main configuration section is "Dataset" tab, where you specify SQL statement (only one dataset at the moment). SQL statement can contain bind variables, that are explicitly specified in comma separated list in "Chart"->"Binds" text area.
You can set autorefresh for progress bar in "Auto Refresh (in sec)" parameter.
The subtype of the chart is set in the "Common"->"Chart Type", where you can set:
- line
- bar
- pie
- horizontal bar
- doughnut
- radar
- polar area