https://github.com/vpro/magnolia-vpro-ui

irma magnolia magnolia-cms magnolia-ui
Last synced: 9 months ago
JSON representation
Host: GitHub
URL: https://github.com/vpro/magnolia-vpro-ui
Owner: vpro
License: apache-2.0
Created: 2022-01-07T15:55:19.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2023-10-25T20:57:58.000Z (over 2 years ago)
Last Synced: 2025-02-16T15:17:31.760Z (over 1 year ago)
Topics: irma, magnolia, magnolia-cms, magnolia-ui
Language: Java
Homepage:
Size: 2.15 MB
Stars: 2
Watchers: 5
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project

README

          = VPRO magnolia UI components

:toc:

:toclevels: 5

:VERSION: 1.9

:VPRO_SHARED_VERSION: 3.5.4

image:https://github.com/vpro/magnolia-vpro-ui/workflows/build/badge.svg?[Build Status,link=https://github.com/vpro/magnolia-vpro-ui/actions/workflows/maven.yml]

image:https://img.shields.io/maven-central/v/nl.vpro.magnolia/magnolia-vpro-ui.svg[MavenCentral,link=https://search.maven.org/search?q=g:%22nl.vpro.magnolia%22]

// image:http://www.javadoc.io/badge/nl.vpro.magnolia/magnolia-vpro-ui/.svg?color=blue[javadoc,link=http://www.javadoc.io/doc/nl.vpro.magnolia/magnolia-vpro-ui/]

// image:https://codecov.io/gh/vpro/magnolia-vpro-ui/branch/main/graph/badge.svg[codecov,link=https://codecov.io/gh/vpro/magnolia-vpro-ui]

image:https://img.shields.io/nexus/s/https/oss.sonatype.org/nl.vpro.magnolia/magnolia-vpro-ui.svg[snapshots,link=https://oss.sonatype.org/content/repositories/snapshots/nl/vpro/magnolia/magnolia-vpro-ui/]

== Introduction

These are a few magnolia UI components which we developed mostly years ago. Recently we migrated to Magnolia 6 and its new framework, and we had

to migrate these components too. We took the occasion to isolate them to this github project. Hopefully it may benefit others, or otherwise it

may at least facilitate use showing our code.

SNAPSHOTs are present in sonatype.

.pom.xml dependency

[source, xml, subs='attributes,verbatim']

----

 

  nl.vpro

  magnolia-vpro-ui

  {VERSION}

 

----

We'll make a release when we're ready, and the artifact will be available in maven central then.

