` with at least two classes first is `layout`, second is `my_awesome_layout`. --- Each feature is an item and needs some directives: |Element|Required ?|Description| |-------|---------------|-----------| |tabbar-items|yes|This directive binds the on-click of your element| |option="feature"|yes|Sets the option to the current feature| |go-to-url="goTo(feature);"|no|**Deprecated**, the `tabbar-items` directive opens the feature itself on click (`HomepageLayout.openFeature`), the attribute is still present in the core layouts| |ng-show="tabbar_is_visible"|yes|Condition used when the layout is always displayed| |ng-class="[...]"|yes|Used by the option in Editor > Colors > Homepage > Transparent to remove border & background| Elements also use CSS classes to bind their colors upon the application defined color set |Class|Required ?| |-----|---------------| |item|yes| |homepage-custom|yes| |Classic| |----------------| |![opaque](img/layout/opaque-1.png)![translucent-1](img/layout/translucent-1.png) ![translucent-2](img/layout/translucent-2.png)| ### style.css This CSS is the example given in the layout skeleton but with `my_awesome_layout` as namespace ```css .layout.my_awesome_layout { position: absolute; bottom: 5vh; width: 100%; } .layout.my_awesome_layout li.item { height: 28px; width: 150px; border-radius: 0 14px 14px 0; padding: 0; -o-transform: rotate(-7deg); -ms-transform: rotate(-7deg); -webkit-transform: rotate(-7deg); transform: rotate(-7deg); margin-left: -4vw; margin-top: 1px; border-width: 0px; } .layout.my_awesome_layout li.item img { float: left; height: 80%; margin: 2% 0 0 10%; } .layout.my_awesome_layout li.item h2 { float: left; } ``` ### hooks.js The hooks.js file is an Angular service, lazy loaded when using a custom Layout, allowing to manipulate features. ```js /** * * MyAwesomeLayout example * * All the following functions are required in order for the Layout to work */ angular.module("starter").service('my_awesome_layout', function ($rootScope, $timeout, HomepageLayout) { var service = {}; var _features; /** * Must return a valid template * * @returns {string} */ service.getTemplate = function() { return "modules/layout/home/my_awesome_layout/view.html"; }; /** * Must return a valid template * * @returns {string} */ service.getModalTemplate = function() { return "templates/home/l10/modal.html"; }; /** * onResize is used for css/js callbacks when orientation change */ service.onResize = function() { /** Do nothing for this particular one */ }; /** * Manipulate the features objects * * Examples: * - you can re-order features * - you can push/place the "more_button" * * @param features * @param more_button * @returns {*} */ service.features = function(features, more_button) { /** Keep a copy of the features in your hook */ _features = features; /** Place more button at the end */ features.overview.options.push(more_button); return features; }; return service; }); ``` |Function|Description| |--------|-----------| |service.getTemplate|Must return the path to the layout file| |service.getModalTemplate|Must return the path to a valid modal file| |service.onResize|Called when device orientation is changed or resized and everytime the homepage is shown| |service.features|Called to manipulate features| * Default modal templates are `templates/home/l10/modal.html` & `templates/home/modal/view.html` #### Available objects in hook service `features` ```json "features": { "layoutCode": "my_awesome_layout", /** an array of every features in your application see [Option](#option) */ "options": [...] } ``` #### Chunk of features defined by the `limit` `features.overview` ```json "features.overview": { "layoutCode": "my_awesome_layout", /** an array of every features in your application see [Option](#option) */ "options": [...] } ``` #### Option Example of an option/feature for information ```json { "value_id": "6", "id": 6, "layout_id": "1", "code": "calendar", "name": "Calendar", "is_active": "1", "url": "http://www.yourdomain.com/57c7f8764a65a/event/mobile_list/index/value_id/6", "path": "/57c7f8764a65a/event/mobile_list/index/value_id/6", "icon_url": "http://www.yourdomain.com/var/cache/images/e9dcc367471a70a23261056b1129a198.png", "icon_is_colorable": "1", "is_locked": null, "is_link": false, "use_my_account": "0", "use_nickname": "0", "use_ranking": "0", "custom_fields": [], "position": "5", "is_visible": true } ``` #### Other `service.features = function(features, more_button)` examples In the example below, we are placing the `more_button` at the third place in the `features.overview.options` array. ```js [...] /** * Example with a layout containing 5 features (more_button include) & a modal */ service.features = function(features, more_button) { if(features.overview.options.length >= 4) { var third_option = features.overview.options[2]; var fourth_option = features.overview.options[3]; /** Placing more button at the third place (middle in layout) */ features.overview.options[2] = more_button; features.overview.options[3] = third_option; features.overview.options[4] = fourth_option; /** Removing 4 first option for the modal */ features.options = features.options.slice(4, features.options.length); } else { features.overview.options.push(more_button); } return features; }; [...] ``` The second example is used by the `Apartments` layout to create chunks of features. ```js [...] service.features = function(features, more_button) { _features = features; var more_options = features.options.slice(12); var chunks = new Array(); var i, j, temparray, chunk = 2; for (i = 0, j = more_options.length; i < j; i += chunk) { temparray = more_options.slice(i, i + chunk); chunks.push(temparray); } features.chunks = chunks; return features; }; [...] ``` ## Layout Options Layout options let you offer easy customization of your layouts to the final user with a simple form. If you want to add custom options to your layout you must create a Form and register it in your init. ```raw MyAwesomeLayout.zip └─ Form └─ MyAwesomeLayout.php ``` ### Init hook ```php # Register a custom form for the Layout Options Siberian_Feature::registerLayoutOptionsCallbacks("my_awesome_layout", "MyAwesomeLayout_Form_MyAwesomeLayout", function($datas) { $options = array(); return $options; }); ``` ### Form options Here is a simple example of what the form could look (from Layout 18). ![layout-18](img/layout/layout-18-form.png) And the example code ```php addSimpleSelect("label", __("Title position"), array( "label-left" => __("Left"), "label-right" => __("Right"), )); $textTransform = $this->addSimpleSelect("textTransform", __("Title case"), array( "title-lowcase" => __("Lower case"), "title-uppercase" => __("Upper case"), )); $borders = $this->addSimpleMultiCheckbox("borders", __("Display Borders"), array( "border-left" => __("Left"), "border-right" => __("Right"), "border-top" => __("Top"), "border-bottom" => __("Bottom"), )); $this->addNav("submit", __("Save"), false, false); self::addClass("btn-sm", $this->getDisplayGroup("submit")->getElement(__("Save"))); } } ``` Your form `MUST` extend `Siberian_Form_Options_Abstract` class. Then you can add your options. ### style.css And the view.html & style.css examples Here in the style.css we are using classes with the same names as the form values below, this is one way of doing it. ```css [...] .layout.layout_siberian_18 .label-right { text-align: right; } .layout.layout_siberian_18 .label-left { text-align: left; } .layout.layout_siberian_18 .title-lowcase { text-transform: inherit; } .layout.layout_siberian_18 .title-uppercase { text-transform: uppercase; } [...] ``` ### view.html And then in the view.html ```html

