uPortal-web-components

Développer des composants Web Vue pour uPortal

Guide étape par étape pour le composant vue.js

Prérequis
1. Node.js
2. Vue CLI
3. Maven
4. Gradle
Générer une application Vue
Ajouter un support de gradle pour les WebJars
Éditer l’application Vue
Assembler et déployer l’application Vue
Ajouter le composant dans uPortal
1. Créer un fichier portlet-definition.xml
2. Éditer le fichier portlet-definition
3. Remplacer les valeurs entre le CDATA dans votre portlet-definition
4. Autres options de la portlet-definition (ne pas oublier d’ajouter des permissions)
5. Ajouter le webjar au resource server
Sélectionner le composant dans uPortal (note : par défaut, depuis uPortal-start, il semble que vous ne pouvez l’ajouter qu’à d’autres onglets, et non à l’onglet d’accueil par défaut, qui peut être verrouillé selon les configurations).

1. Prérequis

Node.js

Si vous n’avez pas de Node installé, il y a plusieurs façons de le faire. Une est d’utiliser Node Version Manager (nvm).

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash

Installer la dernière version LTS (Long Term Support) de Node (actuellement 10.15.1).

nvm install node

Vue CLI

Si vous n’avez pas Vue cli installé (Node doit déjà être installé).

npm install --global @vue/cli

Maven

Utiliser le gestionnaire de paquets approprié pour votre système d’exploitation. Ces instructions ont été testées avec maven version 3.6.

Gradle

Utiliser le gestionnaire de paquets approprié pour votre système d’exploitation. Ces instructions ont été testées avec le gradle 5.2.

2. Générer une application Vue

Remplacer {nom-du-composant} avec le nom souhaité pour le composant.

vue create {nom-du-composant} --default

Installer les dépendances pour le support des anciens navigateurs dans l’application nouvellement générée.

cd {nom-du-composant}

npm install --save-dev @babel/{cli,plugin-transform-runtime,preset-env}

3. Ajouter un support de gradle pour les WebJars

Créer un fichier gradle.properties

Dans le répertoire racine, créer un fichier gradle.properties, avec le contenu suivant :

group=org.webjars.npm

Créer un fichier build.gradle

Copier le fichier build.gradle file depuis le répertoire @uportal du projet uPortal-web-components (ou utiliser un de ceux de l’Annexe).

https://github.com/uPortal-contrib/uPortal-web-components/blob/master/%40uportal/build.gradle

Si vous utilisez celui d’uPortal-web-components, supprimer la ligne subprojects jusqu’à la fin de ses accolades, par exemple :

- subprojects {

    apply plugin: 'java'
    apply plugin: 'maven'

    def jsonFile = file("${projectDir}/package.json")
    def parsedJson = new groovy.json.JsonSlurper().parseText(jsonFile.text)
    project.version = parsedJson.version + '-SNAPSHOT'

    jar {
        baseName "uportal__${project.name}"
        from '.'
        exclude 'build'
        exclude 'node_modules'
        into "META-INF/resources/webjars/uportal__${project.name}/${project.version}"
    }

- }

Cela devrait ressembler au final à quelque chose comme ceci :

    apply plugin: 'java'
    apply plugin: 'maven'

    def jsonFile = file("${projectDir}/package.json")
    def parsedJson = new groovy.json.JsonSlurper().parseText(jsonFile.text)
    project.version = parsedJson.version + '-SNAPSHOT'

    jar {
        baseName "uportal__${project.name}"
        from '.'
        exclude 'build'
        exclude 'node_modules'
        into "META-INF/resources/webjars/uportal__${project.name}/${project.version}"
    }

Note : Pour produire le .jar le plus compact possible ceci afin de réduire le trafic du resource server et d’accélérer le temps de réponse du navigateur, ou si vous développez sous Windows, essayer ce build.gradle pour Linux et Mac OS ou ce build.gradle pour Windows.

Ajouter un wrapper Gradle au projet

Lancer cette commande :

gradle wrapper --gradle-version=5.1.1

