dsv-su/resultpress

Dev repository for ResultPress

1. Overview

Development setup for ResultPress.

2. Requirements

Requirements are best determined using Server Requirements page of corresponding Laravel 7 version Currently used version is 7.10.3

• PHP version 7.3.*

• BCMath PHP Extension

• Ctype PHP Extension

• Fileinfo PHP extension

• JSON PHP Extension

• Mbstring PHP Extension

• OpenSSL PHP Extension

• PDO PHP Extension

• Tokenizer PHP Extension

• XML PHP Extension

• SSH access to the server

• Composer

3. Installation

• Make sure that composer is installed globally or install it in place

• Clone the repository

• Move into the directory. Move into the /systemconfig folder.

• Make sure that /systemconfig/resultpress.ini file is present and configured with the configuration details for your requirements and for the server (copy resultpress.ini.example to .ini and fill in with your data)

    [global]
    app_env=local                           ; Make sure this is set to local NOTE! For production enviroment the settings should be set to: app_env=production and app_debug=false.
    app_debug=true                          ; Make sure this is set to true
    app_url=http://localhost                ; Set this to localhost or your domain
    authorization_parameter=entitlement     ; The authorization parameter NOTE! Not used for dev enviroments
    authorization=                          ; Authorization entitlements NOTE! Not used for dev enviroments
    login_route=/login                      ; The SSO login route for your application (The production server should be set ut with this route) 
    
    [database]
    db=mysql                                ; Here you can specify which database you use: mysql, sqlite, pgsql, sqlsrv or redis 
    db_host=127.0.0.1                       ; DB host address
    db_port=3306                            ; DB port
    db_database=                            ; Database used     
    db_username=                            ; DB user
    db_password=                            ; secret
    
    [oauth2]                                ; Here you add the registered providers client id, client secrets and callback URI:s
    github_client_id=                       
    github_client_secret=
    github_callback=https://resultpress.dev/partner-login/github/callback
    
    facebook_client_id=                     
    facebook_client_secret=
    facebook_callback=https://resultpress.dev/partner-login/facebook/callback
    
    linkedin_client_id=
    linkedin_client_secret=
    linkedin_callback=https://resultpress.dev/partner-login/linkedin/callback
    
    google_client_id=
    google_client_secret=
    google_callback=https://resultpress.dev/partner-login/google/callback
  

• Once the global settings are entered you can install the dependencies. composer install

• Make sure that .env file is present (copy .env.example to .env).

• Either create application key manually or do that with a command php artisan key:generate

• Make sure the subdirectories bootstrap/cache and /storage is writable by your web server user.

• If you need to change the email configuration. Open the .env file and set the needed values

• Create the database and seed the default permissions and roles with php artisan migrate --seed (this should create database tables needed and populate necessary user permissions)

• First time installation: run Admin seeder for creating an Administrator account: php artisan db:seed --class=CreateAdminUserSeeder this will make the default user account an Administrator (this should be removed in production)

###Database structure

resultpress's Issues

Gantt charts

Projects and program time plans should be able to be represented as gantt charts based on the available data.

Ability to assign users to more than one project

You can’t assign project to users that have already been invited. I tried it in Admi/Manage/invite. There should for instance be a list in the Add Project and Edit Project that allows Program managers to select one or more Partners to participate in the project.

Eliminate tables

Tables quickly become a problem on small screens, so they should be avoided. If a tabe is absolutely necessary (possibly in a gantt view for instance), make sure smaller screens handle it properly with min-width settings and horizontal scrolling.

Sane defaults on all input fields

All input fields should assume sane defaults as far as possible (the "placeholder=" attribute on input tags is great for this):

• Number fields that pre-exist should assume 0 if no input is given (the total project budget field is a good example).
• User-created number fields should require input (an ouput on the project creation page is a good example)
• Text fields should be allowed to be blank, but a confirmation dialog should be shown if all text fields on the page are blank on submission.

Implement cumulative activity updates

Feature summary:

• Cumulative update support
• Ability to choose between cumulative or standalone updates at the project level

Research projects need activity updates to build on one another. Imagine the following situation (assuming standalone updates):

Activity template:

• Heading 1
• Heading 2

Update 1:

• Heading 1
  text text text

• Heading 2
  foo foo foo

Update 2:

• Heading 1
  bar bar bar

• Heading 2
  baz baz baz

These two updates can't be presented as cohesive text. They could be presented like this:

• Heading 1
  text text text
  bar bar bar

• Heading 2
  foo foo foo
  baz baz baz

However, this becomes messy since the writer of each update needs to keep track of what was previously written on their own and can't change anything from a previous update to make text flow better or resolve inconsistencies.

A better approach then would be this (trailing + and - denote differences to the previous update/template):

