Igor Sverdlov
and 1 contributors

Name

QBit::Application - base class for create applications.

Description

It union all project models.

RO accessors

  • timelog

Package methods

init

Initialization application.

It is done:

  • Set options ApplicationPath and FrameworkPath

  • Read all configs

  • Install die handler if needed

  • Set default locale

  • Initialization accessors (see "set_accessors")

  • Preload accessors if needed

No arguments.

Example:

  my $app = Application->new(); # Application based on QBit::Application

set_accessors

Set accessors. Initialization accessors - one of the steps in sub "init". If you used set_accessors after init, call sub init_accessors.

You can use standard way for set accessors

  use Application::Model::Users accessor => 'users';
  use QBit::Application::Model::RBAC::DB accessor => 'rbac', models => {db => 'app_db'};

But use this method preferable.

Reserved keys:

  • accessor

  • package

  • models

  • init

  • app_pkg

Arguments:

  • %accessors - Accessors (type: hash). Keys is accessor name, values is options for import.

Example:

  __PACKAGE__->set_accessors(
      app_db => {
          package => 'Application::Model::DB',             # key "package" required (Package name)
      },
      rbac => {
          package => 'QBit::Application::Model::RBAC::DB',
          models => {                                      # key "models" redefine accessors into rbac
              db => 'app_db'
          },
      },
  );

  # or run time

  $app->set_accessors(...);
  $app->init_accessors();

  #after

  $app->app_db; # returns object of a class "Application::Model::DB"
  $app->rbac;   # returns object of a class "QBit::Application::Model::RBAC::DB"

  $app->rbac->db; # returns object of a class "Application::Model::DB", but into package used "QBit::Application::Model::DB::RBAC"

init_accessors

Initialization accessors. Used after calling set_accessors in run time a code

No arguments.

Example:

  $app->set_accessors(...);
  $app->init_accessors();

config_opts

Set options in config

Arguments:

  • %opts - Options (type: hash)

Example:

  __PACKAGE__->config_opts(param_name => 'Param');
  
  # later in your code:
  
  my $param = $app->get_option('param_name'); # 'Param'

use_config

Set a file in config queue. The configuration is read in sub "init". In the same place are set the settings ApplicationPath and FrameworkPath.

QBit::Application options:

  • locales - type: hash

      locales => {
          ru => {name => 'Русский', code => 'ru_RU', default => 1},
          en => {name => 'English', code => 'en_GB'},
      },
  • preload_accessors - type: int, values: 1/0 (1 - preload accessors, 0 - lazy load, default: 0)

  • install_die_handler - type: int, values: 1/0 (1 - set die handler qbit::Exceptions::die_handler, default: 0)

  • timelog_class - type: string, values: QBit::TimeLog::XS/QBit::TimeLog (default: QBit::TimeLog - this is not a production solution, in production use XS version)

  • locale_domain - type: string, value: <your domain> (used in set_locale for Locale::Messages::textdomain, default: 'application')

  • find_app_mem_cycle - type: int, values: 1/0 (1 - find memory cycle in post_run, used Devel::Cycle, default: 0)

QBit::WebInterface options:

  • error_dump_dir - type: string, value: <your path for error dumps>

  • salt - type: string, value: <your salt> (used for generate csrf token)

  • TemplateCachePath - type: string, value: <your path for template cache> (default: "/tmp")

  • show_timelog - type: int, values: 1/0 (1 - view timelog in html footer, default: 0)

  • TemplateIncludePaths - type: array of a string: value: [<your path for templates>]

      already used:
      - <project_path>/templates         # project_path   = $self->get_option('ApplicationPath')
      - <framework_path>/QBit/templates  # framework_path = $self->get_option('FrameworkPath')

QBit::WebInterface::Routing options:

  • controller_class - type: string, value: <your controller class> (default: QBit::WebInterface::Controller)

  • use_base_routing - type: int, values: 1/0 (1 - also use routing from QBit::WebInterface::Controller, 0 - only use routing from QBit::WebInterface::Routing)

Arguments:

  • $filename - Config name (type: string)

Example:

  __PACKAGE__->use_config('Application.cfg');  # or __PACKAGE__->use_config('Application.json');

  # later in your code:

  my preload_accessors = $app->get_option('preload_accessors');

read_config

read config by path or name from folder "configs".

  > tree ./Project

  Project
  ├── configs
  │   └── Application.cfg
  └── lib
      └── Application.pm