``` Here we are using a simple javascript "join" to concatenate all the selected options which have the same classes names. For the multi-select `{{ features.layoutOptions.borders.join(' ') }}` And for the simple selects we only echo the class, or classes `{{ features.layoutOptions.label+' '+features.layoutOptions.textTransform }}` ### Advanced usage of the options In the layout swiper, we are using the options to configure the Slider javascript object Here is an example of how we do it. in our hooks.js file, within the onResize function ```js /** * onResize is used for css/js callbacks when orientation change */ service.onResize = function() { var options = _features.layoutOptions; /** Do nothing for this particular one */ var time_out = ($rootScope.isOverview) ? 1000 : 200; $timeout(function() { if(swipe_instance != null && typeof swipe_instance.destroy == "function") { swipe_instance.destroy(true, false); } swipe_instance = new Swiper('.layout.layout_siberian_swipe .swiper-container', { direction: 'vertical', loop: (options.loop == "1") ? true : false, effect: 'coverflow', centeredSlides: true, initialSlide: (options.backcurrent == "1") ? service.last_index : 0, slidesPerView: 'auto', loopedSlides: 6, coverflow: { rotate: options.angle, stretch: options.stretch, depth: options.depth, modifier: 1, slideShadows : false } }); }, time_out); }; ``` previously we saved the `_features` array in the features function, and thus can use it. However, you can also access the layout options here `HomepageLayout.layoutOptions` ## Package When you are done with your layout, it's time to pack ! zip everything at the root of your layout and you're done ! If you have created your own module from the [skeleton](https://github.com/Xtraball/siberian-layout-skeleton), you can run `./tools.pack.sh` and voila ! ```raw MyAwesomeLayout.zip ├─ resources ├─ init.php └─ package.json ``` ================================================================ FILE: docs/customization/template.md ================================================================ # Template ** *Note: Template packages require Siberian 5.1.0 and above, otherwise they will not work* ** Demo template can be found [here](../img/template/template-corporate.zip)! ### What you need * A nice template idea ! **And to define its name:** * Your template name, like `TemplateAwesome`. note: always prefix it with `Template` this will avoid collision with modules! ## Structure of a template package Templates are installed in the `app/local/modules` folder Below is the complete and minimal required structure for a template pack ```raw TemplateAwesome.zip ├─ resources │ ├─ db │ │ └─ data │ │ └─ template-awesome.php │ └─ images │ └─ templates │ └─ awesome │ └─ unified │ ├─ background.jpg // Must be square and 2732x2732px │ ├─ icon.jpg // Must be square and 512x512px │ └─ overview_new.jpg // Must be 640x568px └─ package.json ``` #### overview_new.jpg Example ![overview-image](../img/template/overview_new.jpg) ### package.json The `package.json` is used by the Installer to know the requirements, and routines to run during the installation/update process of your Template pack ```json { "name": "TemplateAwesome", "version": "2.0.0", "description": "Awesome template installer.", "dependencies": { "system": { "type": "SAE", "version": "5.1.0" /** 5.1.0 is required for the Template to work! */ } }, "type": "template" /** The type is important for Siberian to identify it as a template! */ } ``` |Field|Required ?|Description| |-----|---------------|-----------| |name|yes|Package name, avoid spaces and numbers| |description|yes|Package description| |type|yes|must be `template`| |version|yes|Your template pack version, for updates| |dependencies|yes|**version*:** 5.1.0 minimum, **type:** SAE/MAE/PE minimum installation type required| ** * version must be at least 5.1.0** ### Data `template-awesome.php` This file creates & updates the entry in database and copy assets at installation time If you need to change options in your module while providing an update you must change the values here ```php 'app/local/modules/TemplateAwesome/resources/media/library/awesome1.png', 'awesome2' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome2.png', 'awesome3' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome3.png', 'awesome4' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome4.png', 'awesome5' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome5.png', 'awesome6' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome6.png', 'awesome7' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome7.png', 'awesome8' => 'app/local/modules/TemplateAwesome/resources/media/library/awesome8.png', ]; // We insert icons one by one, so we can get the icon_id for each, and use it in our features! // We fill the array $libraryKeys with our "keys" so we can identify our icons later, to assign them to our features! $libraryKeys = []; foreach ($icons as $key => $icon) { $result = Feature::installIcons('TemplateAwesome', [$icon], false); $libraryKeys[$key] = $result; } // No changes here $ionicColors = [ 'header' => [ 'color' => '#ffffff', 'background_color' => '#5b5b5b' ], 'background' => [ 'background_color' => '#e2e2e2' ], 'homepage' => [ 'color' => '#5b5b5b', 'background_color' => '#ffffff', 'background_opacity' => '0', 'border_color' => '#ffffff', 'border_opacity' => '0', 'image_color' => '#5b5b5b' ], 'list_item_divider' => [ 'color' => '#ffffff', 'background_color' => '#5b5b5b' ], 'list_item' => [ 'color' => '#5b5b5b', 'background_color' => '#ffffff', 'border_color' => '#5b5b5b' ], 'card_item_divider' => [ 'color' => '#ffffff', 'background_color' => '#5b5b5b' ], 'card_item' => [ 'color' => '#5b5b5b', 'background_color' => '#ffffff' ], 'buttons' => [ 'color' => '#ffffff', 'background_color' => '#5b5b5b', 'border_color' => '#ffffff' ], 'checkbox_on' => [ 'color' => '#5b5b5b', 'background_color' => '#c1c1c1' ], 'checkbox_off' => [ 'background_color' => '#c1c1c1' ], 'checkbox_general' => [ 'color' => '#5b5b5b', 'background_color' => '#c1c1c1' ], 'radio' => [ 'color' => '#5b5b5b', 'background_color' => '#c1c1c1' ], 'toggle_on' => [ 'background_color' => '#c1c1c1' ], 'toggle_general' => [ 'color' => '#5b5b5b', 'background_color' => '#c1c1c1' ], 'toggle_off' => [ 'background_color' => '#c1c1c1', 'border_color' => '#808080' ], 'toggle_handle_on' => [ 'background_color' => '#c1c1c1' ], 'toggle_handle_off' => [ 'background_color' => '#5b5b5b' ], 'tooltip' => [ 'color' => '#ffffff', 'background_color' => '#5b5b5b' ], 'spinner_ios_text' => [ 'background_color' => '#5b5b5b' ], 'spinner_android_text' => [ 'background_color' => '#5b5b5b' ] ]; // No more keys, we will use "code" so we can have the same feature, many times $features = [ [ 'code' => 'custom_page', 'name' => 'About Us', 'icon_id' => $libraryKeys['awesome1']['icon_id'] ], [ 'code' => 'catalog', 'name' => 'Menu', 'icon_id' => $libraryKeys['awesome2']['icon_id'] ], [ 'code' => 'commerce', 'name' => 'Shop', 'icon_id' => $libraryKeys['awesome3']['icon_id'] ], [ 'code' => 'fanwall2', 'name' => 'Social wall', 'icon_id' => $libraryKeys['awesome4']['icon_id'] ], [ 'code' => 'form_v2', 'name' => 'Form', 'icon_id' => $libraryKeys['awesome5']['icon_id'] ], [ 'code' => 'folder_v2', 'name' => 'Folder #1', 'icon_id' => $libraryKeys['awesome6']['icon_id'] ], [ 'code' => 'folder_v2', 'name' => 'Folder #2', 'icon_id' => $libraryKeys['awesome7']['icon_id'] ], [ 'code' => 'tabbar_account', 'name' => 'My account', 'icon_id' => $libraryKeys['awesome8']['icon_id'] ] ]; Template::installOrUpdate( 'TemplateAwesome', 'awesome', 'awesome', 'layout_3', ['Design'], $ionicColors, $features ); ``` |Argument|Description| |--------|-----------| |1|Module (package) name, here `TemplateAwesome`| |2|Template name| |3|Template `code`, unique, also used in the image path `resources/images/templates/

