Skip to content
Same view, same view model, but different DOM position. Portal custom attribute to render your component anywhere.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.rollupcache feat(deps): update dependencies, use new core APIs Jul 2, 2018
dist
doc fix(readme): correct doc Jan 15, 2018
src
test
.gitignore initial commit Jan 15, 2018
.npmignore initial commit Jan 15, 2018
CONTRIBUTING.md
ISSUE_TEMPLATE.md
LICENSE
README.md
config.js
package.json
rollup.config.js feat(deps): update dependencies, use new core APIs Jul 2, 2018
tsconfig.json
tslint.json

README.md

aurelia-portal-attribute

Join the chat at https://gitter.im/aurelia/discuss CircleCI

[Introduction]

This article covers the portal attribute plugin for Aurelia. This plugin is created for managing rendering flow of part of custom element in an Aurelia application. The plugin supports the use of dynamic elements matching as render target, via either element references or CSS selectors. Online Demo

[Installing The Plugin]

  1. In your JSPM-based project install the plugin via jspm with following command
jspm install aurelia-portal-attribute

If you use Webpack, install the plugin with the following command

npm install aurelia-portal-attribute --save

If you use the Aurelia CLI, install the plugin with the following command

au install aurelia-portal-attribute

alternatively you can manually add these dependencies to your vendor bundle:

  ...
  "dependencies": [
    {
      "name": "aurelia-portal-attribute",
      "path": "../node_modules/aurelia-portal-attribute/dist/amd",
      "main": "aurelia-portal-attribute"
    }
  ]
  1. Make sure you use manual bootstrapping. In order to do so open your index.html and locate the element with the attribute aurelia-app. Change it to look like this:
  <body aurelia-app="main">...</body>
  1. In main.js in your src:
  export function configure(aurelia) {
    aurelia.use
     .standardConfiguration()
     .plugin(PLATFORM.moduleName('aurelia-portal-attribute'))

    aurelia.start().then(a => a.setRoot());
  }

[Using The Plugin]

There are a few scenarios you can take advantage of the attribute.

  1. There is part of the element that needs to be rendered into document body. This is a common case, as the component may be nested under a overflow: hidden ancestor and it won't be able to display properly. Consider the following dom structure of a custom <combobox /> element:
  <template class="combobox">
    <div class="input-ct">
      <input ref="input" value.bind="filterText" />
    <div>
    <ul class="list-group items-list">
      <li repeat.for="item of items | filter: filterText" class="list-group-item">${item.name}</li>
    </ul>
  </template>

This structure often works fine when we have ul.list-group.item-list CSS: position: absolute; top: 100%; But it will not work when the custom element is nested inside an element with overflow: hidden, or inside an element with scroll, like following example:

  <!-- app.html -->
  <div style="height: 200px; overflow: auto;">
    <!-- oopps, my list got clipped -->
    <combobox></combobox>
  </div>

A simple solution is to use CSS: position: fixed on the list and calculat its position, or the portal attribute like the following example:

  <template class="combobox">
    <div class="input-ct">
      <input ref="input" value.bind="filterText" />
    <div>
    <ul portal class="list-group items-list">
      <li repeat.for="item of items | filter: filterText" class="list-group-item">${item.name}</li>
    </ul>
  </template>

portal attribute may seem to be an overkill, but beside styling, it also helps you separate DOM path of different parts in your custom element, whist still binds them to the same underlying view model, which should helps better DOM manangement, including event model in some cases. Following is an example of final rendered DOM tree for <combobox/> above:

  <body>
    <app>
      <combobox>
        <!-- combobox internal elements -->
      </combobox>
    </app>
    <!-- combobox item list in the body -->
    <ul class="list-group items-list">
      <li class="list-group-item">item 1</li>
      <li class="list-group-item">item 2</li>
      <li class="list-group-item">item 3</li>
      ...
      <!-- more items -->
    </ul>
  </body>

Usage Examples / Scenarios

TODO

Building The Code

To build the code, follow these steps.

  1. Ensure that NodeJS is installed. This provides the platform on which the build tooling runs.
  2. From the project folder, execute the following command:
npm install
  1. To build the code, you can now run:
npm run build
  1. You will find the compiled code in the dist folder, available in three module formats: AMD, CommonJS and ES6.

Running The Tests

npm test

Acknowledgement

Thanks goes to Dwayne Charrington for his Aurelia-TypeScript starter package https://github.com/Vheissu/aurelia-typescript-plugin

You can’t perform that action at this time.