Formats:

  • cfg - perl code

      > cat ./configs/Application.cfg
    
      preload_accessors => 1,
      timelog_class => 'QBit::TimeLog::XS',
      locale_domain => 'domain.local',
      TemplateIncludePaths => ['${ApplicationPath}lib/QBit/templates'],
  • json - json format

      > cat ./configs/Application.json
    
      {
        "preload_accessors" : 1,
        "timelog_class" : "QBit::TimeLog::XS",
        "locale_domain" : "domain.local",
        "TemplateIncludePaths" : ["${ApplicationPath}lib/QBit/templates"]
      }

Arguments:

  • $filename - Config name (type: string)

Return value: Options (type: ref of a hash)

Example:

  my $config = $app->read_config('Application.cfg');

get_option

Returns option value by name

Arguments:

  • $name - Option name (type: string)

  • $default - Default value

Return value: Option value

Example:

  my $salt = $app->get_option('salt', 's3cret');

  my $stash = $app->get_option('stash', {});

set_option

Set option value by name.

Arguments:

  • $name - Option name (type: string)

  • $value - Option value

Return value: Option value

Example:

  $app->set_option('salt', 's3cret');

  $app->set_option('stash', {key => 'val'});

cur_user

set or get current user

Arguments:

  • $user - hash ref

Return value: hash ref

    my $user = {id => 1};

    $cur_user = $app->cur_user($user); # set current user

    # if use rbac
    # {id => 1, roles => {3 => {id => 3, name => 'ROLE 3', description => 'ROLE 3'}}, rights => ['RIGHT1', 'RIGHT2']}
    # or
    # {id => 1}

    $cur_user = $app->cur_user(); # return current user or {}

    $app->cur_user({}); # remove current user

set_cur_user_rights

set rights for current user

Arguments:

  • $rights - array ref

    $app->set_cur_user_rights([qw(RIGHT1 RIGHT2)]);

revoke_cur_user_rights

revoke rights for current user

Arguments:

  • $rights - array ref

    $app->revoke_cur_user_rights([qw(RIGHT1 RIGHT2)]);

refresh_rights

refresh rights for current user

    my $cur_user_id = $app->cur_user()->{'id'};

    $app->rbac->set_user_role($cur_user_id, 3); # role_id = 3

    $app->refresh_rights();

get_models

Returns all models.

No arguments.

Return value: $models - ref of a hash

Examples:

  my $models = $app->get_models();

  # $models = {
  #     users => 'Application::Model::Users',
  #     ...
  # }

get_registered_rights

Returns all registered rights

No arguments.

Return value: ref of a hash

Example:

  my $registered_rights = $app->get_registered_rights();
  
  # $registered_rights = {
  #     view_all => {
  #         name  => 'Right to view all elements',
  #         group => 'elemets'
  #     },
  #     ...
  # }

get_registered_right_groups

Returns all registered right groups.

No arguments.

Return value: $registered_right_groups - ref of a hash

Example:

  my $registered_right_groups = $app->get_registered_right_groups();

  # $registered_right_groups = {
  #     elements => 'Elements',
  # }

check_rights

Check rights for current user.

Arguments:

  • @rights - array of strings or array ref

Return value: boolean

Example:

  $app->check_rights('RIGHT1', 'RIGHT2'); # TRUE if has rights 'RIGHT1' and 'RIGHT2'

  $app->check_rights(['RIGHT1', 'RIGHT2']); # TRUE if has rights 'RIGHT1' or 'RIGHT2'

set_app_locale

Set locale for Application.

Arguments:

  • $locale_id - type: string, values: from config (key "locales")

Example:

  $app->set_app_locale('ru');

set_tmp_app_locale

Set temporary locale.

Arguments:

  • $locale_id - type: string, values: from config (key "locales")

Return value: $tmp_locale - object QBit::Application::_Utils::TmpLocale

Example:

  my $tmp_locale = $app->set_tmp_app_locale('ru');
  
  #restore locale
  undef($tmp_locale);

add_tmp_rights

Add temporary rights.

Arguments:

  • @rights - Rights (type: array of a string)

Return value: $tmp_rights - object QBit::Application::_Utils::TmpRights

Example:

  my $tmp_rights = $app->add_tmp_rights('view_all', 'edit_all');
  
  #restore rights
  undef($tmp_rights);

pre_run

Called before the request is processed.

It is done:

  • Resets current user

  • Refresh options

  • Resets timelog

  • Call "pre_run" for models

No arguments.

Example:

  $app->pre_run();

post_run

Called after the request is processed.

It is done:

  • Call "post_run" for models

  • Finish timelog

  • Call "process_timelog"

  • Find memory cycles and call "process_mem_cycles" if needed

No arguments.

Example:

  $app->post_run();

process_mem_cycles

Process memory cycles

Arguments:

  • $cycles - Cycles. (result: Devel::Cycle::find_cycle)

Return value: $text - info (type: string)

process_timelog

Process time log. Empty method.

No arguments.