/unified/`, **never change it** as it is the key used to update the template|
|4|Layout code the template uses, if missing it falls back on `layout_6`|
|5|Categories, an array of names, e.g. `['Design']`|
|6|Ionic colors, see above|
|7|Features, see above|
|8|Position in the template list (optional, default `1000`)|

Each feature accepts `code` (required, the feature must exist, otherwise it is skipped), `name`, `icon_id`, or `icon` (a path, when there is no `icon_id`), `background_image` and `colorized` (default `true`).


================================================================
FILE: docs/customization/icon.md
================================================================

# Icon

** *Note: icon packages require Siberian 5.1.0 and above, otherwise they will not work* **

### What you need

* Cool icons to share an awesome pack !

**And to define two names:**

* Your icons pack name, like `MyIconPack`.

### Requirements

* Icons must be 512x512, border to border, can be full white if you want them to be colorized, or colorfull !

## Structure of an icon pack

Icons are installed in the `app/local/modules` folder

 

Below is the complete and minimal required structure for an icon pack

```raw
MyIconPack.zip
├─ resources
│  ├─ db
│  │  └─ data
│  │     └─ my_icon_pack.php
│  └─ media
│     └─ library
│        ├─ icon1.png
│        ├─ icon2.png
│        ├─ icon3.png
│        ├─ icon4.png
│        └─ [...]
├─ package.json
└─ [...]
```

### package.json

The `package.json` is used by the Installer to know the requirements, and routines to run during the installation/update process of your icon pack

```json
{
  "name": "MyIconPack",
  "description": "MyIconPack description",
  "type": "icons",
  "version": "1.0",
  "dependencies": {
    "system": {
      "type": "SAE",
      "version": "5.1.0"
    }
  }
}
```

|Field|Required ?|Description|
|-----|---------------|-----------|
|name|yes|Package name, avoid spaces and numbers|
|description|yes|Package description|
|type|yes|must be `icons`|
|version|yes|Your icon pack version, for updates|
|dependencies|yes|**version*:** 5.1.0 minimum, **type:** SAE/MAE/PE minimum installation type required|

** * version must be at least 5.1.0**

### Data

This file creates & updates the entry in database and copy assets at installation time

If you need to change options in your module while providing an update you must change the values here

**Note:** the icon pack is identified by its name (1st parameter of `installIcons`), and an icon by its path, installing again the same name and path updates instead of duplicating.

```php
 "...", "colorize" => true/false]` to override the 3rd parameter for one icon.

    It returns an array with `icon_id` (the first icon of the pack) and `library_id`, `icon_id` is used in the [Template](template) features.


## Package

When you are done with your icon pack, it's time to zip !

zip `resources` and `package.json` and you're done !

You can also give a look at this icon pack [icon-pack-yappix](https://github.com/Xtraball/icon-pack-yappix).

```raw
MyIconPack.zip
├─ resources
└─ package.json
```

================================================================
FILE: docs/stack/ionic-tools.md
================================================================

# Ionic Tools

We've build our own services on top of Ionic to be more resilient when updating frameworks.

# Dialog

The `Dialog` service is used to handle `Alert`, `Prompt` & `Confirm` popups taking care of the stack, and extended with nice features.
This service also takes care of the translations, every `String` goes into `$translate.instant(text)`

And if `context` is defined, strings goes into `$translate.instant(text, context)`.

Dialog methods always return a promise

## Alert

```js
Dialog.alert(title, message, button, dismiss, context);
```

![dialog-alert](../img/stack/dialogalert.png)

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|title|String|---|Dialog title|
|message|String|---|Dialog message `text`|
|button|String|---|Dialog button text, dismiss or ok|
|dismiss|Integer|undefined|When defined, the Dialog will automatically dismiss after the given time in ms, if set to `-1` the dismiss time will be calculated automatically|
|context|String|undefined|When defined, the context will be used to translate strings|

## Prompt

```js
Dialog.prompt(title, message, type, value, buttons_array, css_class, context);