Note : Maintenant que le projet a un fichier build.gradle et un wrapper Gradle, un IDE comme IntelliJ IDEA le reconnaîtra comme un projet Gradle. Vous pouvez faire le reste de l’édition requise dans l’IDE.

4. Éditer l’application Vue

Renommer HelloWorld.vue

Renommer le fichier HelloWorld.vue généré, remplacer {nom-du-composant} avec le vôtre :

DEPUIS :
src/components/HelloWorld.vue

VERS :
src/components/{nom-du-composant}.vue

Éditer App.vue

Rename the imports.generated HelloWorld.vue file, replace {nom-du-composant} with yours: Renommer le fichier d’imports généré HelloWorld.vue, remplacer {nom-composant} par les vôtres :

// DEPUIS :
import HelloWorld from './components/HelloWorld.vue';

// À :
import HelloWorld from './components/{nom-du-composant}.vue';

Éditer package.json

Le {nom-du-composant} après --name doit avoir un trait d’union, par exemple --name machin-meteo. Modifier comme ce qui suit :

// DEPUIS :
    "build": "vue-cli-service build",

// À (assurez-vous d’avoir bien renommé {nom-du-composant}):
    "prebuild": "babel node_modules/@vue/web-component-wrapper/dist/vue-wc-wrapper.js -o node_modules/@vue/web-component-wrapper/dist/vue-wc-wrapper.js",
    "build": "vue-cli-service build --name {nom-du-composant} --target wc src/components/{nom-du-composant}.vue",

Ajouter ces déclarations de niveau supérieur ::

  "main": "dist/{nom-du-composant}.js",
  "source": "src/components/{nom-du-composant}.vue",

Par exemple :

{
  "name": "@uportal/machin-meteo",
  "version": "0.1.0",
  "private": true,
  "main": "dist/machin-meteo.js",
  "source": "src/components/machin-meteo.vue",
  "scripts": {
    "serve": "vue-cli-service serve",
    "prebuild": "babel node_modules/@vue/web-component-wrapper/dist/vue-wc-wrapper.js -o node_modules/@vue/web-component-wrapper/dist/vue-wc-wrapper.js",
    "build": "vue-cli-service build --name machin-meteo --target wc src/components/machin-meteo.vue",
    "lint": "vue-cli-service lint"
  },
  ...
}

Éditer babel.config.js

Remplacer le contenu de babel.config.js par ceci :

module.exports = {
  presets: ['@babel/preset-env'],
  plugins: [['@babel/plugin-transform-runtime', { useESModules: true }]],
};

5. Assembler et déployer l’application Vue

Pour empaqueter le composant, exécuter :

npm run build

Pour assembler le webjar et le mettre en local sur un repo Maven, lancer :

./gradlew install

6. Ajouter le composant dans uPortal

Tout ce qui suit est fait depuis le projet uPortal-start.

Créer un fichier portlet-definition.xml

Depuis le projet uPortal-start, faites une copie d’une portlet-definition.xml existante qui a un composant web.

COPIER :
data/quickstart/portlet-definition/admin-dashboard.portlet-definition.xml

EN :
data/quickstart/portlet-definition/{nom-du-composant}.portlet-definition.xml

Éditer le fichier portlet-definition

Dans le fichier portlet-definition.xml nouvellement créé, modifier les valeurs suivantes :

    <title>Titre du composant</title>
    <name>Nom du composant</name>
    <fname>nom-du-composant</fname>
    <desc>Un excellent composant qui fait des choses</desc>

Remplacer les valeurs entre le CDATA dans votre portlet-definition

Modifier par ce qui suit dans la section CDATA de la portlet-définition, en changeant {nom-du-composant} par le nom de votre composant et en conservant les lignes d’ouverture et de fermeture du CDATA:

<portlet-preference>
    <name>content</name>
    <readOnly>false</readOnly>
    <value>
        <![CDATA[
           <script src="https://unpkg.com/vue"></script>
           <script type="text/javascript" src="/resource-server/webjars/uportal__{nom-du-composant}/dist/{nom-du-composant}.min.js"></script>

           <{nom-du-composant}></{nom-du-composant}>

       ]]>
    </value>
</portlet-preference>