Activity template:

• Heading 1
• Heading 2

Update 1:

• Heading 1
  text text text +
• Heading 2
  foo foo foo +

Update 2:

• Heading 1
  text text text
  bar bar bar +

• Heading 2
  foo foo foo -
  baz baz baz

The final text would then become:

• Heading 1
  text text text
  bar bar bar

• Heading 2
  baz baz baz

Since each update builds on the previous but doesn't change anything in older updates, auditability comes baked in. The final cumulative state of the activity update text would simply be the 'playback' of all the diffs in order. The cumulative state at some previous point in time is just all updates 'played back' up to that date.

The project summary page should show the cumulative state of all existing updates under each activity.
Viewing a single update should show the cumulative state for all covered activities up until that point.

Ability to view more detailed diffs showing what exactly was added and/or removed by a specific update may become important in the future, but is not necessary at the moment. The option should be kept open though.

Each project should be able to choose whether they want to use standalone or cumulative updates. This should be part of project creation.

Ouput targets in project summary

The project summary should list the targets of outputs along with their states.

Either have a separate field for the target value, or combine current and target into one field as "current / target".

Unexpected outputs should display "unplanned" in the target field if it is separate. If the values get combined into one field, just skip the "/ target" part for unexpected outputs.

Support for multiple currencies

Each project should be able to set its own currency. The default should always be SEK.

This feature is slightly in question due to reporting requirements on all budgets being in SEK. Currency conversions could become an issue as well.

Draft updates

Project updates should have the ability to be saved as a draft before being properly submitted. Draft updates should not have their modifications logged (until proper submission).

Filtering project lists

There will need to be some way of filtering project lists based on project state. This depends on #25 being done.

Since project states are a strict progression (is that certain?), a min-max slider may be appropriate. Another approach would be to collate projects within a listing based on their state, but this may cause difficulty finding a project if its state has changed unexpectedly.

In order to make sure finished projects don't start cluttering things up in a few years, the default filter should hide projects that have reached an end state (finished? maybe an archived state?).

Customizable site header and footer

The site header should be customizable, along with the footer.

Since at least the header can include an image (or as right now, two), some kind of handling of that will be necessary. Base64 embedding of images might be the best option here, since it makes it possible to include an arbitrary number of images in the header without worrying about storing uploaded files. It would need to be implemented such that the user doesn't need to do the encoding/embedding though.

One option to implement image embedding would be to use https://github.com/arcs-/medium-button to create a custom button in medium-editor that would wrap the upload->base64->embed flow.

Project update templates

It should be possible to create templates that pre-populate the project update text box with some text. Depends on #15.

Templates should be local to a project, but importable (possibly by simply copying and pasting manually) between projects.

It should be possible to pick a template from the defined templates for the project when on the update writing page. Creating update "types" based on templates, possibly bound to specific activities, may become an option.

End dates should depend on start dates in project/activities

It's now possible that end date is lower than start date. It should be fixed to validate that the end date is greater or equal than the start date. Also its default value should be equal to the selected start date.

Ability to view a project summary for an arbitrary historic date

Project summaries currently reflect the state of the project as of the viewing date. It should also be possible to pick a date since project start and see a project summary as of that date.

Once #10 is implemented it would be nice to integrate the two - pick a point in the gantt timeline and get an overview of the project state.

Configurable project lists for spider users

Spider users need to be able to narrow down the number of projects they see when logging in, while being able to find any project they have access to if they need to. This is of partially dependent on how program areas get implemented.

Upon login the user should be presented with a personal start page. It should consist of threee major parts:

• Owned projects: all projects the user is an owner of
• Program area projects: the user should be able to configure program areas of interest, whose projects all get listed (collated by program area)
• All (other?) projects: a list of all projects the user has any access to at all. This should probably be initially collapsed for enhanced readability of the page once many projects exist on the platform.

Establishing project and activity states

The exact states possible for a project need to be established.

A starting point:

• Pending (white): The project exists but its start date has not yet passed (I don't like this name but it's the best I can come up with atm)
• In progress (yellow): The project has started and is not currently behind on anything
• Delayed (red): Some activity has passed its expected end date without being marked as done
• Pending review (blue): One or more updates have yet to be reviewed by spider
• Finished (green): The end date has passed and all activities are marked as done
• Archived (gray): The project has been marked as completely done and is not expected to need regular interaction any more

The archived state should be settable by a spider user at the project level. Other states are calculated.
Bonus points if delayed and pending review states somehow indicate which activities/updates they pertain to (tooltip? links?).

Activity states should be able to be largely similar:

• Pending (white): Start date not yet passed and no updates exist
• In progress (yellow): Start date has passed or an update exists
• Delayed (red): The end date has passed but the activity is not marked as done
• Pending review (blue): An update has been posted but not yet reviewed
• Finished (green): Activity is marked as done

Marking an activity as done could be part of an update, or marking an activity as done may be done during spider update review, that needs clarification. Other states are calculated.

All these things are suggestions and should be discussed, please comment if you have ideas/opinions. Since the state is essentially metadata there should be no harm in changing these things after the platform is in use, so it does not have to be finished for the initial milestone.

An overarching decision of whether states should be explicit (set by a user) or implicit (calculated) may be necessary before initial release though. I'm leaning towards implicit as described above.

Make links work when not logged in

If i'm not logged in to resultpress and click a link pointing to some part of resultpress that requires login, I get dumped at the start page after login, not at the target of the link. This should be fixed.

Ability to log off or change users

There is no log of button. It is needed to change users.

(This is a SSO-related issue. Is it better with a work-around for the few SPIDER users who will need to swap between users?)

CSS simplification/unification

The styles for the site should be streamlined so that elements get the right style by default with minimal additional styling needed (if any).

Styles for base tags (ex. button, h1, body) would help with this, as would some generic css classes (ex. small, inline, highlight) that could be used for certain common style needs. Using semantic tags (header, menu, aside, etc) may help reusability as well.

The goal is to be able to add new pages/buttons/etc in resultpress with no custom styles and they just look correct immediately.

Merge project details and summary

The details and summary pages are mutually redundant. The summary page should replace the details page and include overall project status.

Updates that cover a date range

Currently the date field on an activity covered by an update takes only a single date. It would be useful to be able to indicate that an update covers a time range, either by allowing " - " in a single field or by splitting to a start date and end date field.

I prefer the single field approach from a UI perspective, as long as the possibility to set a range is made obvious in some way.

Implement user authentication for spider users

Spider users should log in with shibboleth (preferrably without needing to be prompted as usual).

Shibboleth should work on the server within a few days. Shib login will only be forced at /login as usual.

Implement user authentication for project partners

Project partners won't be able to login using (normal) SSO. Alternative options include OAuth and local accounts.

Display units on relevant fields

Fields with defined units such as currency should display the unit as a non-editable part of the field

Update rejection

It should be possible for a reviewer to reject an update.

If an update gets rejected, it should become editable again. The editable update should behave just like a saved draft, with the exception that the rejected version should be logged as rejected.

"Create update" button in update list

There should be a button for creating a new update on the update list page.

Image embedding in updates

We should explore whether it's possible to embed an image into an update text using medium-editor. The upload process should be as streamlined as possible, ideally "click the button, pick an image, the image shows up".

Possibly embed the image directly into the dosument in a similar way as #34 would.

Database migrations

Make sure that data can be retained across updates to the system

Copy function to add similar activities

A copy function to add activities would be useful

Project updates should be more flexible

Trying to create an update that doesn't cover any outputs currently results in an error. This should be fixed. It should be discussed with spider whether an update must cover an activity at all.

It's probably not meaningful to allow updates that cover only outputs.

Change date format to DD/MM/YYYY

Dates are currently in the US format MM/DD/YYY. The rest of the world prefers DD/MM/YYYY, so let's stick with that across the entire application.

Data export & import

The ability to export an entire project to some stable format suitable for data interchange, ex. JSON or XML.

This would help testing by allowing quick loading of test projects/programs. There is also an international reporting framework whose name escapes me at the moment that in future could be supported via this route.

Ability to pull data from one project to another

Some projects need the ability to pull data from other projects and present them in context of an update.

The archetypal case is a research project studying an implementation project. The researchers need to be able to cite data from the implementation project in their updates.

The exact implementation of this linkability is unclear. One option would be to use a combination of anchor links for linking to text sections and permalinks for linking to outputs and outcomes:

• Once #15 is implemented, it should be possible to link to each heading in an update with fairly little effort. This would probably suffice for citing text. A link looking something like "resultpress.dsv.su.se/penguinproject/update3/#My_heading" should be perfectly usable.

• Implementing a permalink button next to each output and/or outcome covered in an update should cover the remaining use cases - The button produces a link similar to the one above, maybe it could be implemented with anchors the same way.

This would cover the basic usecase of "as you can see here[link]..." It may be desirable to be able to view the linked content directly though, possibly as embedded appendices to the update being written or something similar. This opens up the issue of knowing how much text after the linked anchor is relevant, which is where I think an approach similar to https://github.com/gorhill/efatmarker would be useful. Whether it's realistic and/or useful is unclear.

Compare two project updates

Continuation of #18