Dialog.prompt(title, message, type, value, buttons_array, css_class, context)
    .then(function (result) {
        // the text typed by the user
    });
```

![dialog-prompt](../img/stack/dialogprompt.png)

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|title|String|---|Prompt title|
|message|String|---|Prompt message `text`|
|type|String|text|`text` or `password`, defaults to `text` if undefined|
|value|String|undefined|Placeholder if type is set to `text`|
|buttons_array|Array|`["OK", "CANCEL"]`|The two buttons: validate, then cancel|
|css_class|String|undefined|CSS class used to customize render|
|context|String|undefined|When defined, the context will be used to translate strings. It is the seventh argument: pass `undefined` for the ones you skip|


## Confirm

```js
Dialog.confirm(title, message, buttons_array, css_class, context);

Dialog.confirm(title, message, buttons_array, css_class, context)
    .then(function (result) {
        if (result) {
            // Confirmed
        } else {
            // Cancelled
        }
    });
```

![dialog-confirm](../img/stack/dialogconfirm.png)

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|title|String|---|Confirm title|
|message|String|---|Confirm message `text`|
|buttons_array|Array|---|`["YES","NO"]`|
|css_class|String|undefined|CSS class used to customize render|
|context|String|undefined|When defined, the context will be used to translate strings|

 

 

----

# Modal

This Modal service is using $ionicModal but will take cares of the stacking, the parameters & config are the same as the $ionicModal ones.

The service also takes care of removing the Modal when closing via `modal.hidden` subscribers.

The Modal service returns a promise with the modal object

## fromTemplateUrl

```js
Modal.fromTemplateUrl(templateUrl, config);

Modal.fromTemplateUrl(templateUrl, config)
    .then(function (modal) {
        // Do Whatever you want with your modal!
    });
