Document implementing with vanilla uPortal master

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/

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

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,

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,

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;
         };
 

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

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
+<Connector port="8080" protocol="HTTP/1.1"
+           connectionTimeout="20000"
+           redirectPort="8443" />
+
+```
+
+After:
+
+```xml
+<!-- <Connector port="8080" protocol="HTTP/1.1" -->
+<Connector port="8080" protocol="org.apache.coyote.http11.Http11Nio2Protocol"
+           connectionTimeout="20000"
+           redirectPort="8443" />
+```
+
+#### 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
+<Context sessionCookiePath="/">
+```
+
+#### Configure bigger cache size
+
+Add a `Resources` element to increase Tomcat's cache size to accommodate uPortal's bulk:
+
+```xml
+  <Resources cachingAllowed="true" cacheMaxSize="100000" />
+</Context>
+```
+
+#### 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`.
+
+<http://localhost:8080/uPortal>
+
+Then, navigate to /web.
+
+<http://localhost:8080/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.