https://github.com/trychlos/pwix-app-pages
Meteor APP pages description
https://github.com/trychlos/pwix-app-pages
Last synced: about 1 month ago
JSON representation
Meteor APP pages description
- Host: GitHub
- URL: https://github.com/trychlos/pwix-app-pages
- Owner: trychlos
- Created: 2024-07-27T22:30:53.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2025-07-08T14:53:55.000Z (11 months ago)
- Last Synced: 2025-07-08T15:48:55.731Z (11 months ago)
- Language: JavaScript
- Size: 31.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
# pwix:app-pages
## What is it ?
A package which let an application describe its pages, modals and so on, said _display units_.
The packages provides three client classes:
- `AppPages.DisplayUnit` which manages each display unit,
- `AppPages.DisplaySet` which gathers all display units of the application
- `AppPages.RunContext` which provides and manages runtime live informations and permissions about the currently displayed unit.
These classes are defined, and can be used, in common code.
## Provides
### `AppPages`
The exported `AppPages` global object provides following items:
#### Classes
##### `AppPages.DisplaySet`
An ensemble of `AppPages.DisplayUnit` instances.
This class can be used as-is, or can be derived by the application. This is the reason for why this class is not automatically instanciated at initialization time. The application is expected to instanciate its `AppPages.DisplaySet` with the list of `AppPages.DisplayUnit`'s definition objects (not instances) to be managed.
Methods are:
- `new AppPages.DisplaySet( set, opts={} ): AppPages.DisplaySet`
The constructor.
it takes following arguments:
- `set`:, an object where the keys are the (unique) name of the display units, and the values an object which describes the properties of the display unit.
We have chosen to not force a singleton implementation. Nonetheless, the last instance is stored, in a ReactiveVar, as `AppPages.displaySet`.
- `byName( name ): AppPages.DisplayUnit|null`
This method returns the named `AppPages.DisplayUnit` if found, or null.
- `enumerate( cb, args )`
This method iterates through the `AppPages.DisplaySet` set, and calls the provided `cb` callback.
The enumeration is stopped when the callback returns `false`.
The callback has following prototype: `cb( name, unit, args ): Boolean`.
##### `AppPages.DisplayUnit`
A display unit, either a page or a modal or anything which can be addressable from a menu.
This class can be used as-is, or can be derived by the application.
Methods are:
- `new AppPages.DisplayUnit( name, properties ): AppPages.DisplayUnit`
The constructor.
it takes following arguments:
- `name`: the (unique) name of the display unit
- `properties`: the display unit properties:
- `classes`
Type: Array
The classes to be added.
Defaulting to the [configured](#configuration) value.
- `inMenus`
Definition type: String or Array of strings
Returned type: Array of strings
The menus names in which this page may appear as an item.
Defaulting to an empty array.
- `menuIcon`
Type: String
The name of the FontAwesome icon to be used in front of the menu label.
Defaulting to the [configured](#configuration) value.
- `menuLabel`
Type: String
The I18n translation key for the menu label.
Defaulting to the (untranslated) display unit name.
- `route`
the route to the page
Defaulting to null.
- `template`
Type: String
The template to be loaded
Defaulting to null.
Please note that this option must be set to get any rendering.
- `templateParms`
Type: Object|Function
Parameters to be passed to the template, defaulting to an empty object.
- `wantPermission`
Type: String
A permission string to be passed as the action to an `isAllowed()` function, defaulting to null (allowed)
This permission is expected to determine the display/availability/visibility of the display unit for the current user.
Do not set anything here for public pages.
Contrarily, having a `wantPermission` non-empty string means that the permissions of the current user must be validated by the application through the [configured](#configuration) `allowFn()` function.
- `async accessAllowed(): Boolean`
This method determines if the current user is allowed to access the display unit.
It calls the `allowFn()` [configured](#configuration) function with the `wantPermission` action string of the display unit.
- `get( key ): Any`
This method returns the parameter value for the specified key.
- `name(): String`
This method returns the unique name of this `AppPages.DisplayUnit`.
##### `AppPages.RunContext`
Let the application access or manages to live informations and permissions.
This class can be used as-is, or can be derived by the application.
Methods are:
- `new AppPages.RunContext(): AppPages.RunContext`
The constructor.
We have chosen to not force a singleton implementation. Nonetheless, the last instance is stored, in a ReactiveVar, as `AppPages.runContext`.
- `currentPage(): AppPages.DisplayUnit`
This method the current display unit computed from the current route.
A reactive data source.
- `dataContext( dc ): Any`
This method gets or sets the data context of the current display unit.
A reactive data source.
- `async getMenu( name ): Array`
Returns the list of the display units available in the specified menu and allowed to the current user.
- `async wantFooter(): Boolean`
Whether we want display a page footer.
This method should most probably be overriden by the application.
- `async wantHeader(): Boolean`
Whether we want display a page header.
This method should most probably be overriden by the application.
#### Functions
##### `AppPages.configure()`
See [below](#configuration).
A reactive data source.
### Objects
### `displayUnitDefs`
The `pwix:app-pages` package offers a `AppPages.displayUnitDefs` empty object as a placeholder where other packages are free to install the definitions of the display units they want exhibit.
Most often, the application may so:
- install its own display unit definitions
- instanciate its display set with:
```js
new AppPages.DisplaySet( AppPages.displayUnitDefs );
```
Remind that the resulting display set will be available as a `AppPages.displaySet` ReactiveVar.
## Permissions management
This package can take advantage of `pwix:permissions` package to manage the user permissions through the `wantPermission` `DisplayUnit` property. When present, the property is used as the action string identifier when calling the configured `allowFn()` function.
## Configuration
The package's behavior can be configured through a call to the `AppPages.configure()` method, with just a single javascript object argument, which itself should only contains the options you want override.
Known configuration options are:
- `allowFn`
An async function which will be called with an action string identifier, and must return whether the current user is allowed to do the specified action.
If the function is not provided, then the default is to deny all actions.
`allowFn` prototype is: `async allowFn( permission, user, page ): Boolean`
- `classes`
A list of classes to be added to display units.
Default to `[ 't-page' ]`.
- `menuIcon`
The menu icon, defaulting to `fa-chevron-right`.
- `verbosity`
Define the expected verbosity level.
The accepted value can be any or-ed combination of following:
- `AppPages.C.Verbose.NONE`
Do not display any trace log to the console
- `AppPages.C.Verbose.CONFIGURE`
Trace `AppPages.configure()` calls and their result
- `AppPages.C.Verbose.CUURENT_PAGE`
Trace the current page changes
- `AppPages.C.Verbose.DISPLAY_UNIT`
Trace DisplayUnit's instanciations
- `AppPages.C.Verbose.FUNCTIONS`
Trace all functions calls
Please note that `AppPages.configure()` method should be called in the same terms both in client and server sides.
Remind too that Meteor packages are instanciated at application level. They are so only configurable once, or, in other words, only one instance has to be or can be configured. Addtionnal calls to `AppPages.configure()` will just override the previous one. You have been warned: **only the application should configure a package**.
## NPM peer dependencies
Starting with v 0.1.0, and in accordance with advices from [the Meteor Guide](https://guide.meteor.com/writing-atmosphere-packages.html#peer-npm-dependencies), we no more hardcode NPM dependencies in the `Npm.depends` clause of the `package.js`.
Instead we check npm versions of installed packages at runtime, on server startup, in development environment.
Dependencies as of v 1.2.0:
```js
'lodash': '^4.17.0'
```
Each of these dependencies should be installed at application level:
```sh
meteor npm install --save
```
## Translations
None at the moment.
## Cookies and comparable technologies
None at the moment.
## Issues & help
In case of support or error, please report your issue request to our [Issues tracker](https://github.com/trychlos/pwix-app-pages/issues).
---
P. Wieser
- Last updated on 2025, Jul. 8th