```

## fromTemplate

```js
Modal.fromTemplate(template, config);
```

 

 

----

# Loader

With this loader wrapper, you can only open the Loader once.
Also the loader comes with a backdrop modal preventing any action!

## Show

```js
Loader.show(text, config);
```

#### default

```js
Loader.show()
```

![loader-simple](../img/stack/loader-simple.png)

#### example with text

```js
Loader.show("Custom text...")
```

![loader-custom](../img/stack/loader-custom.png)

#### example with image

```js
Loader.show("
")
```

![loader-image](../img/stack/loader-image.png)

## Hide

```js
Loader.hide();
```


 

 

----

# Location

The location services is used to get the current position, with refresh rules to avoid GPS spam & abuse.

## getLocation

#### usage 

```js
Location.getLocation(config, force)
    .then(function(position) {
        /** position: {
                coords: {
                    latitude  
                    longitude 
                    altitude
                    accuracy
                    altitudeAccuracy
                    heading
                    speed
                }
                timestamp                
            }
        */
    }, function(error) {
        // action on error
    })
```

Returns a promise

If `force` is defined, whatever its value (`true` as well as `false`), the GPS request will be immediate. Leave it
`undefined` to let the service decide: if the latest fetch is less than 42 seconds old, it returns the latest saved
position within the promise then refreshes it in background.

If the position cannot be found (permission denied, timeout, position unavailable), the promise is rejected and the
service stops asking for the next calls, to avoid asking again and again.

 

#### default config

```js
{
    enableHighAccuracy: true,
    timeout: 10000,
    maximumAge: 0
}
```

## getLatest

```js
Location.getLatest()
    .then(function(position) {
        /** position: {
                coords: {
                    latitude  
                    longitude 
                    altitude
                    accuracy
                    altitudeAccuracy
                    heading
                    speed
                }
                timestamp                
            }
        */
    }, function(error) {
        // action on error
    })
```

Returns a promise

Get latest will return the latest position, without taking care of the freshness, 
if the position was never fetched, it will try to fetch it however.


 

 

----

# Picture

The picture service asks the user whether to take a new picture with the camera or to import one from the library
(in the browser preview, it opens a file picker instead). It needs no permission from your module: the system picker
is used to import a picture, and the camera permission is asked by the camera plugin when it is needed.

## takePicture

```js
Picture.takePicture(width, height, quality)
    .then(function (response) {
        /**
            The image is returned as a data URI.
            response: {
                image: "data:image/jpeg;base64,/9j/4AAQ..."
            }
        */
    }, function (error) {
        if (error && error.cancelled) {
            // The user backed out of the menu, of the camera or of the library.
            // Nothing went wrong and nothing was shown: do nothing.
            return;
        }

        // Any other error was already reported to the user with a dialog,
        // you only need to reset your own state here.
    });
```

All three arguments are optional.

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|width|Integer|1200|Max width in pixels, from 1 to 10000. The picture keeps its proportions.|
|height|Integer|1200|Max height in pixels, from 1 to 10000.|
|quality|Integer|90|JPEG quality, from 0 to 100.|

A value that is missing, or not a number, falls back to its default. A value out of range is brought back to the
nearest limit.

#### Good to know

- `response.image` is always a complete data URI, whatever the version of the camera plugin in the app: the plugin
  returned the bare base64 up to version 7 and a data URI from version 8, and `Picture` accepts both. Use it as is,
  for example ``, and do not add `data:image/jpeg;base64,` yourself.
- Handle the rejection even if you do nothing with it: a promise rejected by the user backing out is otherwise
  logged as "Possibly unhandled rejection".
- Calling `takePicture` while the menu is already open rejects at once, without an error object.
- The whole picture is kept in memory as text, so ask for a size that matches what you really need (the default
  1200 px is enough for an avatar or a post), and send it to the server in one request.


 

 

----

# SocialSharing

## share

```js
SocialSharing.share(content, message, subject, link, file)
```

When using `SocialSharing.share()` with no parameters, the default message will be `Hi. I just found this in the MyAwesomeApp app.`

 

If only `content` is defined, `this` will be replace by `content`, like `Hi. I just found a new awesome music in the MyAwesomeApp app.`

 

When defining `message` it will completely override the default message including `content`, like `Just wanted to share this song with you guy's`
but you can use `$1` as a placeholder for `content`, and `$2` as a placeholder for the Application name, like `Just wanted to share $1 with you guy's, in the App $2`

 

`link` will default to the Application download link

 

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|content|String|undefined|Default placeholder text|
|message|String|undefined|Message replacing the default one|
|subject|String|undefined|Subject or your shared message|
|link|String|undefined|Default to the Application download link|
|file|String|undefined|A file url, an album cover or pdf for example|

 

 

----

# Customer

The customer service, is the only entry point you should use when dealing with user accounts, this in order to avoid any unwanted and/or duplicated behaviors.


## loginModal


```js
Customer.loginModal(scope, login_callback, logout_callback, register_callback)
```

 

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|scope|Object|undefined|If undefined, the scope will be $rootScope|
|login_callback|Function|undefined|A function to be called on a sucessfull login|
|logout_callback|Function|undefined|A function to be called on a sucessfull logout|
|register_callback|Function|undefined|A function to be called on a sucessful registration|

 

 

----

# $session

The session provider contains the session id, the uid, and the screen resolution.

This service is also used to store session data in localStorage.

## getId

```js
$session.getId()
```

## getDeviceUid

```js
$session.getDeviceUid()
```

## getDeviceScreen

```js
$session.getDeviceScreen()

/**
{
    width,
    height,
    orientation
}
*/
```

## setItem

```js
$session.setItem(key, value)
```

## getItem

```js
$session.getItem(key)
    .then(function(value) {
        // the retrieved value, or null if it doesn't exists
    });
```

## removeItem

```js
$session.removeItem(key)
```

================================================================
FILE: docs/stack/utilities.md
================================================================

# Utilities

### isNotAvailableOffline

The function below is used to prevent functions or features to work when Application is offline.

This will return `true` or `false`, and when returning true, it also opens an alert.

```js
$rootScope.isNotAvailableOffline(with_alert)
```

 

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|with_alert|Boolean|true|Opens an alert by default|

 

### isNotAvailableInOverview

The function below is used to prevent some functions to work inside the Application overview, when editing.

This will return `true` or `false`, and when returning true, it also opens an alert.

```js
$rootScope.isNotAvailableInOverview(with_alert)
```

 

#### options

|Key|Type|Default|Usage|
|---|---|---|---|
|with_alert|Boolean|true|Opens an alert by default|

 

### isNativeApp

This variable is used to differentiate native Apps Android & iOS from Browser App or Progressive Web App.

```js
$rootScope.isNativeApp
```
================================================================
FILE: docs/stack/frameworks.md
================================================================

# Frameworks

Below you'll find a complete list of the various frameworks we use both in Editor, Backoffice & Applications.

Most of our Cordova & Ionic libraries are customized for Siberian.

## Editor

The main codebase inside the editor is powered with `jQuery` and `bootstrap`.

### FontAwesome 

- Version: `4.7.0`

- [See on Github](https://github.com/FortAwesome/Font-Awesome)

### Bootstrap 

- Version: `3.2.0`

- [See on Github](https://github.com/twbs/bootstrap)

### CKEditor

- Version: `4.13.1`

- CKEditor our richtext editor, used all across the Editor for every feature.

- [See on Github](https://github.com/ckeditor)

### CodeMirror

- Version: `latest`

- CodeMirror is used to highlight Code, Scripts & more, we use it for our inline `SCSS` editor & also as a plugin for our CKEditor source feature. 

- [See on Github](https://github.com/codemirror/CodeMirror)

### Chart.js

- Chart.js is powering our App analytics like below.

- [See on Github](https://github.com/chartjs/Chart.js) 

![chart-js](../img/stack/chartjs.png)

### DataTables

- [See on Github](https://github.com/DataTables/DataTables)

### nestedSortable

- [See on Github](https://github.com/ilikenwf/nestedSortable)

### prettyPhoto

- [See on Github](https://github.com/scaron/prettyphoto)

### jQuery UI

- [See on Github](https://github.com/jquery/jquery-ui)

### SweetAlert

- Version: `latest`

- [See on Github](https://github.com/t4t5/sweetalert)

![sweet-alert](../img/stack/sweetalert.png)

*Basic example*

```js
swal("Here's a message!");
```

You can see [this page](http://t4t5.github.io/sweetalert/) for more advanced usage.


## Backoffice

In the backoffice we are mainly using AngularJS along with some plugins for UI, CKEditor, Graphs.

### FontAwesome 

- Version: `4.2.0`

- [See on Github](https://github.com/FortAwesome/Font-Awesome)


### Bootstrap 

- Version: `3.2.0`

- [See on Github](https://github.com/twbs/bootstrap)


### AngularJS

- Version: `1.3.0`

- [See on Github](https://github.com/angular/angular)


### CKEditor

- Version: `4.4.6`

- [See on Github](https://github.com/ckeditor)


## Backend

All our backend is running under Zend Framework with a complete custom stack on top of it, we also use libraries for Push & SCSS.

### PHP

- Version: from `8.2` up to `8.5` (`>=8.2 <8.6`), `8.5` recommended

- [See on Github](https://github.com/php)

### Zend Framework

- Based on ZF1, customized for Siberian (Zend Framework `1.12.3`) & topped with Siberian library

- [See on Github](https://github.com/zendframework/zf1)


## Applications

### Based on Ionic / AngularJS

- Ionic `1.3.5` (Ionic 1, not Ionic 2+), AngularJS `1.5.3`

#### Highly customized with

- Lazy & Modular loading
- Dynamic caching
- Extended SCSS

 

### Cordova

#### All our cordova platforms are forked and customized.

#### Android

- Minimum Android 8.0 (API 26), `cordova-android` 15.1.0

- [See on Github](https://github.com/Xtraball/cordova-android)

#### iOS

- Minimum iOS 15, `cordova-ios` 6.1.1 (CordovaLib), the iOS shells are built with Xcode 26 in CI

- [See on Github](https://github.com/Xtraball/cordova-ios)

#### Browser

- [See on Github](https://github.com/Xtraball/cordova-browser)

 

### Cordova Plugins

#### All our cordova plugins are forked and customized.

The list below follows `submodules.json`, each plugin lives in its own repository under `https://github.com/Xtraball/`, on the `siberian` branch.

|Plugin|Usage|
|------|-----|
|[AdmobPro](https://github.com/Xtraball/AdmobPro)|Google AdMob ads Banner & Interstitial|
|[AppVersion](https://github.com/Xtraball/AppVersion)||
|[Badge](https://github.com/Xtraball/Badge)||
|[BarcodeScanner](https://github.com/Xtraball/BarcodeScanner)|QRCode scanner|
|[BrowserTab](https://github.com/Xtraball/BrowserTab)||
|[Camera](https://github.com/Xtraball/Camera)|Camera & Library manager|
|[Clipboard](https://github.com/Xtraball/Clipboard)||
|[Device](https://github.com/Xtraball/Device)||
|[File](https://github.com/Xtraball/File)||
|[Geofence](https://github.com/Xtraball/Geofence)||
|[Geolocation](https://github.com/Xtraball/Geolocation)||
|[InAppBrowser](https://github.com/Xtraball/InAppBrowser)||
|[Insomnia](https://github.com/Xtraball/Insomnia)|Prevents sleep for continuous app usage like GPS navigation|
|[IonicWebview](https://github.com/Xtraball/IonicWebview)|Web view of the Android shell|
|[Keyboard](https://github.com/Xtraball/Keyboard)||
|[LocalNotifications](https://github.com/Xtraball/LocalNotifications)||
|[MediaNative](https://github.com/Xtraball/MediaNative)||
|[MusicControls](https://github.com/Xtraball/MusicControls)|Display music controls in Notification center|
|[Navigator](https://github.com/Xtraball/Navigator)||
|[Onesignal](https://github.com/Xtraball/Onesignal)|Push notifications|
|[Permissions](https://github.com/Xtraball/Permissions)|Android runtime permissions (a dummy JavaScript file on iOS)|
|[Promises](https://github.com/Xtraball/Promises)||
|[PluginSiberian](https://github.com/Xtraball/PluginSiberian)||
|[SocialSharing](https://github.com/Xtraball/SocialSharing)||
|[SplashScreen](https://github.com/Xtraball/SplashScreen)||
|[StatusBar](https://github.com/Xtraball/StatusBar)||
|[WebView](https://github.com/Xtraball/WebView)||
|[Whitelist](https://github.com/Xtraball/Whitelist)||

The iOS shell uses `IosXhr` instead of `IonicWebview`, see [docs/mobile-parity.md](https://github.com/Xtraball/Siberian/blob/trunk/docs/mobile-parity.md) in the Siberian repository for the differences between the Android and iOS plugin versions.

 

### Javascript

#### Swiper

- Version: `3.4.2`

- [See on Github](https://github.com/nolimits4web/Swiper)

 

#### Lodash

- Version: `4.13.1`

- [See on Github](https://github.com/lodash/lodash)

 

#### LocalForage

- Version: `1.4.3`

- [See on Github](https://github.com/localForage/localForage)

 

#### Siberian NqQueue

- [See on Github](https://github.com/Xtraball/angular-queue)

 

#### Moment.js

- Version: `2.18.1`

- [See on Github](https://github.com/moment/moment)

 

#### ProgressBar

- Version: `1.0.1`

- [See on Github](https://github.com/kimmobrunfeldt/progressbar.js)

 


================================================================
FILE: docs/cli/siberian.md
================================================================

# Siberian CLI Documentation

## Introduction

Siberian ships with a CLI to help debugging & troubleshooting. Run it from the `siberian` folder with `./cli` (or `php cli`).

## CLI available methods

|Method|Min. version|Params|Description|
|------|------------|------|-----------|
|export:schemas|5.1.0|-|Exports the current schema tables (only schemas) to `var/schema/CURRENT_VERSION/TABLE.php` this is useful to prepare db files for your custom modules|
|export:database|5.1.0|-|Exports the current mysql database|
|version|5.1.0|`version`|Updates `lib/Siberian/Version.php` with the given version|
|user:create|5.1.0|-|This action will ask for an e-mail and a password to create a new backoffice user|
|user:update-password|5.1.0|-|This action will ask for an e-mail and a password, usefull to change a lost backoffice password|
|dev / development|5.1.0|-|Fast switch in development mode|
|prod / production|5.1.0|-|Fast switch in production mode|
|cache:design|5.1.0|`sae`, `mae`, `pe`|Rebuilds SAE/MAE/PE cache for design files|
|cache:clear|5.1.0|-|Clear `var/cache`, `var/log` & `var/tmp`|
|license:set|5.1.0|`license`|Set the product license from cli|
|i18n:extract|5.1.0|`[module] [context]`|Extracts all missing translations|
|app:manifest|5.1.0|`--skip-cache`|Rebuilds the app manifest|
|app:keystore:restore|5.1.0|`appId`|Extracts a keystore from the database|
|info / infos|-|-|Prints generic information about the current installation|
|password|-|`[length]`, `--no-uppercase`, `--no-numeric`, `--no-special`|Generates a strong password (24 characters by default)|
|https|-|`on`, `off`|Switch the soft HTTP to HTTPS redirection on or off|
|test:http2|-|-|Tests whether HTTP/2 is available in php-curl for the cli and cron|
|module:version:get|-|-|Lists the installed modules and their versions|
|module:version:set|-|`module`, `version`|Sets the version of an installed module|
|module:quarantine|-|`list`, `recheck [Module]`, `release Module`, `scan`|Lists, rechecks, releases or scans the modules of `app/local/modules` put in quarantine|
|build:queue:flush|-|-|Flushes the source and APK build queues and removes the locks|
|security:scan|-|`filePath`|Scans the given file with ClamAV (if configured in the Backoffice)|
|subscription:check-payments|-|-|Manually runs the payment verification for expired subscriptions (PE, normally run by the cron)|
|subscription:sync|-|-|Manually caches the payment statuses|
|google:test-api-key|-|`apiKey`|Tests a Google Maps API key|
|waf:status / waf:enable / waf:disable|-|-|Gets, enables or disables the Web Application Firewall|
|waf:extension:list|-|-|Lists the extensions allowed by the Web Application Firewall|
|waf:extension:allow / waf:extension:disallow|-|`extension`|Allows or disallows an extension in the Web Application Firewall|
|help|5.1.0|-|Display the command help manual|

### Examples

```bash
prompt $ ./cli export-schemas

prompt $ ./cli export-database
Filename for the export: dump.sql
Export done.

prompt $ ./cli version 5.1.13

prompt $ ./cli user:create
Input new backoffice user e-mail: demo@demo.com
Input new backoffice user password: ********
Your new user is now created.

prompt $ ./cli user:update-password
Input backoffice user e-mail to change: demo@demo.com
Your new password (min 9 characters, 1 uppercase letter, 1 lowercase, 1 number & 1 special character): ********
Password successfully changed.

prompt $ ./cli dev


prompt $ ./cli prod

prompt $ ./cli cache:design 

prompt $ ./cli cache:clear

prompt $ ./cli app:manifest

prompt $ ./cli help
```
================================================================
FILE: docs/api.md
================================================================

# SiberianCMS API Documentation

## Introduction

Welcome to the SiberianCMS REST API documentation.

This doc contains reference materials to help you implementing the API into your system.

SiberianCMS API provides you with the ability to manage your users, as well as your applications.

You can find our PHP Library:
    
* [Siberian API php](https://github.com/Xtraball/siberiancms-api-php).

## At a glance

* The API is implemented with REST and is secured by an HTTP Basic Authentication or a Bearer Token.

* The requests are made over HTTP POST and the responses are delivered in JSON.

* For each request, you need to post all of your data together with your credentials previously created from your SiberianCMS's back-office.

## Create your API User

* Open your Siberian Backoffice, then go in *Manage > Users > API* 

* Create your user & select the API Accesses to grant him.

* For the HTTP Basic Auth, simply uses your username & password.

* For the Bearer Token, get the generated Token and send it to the API with the header below

```raw
// use this custom header, we do not use the regular Authorization HTTP header due to some restrictions.

Api-Auth-Bearer: Bearer YOURTOKEN

If your token is: 965327d7caa3d748bb70630b8f1ec64b7f0882ec
so your header will be

Api-Auth-Bearer: Bearer 965327d7caa3d748bb70630b8f1ec64b7f0882ec

```


## Basic usage for the PHP library

#### Init the API with Basic Auth or Bearer token


```php
isSuccess()) {
    $user_id = $response->getResponse("user_id");
    $token  = $response->getResponse("token");
} else {
    echo $response->getErrorMessage();
}
```

#### Create an application

```php
   isSuccess()) {
    $app_id = $response->getResponse("app_id");
    $app_url  = $response->getResponse("app_url");
} else {
    echo $response->getErrorMessage();
}
```

Other actions are documented here [API Documentation](http://developer.siberiancms.com/api/)


#### Run test (on you development instance)

Basic Auth

```bash
./run-test.sh siberianurl basic username password
```

Bearer token

```bash
./run-test.sh siberianurl bearer token
```

## APIs

Here is the list of the available APIs:

### Application

* [Create an application](./application#create)

* [Update an existing application](./application#update)

* [Grant access to an application](./application#grant-user)

* [Revoke access to an application](./application#revoke-user)

### User

* [Create a user](./user#create)

* [Update an existing user](./user#update)

* [Check whether a user exists](./user#exists)

* [Authenticate a user](./user#authentication)

* [Send a new password to a user](./user#forgot-password)

### Backoffice

* [Rebuild manifest](./backoffice#manifest)

* [Clear tmp](./backoffice#clear-tmp)

* [Clear cache](./backoffice#clear-cache)

* [Clear logs](./backoffice#clear-logs)

### Push notifications

The global push API was removed in 5.0.0, see [Push](./push).

### Local API access

!!! warning
    When enabled, **every request made from the server itself skips the API authentication**, no user, password or token is needed and all API privileges are granted. Leave it disabled unless you really need it.

The setting `allow_local_api` is read in the API base controller (`Api_Controller_Default::init()`). It is **off by default** (a missing setting counts as disabled), and only the exact value `true` enables it.

When it is enabled, a request skips the Basic and Bearer authentication and the ACL check if the client address equals the server address (`$_SERVER['REMOTE_ADDR'] === $_SERVER['SERVER_ADDR']`), that is a call made from the same machine, typically a script or cron job running `curl` against the instance's own address.

To enable it, add this line to `config.user.php` (next to `config.php`, in the `siberian` folder; `config.php` loads it):

```php

{{ feature.name }}

{{ feature.name }}