It should be possible to be able to compare two different project updates. In case of cumulative updates, a php-diff like lib should be used to calculate a diff between activity comments (since they're built on previous updates).

It might also be useful to be able to toggle a diff view when reviewing an update.

Add text labels to all icon buttons

Icons can be hard to decipher, text labels should be added or possibly replace icons completely.

Rework Project Summary view

It should support Outcomes (#3), also it should provide handy ways for project management (e.g. display pending updates right away)

Implement auditability

All changes done to non-draft content should be logged so as to establish a data trail on all modifications within a project and/or program.

Add expected outcomes to projects

Each outcome should be have a name, and a spider user should be able to mark each expected outcome as "done" at any time, which should include a text description of how the outcome was achieved.

It may be useful to be able to link outputs to an outcome when marking it as complete. That link should then be a "snapshot" of the state of the output at outcome completion time.

Configurable access controls on projects

Projects need access controls. There need to be at least three levels of general access:

• Administrator: can do anything on any project
• Program administrator: can do anything on any project linked to that program (once program areas get implemented)
• Spider: can read anything and full write access to specified projects
• Partner: read access to specified projects and update access to (possibly different) specified projects

The creator of a project should automatically be its 'owner', with the ability to assign further rights on that project to other users.
Administrators should always have owner-equivalent rights on all projects but not be listed as owners (unless they really do own some specific project). It should be possible to add further owners to a project.

Partner read views for projects will need to be separate from spider views, since some information is not to be exposed to project partners. The exact information to show/hide is unspecified at the moment and may differ between projects and/or project partners, so having the ability to specify certain 'classes' of information to expose to a specific project partner would be good. Something like a number of checkboxes when assigning access that grant access to specific parts of the project data would probably be a step in the right direction. The exact 'classes' are subject to change based on discussions with spider, but here are some initial ideas:

• access to budget on specified/all activities
• access to updates on specified/all activities
• access to specified/all outputs

Implement program areas

Each project should be associated to at least one program area. Program areas need to be able to have their own outputs and outcomes, which should be aggregated from related projects. The aggregation definition needs to be manually specified:

Program 1 has the output "Trainig sessions completed"
Project 1 has the output "Successful teacher training sessions"
Project 2 has the output "User education opportunities provided"

The program administrator should be able to link the outputs from project 1 and 2 to the output in program 1. Similar model for outcomes.

Integrated help functions

The system needs explanatory texts in many places. Exactly how to implement this is open. Some possibilities:

• Little help icons placed on page, popping up some information relevant to adjacent fields etc
• A toggleable "help mode" that adds explanatory text on all fields etc. Think something like an interactive tutorial.
• Tooltips on input fields that expand on the expected data beyond the label text

Shibboleth config setting

Rebuild config settings for the shibboleth login package so that there is no need to modify the config file from development to production before each deployment.

Customizability of the overall site style

Since this system is not technically a DSV system as much as it is a SPIDER system, the general style of the site needs to be customizable to follow SPIDER's look and feel (which may change over time).

This can be a fairly technical feature, one approach would be to allow administrators to upload a custom css file that overrides the built-in styling.

#31 is kind of a prerequisite for this, in that it needs to be realistically possible to override the core styles of the site in a way that isn't totally overwhelming. Things like the colors the site uses should be set once and reused instead of being declared on each item. Similarly with text sizes, logos, button styles etc.

Style support in text boxes

It should be possible to style the text of a project update. Something fairly minimal like https://yabwe.github.io/medium-editor/ would be appropriate.

Project creation should include fields for start and end date

The status of a project should be computed based on today's date and the project's start and end dates. Aggregated activity status should be reflected somehow in the overall project status.

Support for small screens

The system should be fully usable on a smartphone-sized display and up, with responsive design adapting to the available real estate. Especially parts expected to be used by partners need this support, but in the end it should cover the entire site.

Email reminders for activities

There is a need to be able to configure email reminders to be sent when an activity is nearing its end date and is not yet marked as done.

The exact contents of the reminder probably don't need configurability, just a simple email saying "There is less than a week left on [activity], please review your project and update as necessary." or something along those lines.

Whether reminders should be sent and at what date should be configurable per activity.

Set up jenkins jobs

We should get a CI pipeline up.

One job should build and deploy to test whenever a new commit is pushed.
Another job should build and deploy to production on demand. Bonus points for making this job use tags/releases/etc - something that won't just naïvely push the latest commit that is available, but some known good state.

Resultpress-test will be set up this week so that the main instance can go into production.

Logging for reminders and other mail notifications

It's important to keep track of sent out mails e.g. reminders, so they should be included in Logs.

Indicate that there are pending updates

When there are submitted updates that have not yet been approved, this should be indicated (to users that can approve) in the project list and project summary pages.

Upgrade Laravel to version 8

Upgrade laravel framework to the latest version (8).