Neutrino Packing Machine

    @eeacms/volto-object-widget

    4.0.1 • Public • Published

    volto-object-widget

    Releases

    Pipeline Lines of Code Coverage Bugs Duplicated Lines (%)

    Pipeline Lines of Code Coverage Bugs Duplicated Lines (%)

    Volto add-on: Various Volto schema-based widgets.

    Features

    This Volto addon provides several "abstract" widgets, to allow complex information to be editable by the schema-based forms. It centers around the concept: "we can create a form to edit a JSON object by using a schema" and so it provides, right now, widgets to edit "list of JSON objects", a "mapping of JSON objects" and a single "JSON object, but I choose the schema for it".

    FlatListObject

    Flat List object

    This widget allows you to edit a list of objects by creating, editing and deleting instances of objects editable with the provided schema parameter. The list is sortable with drag&drop. You can also provide a schema extender, a function with signature (schema, data) => schema, which will adjust, per instance of object, its schema. To use this widget, in the schema, set the widget field to object_list_inline.

    Example of how the data could look like for a block:

    "a55c5053-ba81-4f73-ab29-7cdea74df20f": {
    	"@type": "dataTable",
    	"columns": [
    		{
    			"@id": "f899ca76-68be-4ded-aa0b-669c04c27309",
    			"column": " PERC_HA_07\n(in %)",
    			"renderer": "progress",
    			"title": "21"
    		},
    		{
    			"@id": "94315c5a-e031-4b7e-acb2-93887878a252",
    			"column": " PERC_HA_07\n(in %)",
    			"title": "12"
    		}
    	],
    }
    

    The columns field, in this case, is data generated by the FlatListObject. The schema for this field could look like (ColumnSchema() just generates another instance of a schema, suitable for the column definition of our specific use case):

    columns: {
      title: 'Columns',
      description: 'Leave empty to show all columns',
      schema: ColumnSchema(),
      widget: 'object_list_inline',
    },
    

    Mapping Widget

    Mapping widget

    This widget allows editing the properties of an object. For example, in the following block data, the row_colors value is generated by an instance of the MappingWidget.

    "4430a32a-a266-497b-88e7-72fead5ab718": {
      "@type": "dottedTableChart",
      "column_data": "habitat_group",
      "row_colors": {
        "Bad": "#ed1834",
        "F - Heathland, scrub and tundra": "#88c24f",
        "Good": "#3c8000",
        "Poor": "#f2a70e",
        "Unknown": "#8d8d8d"
      },
      "row_data": "assessment",
      "size_data": "quantity"
    },
    

    You need to provide the options, which is a list of objects with {id, title} and the field_props, which are parameters for the actual field that will be used to edit the values. In our case the schema definition that was used to edit the above value is (note, the options are empty, we're populating them in the edit component, before passing the schema to the form):

    row_colors: {
      title: 'Colors',
      widget: 'option_mapping',
      field_props: {
        widget: 'simple_color',
        available_colors: settings.available_colors,
      },
      options: [],
    }
    

    To use this widget, in the schema, set the widget field to option_mapping.

    Object by type

    Object by type

    With this widget you can choose the type of value that will be used, from a predefined list of schemas. A schema that would use this type of widget could look like:

    const LinkEditSchema = {
      title: 'Link',
      fieldsets: [
        {
          id: 'default',
          title: 'Default',
          fields: ['link'],
        },
      ],
      properties: {
        link: {
          title: 'Link',
          widget: 'object_by_type',
          schemas: [
            {
              id: 'internal',
              icon: internalSVG,
              schema: InternalLinkSchema,
            },
            {
              id: 'external',
              icon: externalSVG,
              schema: ExternalLinkSchema,
            },
            {
              id: 'email',
              icon: emailSVG,
              schema: EmailLinkSchema,
            },
          ],
        },
      },
      required: [],
    };
    

    To use this widget, in the schema, set the widget field to object_by_type.

    Getting started

    1. Create new volto project if you don't already have one:

      $ npm install -g yo @plone/generator-volto
      $ yo @plone/volto my-volto-project --addon @eeacms/volto-object-widget
      
      $ cd my-volto-project
      $ yarn add -W @eeacms/volto-object-widget
      
    2. If you already have a volto project, just update package.json:

      "addons": [
          "@eeacms/volto-object-widget"
      ],
      
      "dependencies": {
          "@eeacms/volto-object-widget": "^2.0.0"
      }
    3. Install new add-ons and restart Volto:

      $ yarn
      $ yarn start
      
    4. Go to http://localhost:3000

    5. Happy editing!

    Release

    Automatic release using Jenkins

    • The automatic release is started by creating a Pull Request from develop to master. The pull request status checks correlated to the branch and PR Jenkins jobs need to be processed successfully. 1 review from a github user with rights is mandatory.
    • It runs on every commit on master branch, which is protected from direct commits, only allowing pull request merge commits.
    • The automatic release is done by Jenkins. The status of the release job can be seen both in the Readme.md badges and the green check/red cross/yellow circle near the last commit information. If you click on the icon, you will have the list of checks that were run. The continuous-integration/jenkins/branch link goes to the Jenkins job execution webpage.
    • Automated release scripts are located in the eeacms/gitflow docker image, specifically js-release.sh script. It uses the release-it tool.
    • As long as a PR request is open from develop to master, the PR Jenkins job will automatically re-create the CHANGELOG.md and package.json files to be production-ready.
    • The version format must be MAJOR.MINOR.PATCH. By default, next release is set to next minor version (with patch 0).
    • You can manually change the version in package.json. The new version must not be already present in the tags/releases of the repository, otherwise it will be automatically increased by the script. Any changes to the version will trigger a CHANGELOG.md re-generation.
    • Automated commits and commits with [JENKINS] or [YARN] in the commit log are excluded from CHANGELOG.md file.

    Manual release from the develop branch ( beta release )

    Installation and configuration of release-it

    You need to first install the release-it client.

    npm install -g release-it
    

    Release-it uses the configuration written in the .release-it.json file located in the root of the repository.

    Release-it is a tool that automates 4 important steps in the release process:

    1. Version increase in package.json ( increased from the current version in package.json)
    2. CHANGELOG.md automatic generation from commit messages ( grouped by releases )
    3. GitHub release on the commit with the changelog and package.json modification on the develop branch
    4. NPM release ( by default it's disabled, but can be enabled in the configuration file )

    To configure the authentification, you need to export GITHUB_TOKEN for GitHub

    export GITHUB_TOKEN=XXX-XXXXXXXXXXXXXXXXXXXXXX
    

    To configure npm, you can use the npm login command or use a configuration file with a TOKEN :

    echo "//registry.npmjs.org/:_authToken=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYY" > .npmrc
    

    Using release-it tool

    There are 3 yarn scripts that can be run to do the release

    yarn release-beta

    Automatically calculates and presents 3 beta versions - patch, minor and major for you to choose ( or Other for manual input).

    ? Select increment (next version):
    ❯ prepatch (0.1.1-beta.0)
      preminor (0.2.0-beta.0)
      premajor (1.0.0-beta.0)
      Other, please specify...
    
    yarn release-major-beta

    Same as yarn release-beta, but with premajor version pre-selected.

    yarn release

    Generic command, does not automatically add the beta to version, but you can still manually write it if you choose Other.

    Important notes

    Do not use release-it tool on master branch, the commit on CHANGELOG.md file and the version increase in the package.json file can't be done without a PULL REQUEST.

    Do not keep Pull Requests from develop to master branches open when you are doing beta releases from the develop branch. As long as a PR to master is open, an automatic script will run on every commit and will update both the version and the changelog to a production-ready state - ( MAJOR.MINOR.PATCH mandatory format for version).

    How to contribute

    See DEVELOP.md.

    Copyright and license

    The Initial Owner of the Original Code is European Environment Agency (EEA). All Rights Reserved.

    See LICENSE.md for details.

    Funding

    European Environment Agency (EU)

    Install

    npm i @eeacms/volto-object-widget

    DownloadsWeekly Downloads

    835

    Version

    4.0.1

    License

    MIT

    Unpacked Size

    164 kB

    Total Files

    35

    Last publish

    Collaborators

    • valentinab25
    • demarant
    • avoinea
    • tiberiuichim
    • zotya
    • alecghica
    • eea-jenkins
    • razvan.miu
    • ichimdav