diff --git a/README.md b/README.md index 6e0b16a24..44c7e0f99 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This is an Angular approach to the dashboard view of uPortal. This dashboard wil "uPortal-home" is somewhere in the process of a name change from its old name, "AngularJS-Portal". -See [this project's documentation](http://uw-madison-doit.github.io/angularjs-portal/). +See [this project's documentation][GitHub Pages site]. #### Resources for understanding what you can do with `angularjs-portal`: @@ -32,27 +32,8 @@ This file contains your server side proxy configurations. See the example file f + run `mvn clean package` from the root directory to build the war files. #### Building, Deploying, and Running with [Apereo uPortal](https://github.com/Jasig/uPortal) -+ Download, build, and run uPortal on your server -+ Setup [autodeploy](https://github.com/UW-Madison-DoIT/angularjs-portal/blob/master/README.md#deploying-to-a-running-local-tomcat) -+ cd to angularjs-portal root directory -+ Unix based systems, run : `./build.sh master` -+ Windows based systems, run : -``` -copy angularjs-portal-home/src/main/webapp/js/app-config.js angularjs-portal-home/src/main/webapp/js/app-config.js.bak -copy angularjs-portal-home/src/main/webapp/js/master-app-config.js angularjs-portal-home/src/main/webapp/js/app-config.js -mvn package -cd angularjs-portal-home -mvn tomcat7:deploy #or redeploy depending if this is a consecutive run -``` -+ navigate to localhost:8080/uPortal -+ Login via any user that has access to the Welcome Tab in uPortal. If you want to use admin, you have to comment out the admin restricting part in the [welcome tab layout](https://github.com/Jasig/uPortal/blob/master/uportal-war/src/main/data/quickstart_entities/fragment-layout/welcome-lo.fragment-layout.xml) -+ navigate to localhost:8080/web -Angularjs-portal is a different front end than the one supplied with [Apereo uPortal](https://github.com/Jasig/uPortal). -As of now, portlet rendering still takes place via uPortal's rendering pipeline. -The [theming] (http://uw-madison-doit.github.io/uw-frame/latest/#/md/theming) comes from the [uw-frame dependency](https://github.com/UW-Madison-DoIT/uw-frame). - -University of Wisconsin styles the portal theme to look similar for a seamless transition between this webapp and the portal webapp. +See [documentation site][GitHub Pages site]. ### Modules @@ -97,3 +78,5 @@ Drop angularjs-portal-home/target/web.war in the Tomcat instance that runs uPort [MyUW Overview slide deck]: http://go.wisc.edu/qwg5r1 [Tomcat docs re Maven plugin]: http://tomcat.apache.org/maven-plugin-2.0/tomcat7-maven-plugin/plugin-info.html + +[GitHub Pages site]: http://uw-madison-doit.github.io/angularjs-portal/ diff --git a/angularjs-portal-home/src/main/webapp/js/README.md b/angularjs-portal-home/src/main/webapp/js/README.md new file mode 100644 index 000000000..0d1fbef65 --- /dev/null +++ b/angularjs-portal-home/src/main/webapp/js/README.md @@ -0,0 +1,20 @@ +# What are these files? + +(This is not comprehensive documentation on how to configure AngularJS-portal -- see the documentation site both for this project and [for the `uw-frame` project][uw-frame configuration docs] it overlays upon. Rather, this is directory-local reminder of what these files are.) + +## `override.js` + +Configuration of the uPortal-app-framework aka `uw-frame` for use in this application. `uPortal-home` is itself a uPortal-app-framework application so it needs to configure the framework same as other applications and it additionally configures some home-specific stuff. The out of the box version of `override.js` should work for localhost development. + +## `master-override.js` +This file doesn't itself do anything. It's just an example. It's the configuration that you'd put in `override.js` to configure for use with vanilla uPortal. + +## `web-config.js` + +uPortal-home configuration about being uPortal-home (rather than the `override.js` about being a uPortal-app-framework app.) + +## `login-config.js` + +Configuration specific to `uPortal-home` delegating to uPortal for user login. See [documentation](http://uw-madison-doit.github.io/angularjs-portal/silent-login.html). + +[uw-frame configuration docs]: http://uw-madison-doit.github.io/uw-frame/configuration.html diff --git a/angularjs-portal-home/src/main/webapp/js/master-override.js b/angularjs-portal-home/src/main/webapp/js/master-override.js index ed7710071..d8f650e91 100644 --- a/angularjs-portal-home/src/main/webapp/js/master-override.js +++ b/angularjs-portal-home/src/main/webapp/js/master-override.js @@ -1,8 +1,5 @@ define(['angular'], function(angular) { - /* Keep in sync with docs/markdown/configuration.md*/ - return angular.module('override', []) - // see configuration.md for howto .constant('OVERRIDE', { 'APP_FLAGS': { 'enableToggle': true, @@ -24,13 +21,18 @@ define(['angular'], function(angular) { 'newstuffInfo': '/web/staticFeeds/new-stuff.json', 'context': '/uPortal/', 'base': '/uPortal/api/', - 'layout': 'layout.json', + 'layout': 'api/v4-3/dlm/layout.json', 'layoutTab': 'Welcome', 'marketplace': { 'base': 'marketplace/', 'entry': 'entry/', 'entries': 'entries.json', }, + 'widgetApi': { + 'entry': '/uPortal/api/marketplace/entry/', + 'entrySuffix': '.json', + 'entries': '/uPortal/api/marketplace/entries.json', + }, 'notificationsURL': '/web/staticFeeds/notifications.json', 'groupURL': '/uPortal/api/groups', 'kvURL': null, diff --git a/angularjs-portal-home/src/main/webapp/js/override.js b/angularjs-portal-home/src/main/webapp/js/override.js index b79da1a42..4fd90633a 100644 --- a/angularjs-portal-home/src/main/webapp/js/override.js +++ b/angularjs-portal-home/src/main/webapp/js/override.js @@ -1,8 +1,5 @@ define(['angular'], function(angular) { - /* Keep in sync with docs/markdown/configuration.md*/ - return angular.module('override', []) - // see configuration.md for howto .constant('OVERRIDE', { 'APP_FLAGS': { 'enableToggle': true, diff --git a/angularjs-portal-home/src/main/webapp/my-app/layout/services.js b/angularjs-portal-home/src/main/webapp/my-app/layout/services.js index bed7d341d..f2ed1f806 100644 --- a/angularjs-portal-home/src/main/webapp/my-app/layout/services.js +++ b/angularjs-portal-home/src/main/webapp/my-app/layout/services.js @@ -124,6 +124,7 @@ define(['angular', 'jquery'], function(angular, $) { } else if ($.isArray(data.layout)) { // layoutDoc result.layout = data.layout; } + return result; }; diff --git a/docs/README.md b/docs/README.md index 1e9fe0331..1b2912d31 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,12 @@ This documentation describes [AngularJS-Portal](https://github.com/UW-Madison-Do Many [contributors](contributors.md) make this project possible. +## Demoing and implementing + +You can partially demonstrate `uPortal-home` without a backing server, using provided stub example data. See the root `README.md` for how; start with that simplest possible local demo. + +Of course for a more sophisticated demo or to adopt for real you will need to [configure your `uPortal-home` to work with a `uPortal` instance](with-uportal.md). + ## Features ### Home page diff --git a/docs/with-uportal.md b/docs/with-uportal.md new file mode 100644 index 000000000..719978bf1 --- /dev/null +++ b/docs/with-uportal.md @@ -0,0 +1,163 @@ +# uPortal-home and uPortal + +`uPortal-home` is an alternative user experience layer for use with `uPortal`. `uPortal-home` is entirely static front end HTML/CSS/JavaScript for users to exercise in their web browsers. To be interesting, it needs to connect up with services provided by server-side components, including those in `uPortal`. + +This documentation is about how to use `uPortal-home` with `uPortal`. + +The uPortal project is an ecosystem of open source software products, communities, participants, and adopters. `uPortal-home` is one organism in this wider ecosystem. + +## uPortal? + +uPortal a software product implementing the server-side portions of an enterprise portal, with facilities for user authentication, user attribute gathering, groups and permissions, user layouts, content directory modeling, containing JSR-286 Portlets, and administrative functions over all of this. + +## Getting uPortal + +Clone the uPortal Git repository. This will get you the latest `master` branch code, which is the bleeding edge code that will eventually become a uPortal 5.0.0 release. + +## Basic localhost demonstration + +### Tomcat + +You'll need a Servlet container to run uPortal. Because of uPortal's portlet container, that Servlet container probably needs to be Tomcat. Since you'll have a Tomcat anyway, we'll use that to serve up `uPortal-home` too. + +So download a Tomcat distribution. Version `8.5.15` worked for me. + +You'll have to configure Tomcat a bit to uPortal's needs: + +#### Aside: Maybe fixing a glitch in Tomcat 8.5 + +I found the out of the box Tomcat 8.5.15 unstable, and that changing the connector implementation fixed the glitch. You may not have this problem and not need to do this. + +In `server.xml`, change the `protocol` of the `Connector` to `org.apache.coyote.http11.Http11Nio2Protocol`. + +Before: + +```xml + + +``` + +After: + +```xml + + +``` + +#### Configure shared loader + +uPortal needs to share libraries across webapps for its Portlet container to work. + +In `catalina.properties`: + +``` +shared.loader=${catalina.base}/shared/lib/*.jar +``` + +##### Configure shared session cookies + +In `context.xml`, add the `sessionCookiePath` attribute to the `Context` element, with value `"/"`. + +```xml + +``` + +#### Configure bigger cache size + +Add a `Resources` element to increase Tomcat's cache size to accommodate uPortal's bulk: + +```xml + + +``` + +#### Tell uPortal source where Tomcat is + +Configure uPortal `build.properties` to know where your Tomcat is. + + + + +### The server: uPortal + +You're going to need a couple terminals: + +#### Run the HSQL database for uPortal + +In one terminal, in the root directory of your checked out uPortal codebase, run an HSQL server so that uPortal has a database to depend upon. + +``` +ant hsql +``` + +#### initportal + +WARNING: `initportal` is destructive, to data in the configured database and to deployed web applications in the configured Tomcat. Only `initportal` in contexts where you really mean it. + +In another terminal, in that same root directory of your checked out uPortal codebase, initialize your uPortal. + +```shell +ant initportal +``` + +#### Start Tomcat + +After uPortal downloads dependencies, builds, and deploys to Tomcat, in a third terminal or so start Tomcat. + +Check it out: at `http://localhost:8080/uPortal`; you've got a uPortal. + +### The client: `uPortal-home` + +Now that you've got uPortal running, go ahead and stop Tomcat again. + +Configure for operation against a localhost uPortal: in source `angularjs-portal-home/src/main/webapp/js/`, replace the contents of `override.js` with the contents of `master-override.js`. + +Build `uPortal-home` to a .war file with + +```shell +npm install +``` + +and then + +```shell +mvn clean package +``` + +Drop the resulting `angularjs-portal-home/target/web.war` in the `webapps` directory of Tomcat. + +Start Tomcat again. + +### The basic demo + +First, log into uPortal, say as `student`. + + + +Then, navigate to /web. + + + +Tada! It'll render the `uPortal-home` home page with some widgets on it. + +(Currently the widgets won't work, but you'll at least see your layout. Working on getting the MyUW-local uPortal additions uPortal-home depends upon working in upstream...) + +## Portlet registry as app directory + +TODO. + +## Widgets as portlet-definition metadata + +TODO. + +## uPortal-home and Portlets + +TODO. + +## Redirecting from uPortal to uPortal-home + +TODO.