Pour retrouver le nom du fichier en min.js de votre composant que vous allez appeler dans le script, examinez le contenu du webjar qui a été créé. Lancer cette commande bash par exemple :

ls -al ~/.m2/repository/org/webjars/npm/uportal__machin-meteo/0.1.0-SNAPSHOT/*.jar

Ceci vous montrera le fichier .jar nommé :

uportal__machin-meteo-0.1.0-SNAPSHOT.jar

Inspecter ainsi maintenant le contenu du fichier .jar :

jar tvf uportal__machin-meteo-0.1.0-SNAPSHOT.jar | grep min.js

Ceci vous montrera :

META-INF/resources/webjars/uportal__machin-meteo/0.1.0-SNAPSHOT/dist/machin-meteo.min.js

Donc le nom du fichier min.js est donc machin-meteo.min.js, qui sera ce que vous devez mettre en valeur de la balise

Autres options de la portlet-definition

Pour ajouter un encadrement (l’encadrement standard avec bordure des portlets):

    <parameter>
        <name>chromeStyle</name>
        <value>default</value>
    </parameter>

Pour retirer l’encadrement :

    <parameter>
        <name>chromeStyle</name>
        <value>no-chrome</value>
    </parameter>

Ajouter le webjar au resource server

Dans le fichier overlays/resource-server/build.gradle de votre projet uPortal-start, ajouter la dépendance d’exécution suivante:

    runtime "org.webjars.npm:uportal__{nom-du-composant}:{version}@jar"

Par exemple:

    runtime "org.webjars.npm:uportal__machin-meteo:0.1.0-SNAPSHOT@jar"

Annexe

installation de Node.js

Mac OS X

MacPorts
HomeBrew
l’installeur MacOS (.pkg) depuis le site web de Node.js

avec MacPorts

sudo port list | grep node
sudo port install nodejs10

avec Homebrew

brew search node
brew install node

fichiers build.gradle

Pour produire des fichiers .jar vraiment compacts que le resource server d’uPortal fournira au navigateur de vos utilisateurs, essayer ceci : (tous les fichiers étrangers à l’exception du fichier *.min.js seront exclus du fichier.jar généré.)

build.gradle pour Linux et Mac OS

apply plugin: 'java'
apply plugin: 'maven'

def jsonFile = file("${projectDir}/package.json")
def parsedJson = new groovy.json.JsonSlurper().parseText(jsonFile.text)
project.version = parsedJson.version + '-SNAPSHOT'

jar {
    baseName "uportal__${project.name}"
    from '.'
    include 'META-INF'
    include 'dist/*'
    exclude "dist/demo.html"
    exclude "dist/${project.name}.js"
    exclude "dist/${project.name}.js.map"
    exclude "dist/${project.name}.min.js.map"
    into "META-INF/resources/webjars/uportal__${project.name}/${project.version}"
}

build.gradle pour Windows

Windows a une bizarrerie, que les tâches copyFiles et cleanUp dans ce fichier build.gradle permettent de contourner. Cela fonctionnera également sous Mac OS et Linux…

apply plugin: 'java'
apply plugin: 'maven'

def jsonFile = file("${projectDir}/package.json")
def parsedJson = new groovy.json.JsonSlurper().parseText(jsonFile.text)
project.version = parsedJson.version + '-SNAPSHOT'


task copyFiles{
    copy{
        from ('.'){
            exclude '*.lock'
            exclude '**/*.lock'
            exclude 'build/*'
            exclude 'node_modules/*'
        }
        into 'build_tmp/target/content'
    }
}

jar {
    baseName "uportal__${project.name}"
    from '.'
    include 'META-INF'
    include 'dist/*'
    exclude "dist/demo.html"
    exclude "dist/${project.name}.js"
    exclude "dist/${project.name}.js.map"
    exclude "dist/${project.name}.min.js.map"
    into "META-INF/resources/webjars/uportal__${project.name}/${project.version}"
}

task cleanUp(type: Delete) {
    delete 'build_tmp'
    followSymlinks = true
}

jar.finalizedBy cleanUp

This site is open source. Improve this page.