Some components described below have extra dependencies, which will not come in automatically (they're optional), which is indicated in notes then.

== Fields

=== Color picker [[color_picker]]

Differences with: https://github.com/magnolia-community/color-picker-field

- stores as string, `String Color#getCSS`, rather than `int Color#getRGB`

- can show text field too (editable)

- more configurable

** `text: `

** `cssInPopup: `

** `format: `

** `pickerWidth: 100`

** `pickerHeight: 100`

.Example usage of color picker field in a form (described in yaml)

[source, yaml]

----

 color:

   $type: cssColorPickerField

   text: AFTER

   defaultValue: '#000'

   pickerWidth: 100

   pickerHeight: 100

----

=== Enum field [[enum_field]]

We provide a simpler version to use enums in a combobox.

.Example usage of enumField

[source, yaml]

----

 type:

    $type: enumField

    enum: nl.vpro.domain.koos.KoosTipType

    multiselect: 

    twinselect: 

    emptyValue: READ

----

Just specify as field $type `enumField`, and the name of the enum.

The enum is presented on default via its `toString` method, unless it implements `nl.vpro.i18n.Displayable`.

If both of these are not desired (e.g. because you can't change the implementation of the enum), then you can set a `Converter` in the field definition or extend `nl.vpro.magnolia.ui.enumfield.EnumFieldDefinition` and overwrite `#convertToPresentation`

To be used in conjuction with this, there is also a '$type: enumColumn'

[source, yaml]

----

type:

  $type: enumColumn

  enum:  nl.vpro.domain.drievoortwaalf.DrieVoorTwaalfUpdateType

----

===  Country and region field [[country_field]]

A dropdown with countries of the world

[source, yaml]

----

 country:

   $type: countryField

   useIcons: true

----

Countries are displayed in current `Locale`, and stored as ISO 639 country code.

Actually it is a specialization of `$type: regionField`, which could also be used for other type of regions like country subdivisions or continents.

[#countries]

.Example of countries drop down in use

image::{docdir}/doc/countries.png[Countries drop down]

=== Integer range field [[integerrange_field]]

Just a drop down with integers

.Example of `integerRangeField`

[source, yaml]

----

fields:

  myinteger:

    $type: integerRangeField

    min: 3

    max: 11

----

=== Virtual value field

This a field to just show some 'calculated' value. Extend `VirtualValueFieldDefinition` and implement the abstract method. (look out with bytebuddy, access all fields via getters)

=== Random UUID

Text field which default value is a random UUID.

On default, it is readonly (but this can be overridden)

[source, yaml]

----

fields:

  uuid:

    $type: randomUUIDField

----

=== DAM Link Field with edit option

Add to the default `damLinkField` an 'edit' button, to jump to the asset app and edit the image after selection.

[source, yaml]

----

fields:

  image:

    $type: damLinkFieldWithEdit

----

It also allows text input, and therefore, implicitely a link validator is added so that you can only enter valid dam links.

image::{docdir}/doc/dam-selector-with-edit.png[Dam Selector in action]

.pom.xml dependency

[source, xml, subs='attributes,verbatim']

----

  

    info.magnolia.dam

    magnolia-dam-app

    3.0.14

  

----

=== Proof of Provenance Field

To enable signing a text field using https://waag.org/en/project/proof-provenance/[irma] ('(I Reveal My Attributes)') you can use a field with type 'proofOfProvenanceField'

[source, yaml]

----

  fields:

    signedText:

      description: A text field with Proof Of Provenance

      attribute: pbdf.sidn-pbdf.email.email

      $type: proofOfProvenanceField

----

This will make a plain text field 'signedText', but it will present an extra text area which contains the 'signature', which can be filled manually, or via a button, which uses the field's value to create a signature.

image::{docdir}/doc/irma.png[Exaple of IRMA Popup]

You can also specify the textfield definition it will use. It must be a fielddefinition for a field of type `AbstractField` it will use the value from that field to sign.

[source, yaml]

----

fields:

   signedRichText:

      description: A text field with Proof Of Provenance

      attribute: pbdf.sidn-pbdf.email.email

      $type: proofOfProvenanceField

      field:

        $type: richTextField

----

== Actions

=== Auto JCR Name

Can be used as a commit action. To fill in jcrName, based on another property

[source, yaml]

----

 detail:

    class: info.magnolia.ui.contentapp.detail.DetailDescriptor

    actions:

      commit:

        $type: autoJcrCommitAction

        propertyName: name # default is 'title'

----

== Columns

=== Referred column [[referred_column]]

Can be used as a column. Like so:

.Example of `referredColumn`

[source, yaml]

----

- name: author

  $type: referredColumn

  workspace: persons

  forType:

    - mgnl:vijverTip

  otherProperty: name

----

This can be used in workbench view to display a field in another node. In this case a column `author` contains a reference to a node in the `persons` workspace, and rather then showing the `uuid` of the node, the `name` property of the referenced node is shown.

=== Unhtml column

Strip HTML markup from the value, so that it can more nicely be presented in a column

[souce, yaml]

----

 description:

   $type: unhtmlColumn

----

[NOTE]

====

For this to work you need

[source, xml, subs='attributes,verbatim']

----

  nl.vpro.shared

  vpro-shared-util

  {VPRO_SHARED_VERSION}

----

====

=== Date only column

Just shows the date part of a datetime field.

[souce, yaml]

----

 description:

   $type: dateonlyColumn

----

=== CheckBox for searching

This is to be used as `filterComponent` in a view.

[source, yaml]

----

columns:

  highlighted:

    defaultValue: false

    type: java.lang.Boolean

    filterComponent:

      $type: checkBoxSearchField

----

It'll show a checkbox. It will only filter if checked. (Or with `negate: true`, only when not checked)

[#searchablecheckbox]

.Example of checkBoxSearchField in  use

image::{docdir}/doc/searchablecheckbox.png[searchablecheckbox]

== Validators

=== Bean validation [[bean_validation]]

The idea is to use the link:https://beanvalidation.org/2.0/[`javax.validation`] framework

.Example usage of beanValidator validator.

[source, yaml]

----

validators:

   urlValidation:

      $type: beanValidator

      bean: nl.vpro.koos.KoosTip

      property: link

----

This way the validation of given bean property is 'borrowed', which is for example in this case exactly what we want, because the value will

end up there eventually.

[NOTE]

====

For this to work you need a validator implementation.

.Dependency on validator implementation

[source, xml]

----

  org.hibernate.validator

  hibernate-validator

  6.2.1.Final

----

====

=== HTML embed validator

Checks whether the value is acceptable as an embed code. The contained HTML must be sane, and contain only https-references.

.Example usage of htmlEmbed validator.

[source, yaml]

----

validators:

   embedValidation:

      $type: htmlEmbedValidator

----

=== Link validator

.Example usage of linkValidator

[source, yaml]

----

validators:

   embedValidation:

      $type: linkFieldValidator

----

=== Word count validator

[source, yaml]

----

fields:

  a_text_field:

      description: 10 words max!

      rows: 5

      required: false

      $type: richTextField

      validators:

        words:

          parseHtml: true

          $type: wordcountValidator

          wordcount: 10

----

=== URL validator

[source, yaml]

----

validators:

   url:

      $type: urlValidator

----

[NOTE]

====

For this to work you need

.Dependency on validator implementation

[source, xml, subs='attributes,verbatim']

----

  nl.vpro.shared

  vpro-shared-validation

  {VPRO_SHARED_VERSION}

  org.hibernate.validator

  hibernate-validator

  6.2.1.Final

----

====

The URL must parse, have a scheme, and the host must have at least two parts.

It is also available implicitly on 'urlField':

[source, yaml]

----

fields:

   urlField:

     descripton: Also an URL, but the validator is implicit

     $type: urlField

----

== POMS extensions

image:https://img.shields.io/nexus/s/https/oss.sonatype.org/nl.vpro.magnolia/magnolia-vpro-ui-poms.svg[snapshots,link=https://oss.sonatype.org/content/repositories/snapshots/nl/vpro/magnolia/magnolia-vpro-ui-poms/]

POMS is a CMS for media meta data, which  is in use at dutch public brothcasters (a.o. VPRO).

[NOTE]

====

For these to work you need

[source, xml, subs='attributes,verbatim']

----

   nl.vpro.magnolia

   magnolia-vpro-ui-poms

   {VERSION}

----

====

=== Fields

==== Media chooser

Shows a text field and a button. If you click on the button the POMS 'Media Selector' will be popped up, and you can select a media object. You'll need a poms-account for this.

[source, yaml]

----

fields:

  media:

    $type: mediaChooserField

    mediaType:

      - BROADCAST

      - SERIES

----

A property poms `poms.baseUrl=https://poms.omroep.nl/` is used and can be overriden to point to test or acceptance environment.

[#poms-selector]

.Example of poms selector in use

[link=https://poms.omroep.nl/CMSSelector/example]

image::{docdir}/doc/poms-selector.png[pomsselector]

==== Thesaurus

TODO, a very similar popup exists for the Thesaurus of  Beeld & Geluid. Integration would be quite straight forward.

==== Media types

A dropdown with types from POMS. Based on the enum in `media-domain`

[source, yaml]

----

fields:

  mediaType:

    $type: pomsTypesField

----

==== Age ratings

link:https://www.kijkwijzer.nl/[NICAM] age ratings

[source, yaml]

----

fields:

  ageRating:

    $type: ageRatingField

----

[#ageratings]

.Example of age ratings in use

image::{docdir}/doc/ageratings.png[ageratings drop down]

==== Content ratings

link:https://www.kijkwijzer.nl/[NICAM] content ratings

[source, yaml]

----

fields:

  contentRating:

    $type: contentRatingsField

----

==== Channels

Drop down with all known channels. Channels that at some point where visible in the Netherlands. Based on the enum in `media-domain`.

[source, yaml]

----

fields:

   channel:

      $type: channelField

----

==== Broadcasters

Dropdown with all known Dutch broadcasters. Based on https://poms.omroep.nl/broadcasters/ (or, actually, a link:https://poms.omroep.nl/broadcasters/CSV[CSV] version )

[source, yaml]

----

fields:

   broadcasters:

      $type: broadcastersField

   twinBroadcasters:

      $type: broadcastersTwinField

----

== Versions

|===

|Version | Java  | magnolia | shared | poms | Remarks

| 1.7 | 8 |  6.2.22     | 2.33 | 6.0 |

| 1.8 | 11 |  6.2.28     | 3.0 | 7.1 |

| 1.9 | 11 |  6.2.38     | 3.5 | 7.6 |

| 1.10   | 17 | 6.2.39 | 4.0 | 7.7 |

|===
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/vpro/magnolia-vpro-ui

Awesome Lists containing this project

README
