From 7aeeba38ce86926903d5238879afddb88ab51bef Mon Sep 17 00:00:00 2001 From: David M Sibley Date: Wed, 20 Dec 2017 11:34:55 -0600 Subject: [PATCH] docs: add major version upgrade documentation (#647) * docs: add major version upgrade documentation * docs: general updating of stale docs * docs: clean up md linting errors --- docs/README.md | 4 ++- docs/announcements.md | 8 ------ docs/app-options.md | 2 +- docs/buttons.md | 2 +- docs/directives.md | 36 +++--------------------- docs/latest/README.md | 5 ---- docs/latest/index.html | 25 ----------------- docs/material.md | 2 +- docs/notifications.md | 8 ------ docs/overview.md | 2 +- docs/theming.md | 2 +- docs/upgrading.md | 63 ++++++++++++++++++++++++++++++++++++++++++ docs/versions.md | 10 ------- 13 files changed, 75 insertions(+), 94 deletions(-) delete mode 100644 docs/announcements.md delete mode 100644 docs/latest/README.md delete mode 100644 docs/latest/index.html delete mode 100644 docs/notifications.md create mode 100644 docs/upgrading.md delete mode 100644 docs/versions.md diff --git a/docs/README.md b/docs/README.md index 2ad338964..46b49893d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,8 +43,10 @@ With gratitude to the many [contributors to this project](contributors.md). ## Administration ++ [Major version upgrade guide](upgrading.md) + [Release management](releasing.md) -+ [Frame versions with docs and release notes](versions.md) ++ [Frame versions with docs and release notes][CHANGELOG] [uportal-home]: https://github.com/uPortal-Project/uportal-home [MyUW]: https://it.wisc.edu/services/myuw/ +[CHANGELOG]: https://github.com/uPortal-Project/uportal-app-framework/blob/master/CHANGELOG.md diff --git a/docs/announcements.md b/docs/announcements.md deleted file mode 100644 index 821ed9574..000000000 --- a/docs/announcements.md +++ /dev/null @@ -1,8 +0,0 @@ -# Retired page - -This page has been retired. If you're seeing this message, please [let the developer list know](https://groups.google.com/a/apereo.org/forum/#!forum/uportal-dev) we need to update a link somewhere! - -You're probably looking for one of these pages: - -+ [In-app messaging (user-facing content)](messaging.md) -+ [In-app messaging (technical implementation)](messaging-implementation.md) diff --git a/docs/app-options.md b/docs/app-options.md index 801d3f969..0fffc0e5d 100644 --- a/docs/app-options.md +++ b/docs/app-options.md @@ -1,6 +1,6 @@ # App options -Apps using the `` or `` [directives](directives.md) can specify custom app-specific options to appear in the app header, as pictured below. +Apps using the `` [directive](directives.md) can specify custom app-specific options to appear in the app header, as pictured below. ![./img/app-header-options.png](img/app-header-options.png) diff --git a/docs/buttons.md b/docs/buttons.md index 48e10205b..2bbc8be84 100644 --- a/docs/buttons.md +++ b/docs/buttons.md @@ -2,7 +2,7 @@ Buttons in uportal-app-framework leverage [Angular Material buttons](https://mat Google Material design practices and come with built-in UX enhancements. Use the `` directive to create a material button. #### All buttons should have the following attributes: -+ The text should be sentence-case (e.g. "Reset announcements") ++ The text should be sentence-case (e.g. "Learn more") + It should include an `aria-label` attribute that describes the action for screen readers + It should have either an `ng-click` or `ng-href` attribute for buttons and links, respectively + It should include a class for the desired color palette (i.e. `md-primary`, `md-accent`, `md-warn`, or `md-default`) diff --git a/docs/directives.md b/docs/directives.md index d6db43efa..e50d82704 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -5,8 +5,6 @@ Frame page should be used for all pages in a uportal-app-framework application. It comes with much of the rest of the framework's skeleton built in, including the app-header and main-menu directives. You should use it as the outermost element for each of your application's main views. -**Example page**: see `/portal/main/partials/example-page.html` - ### Template: ```html @@ -24,38 +22,12 @@ each of your application's main views. ### Params -_See `app-header`_ - -### Options - +* **app-title**: The title that will be displayed in the app header +* **app-icon**: The icon to use as a prefix to the app title. You can use Font Awesome (i.e. "fa-envelope") or Material Icons (i.e. "email"). +* **app-show-add-to-home**: If set to true, will include the add-to-home directive and its controller in the app header (used for apps that are part of the portal ecosystem). +* **app-fname**: If provided, it will be used in the add-to-home feature. If not, it'll try to use NAMES.fname constant. * **white-background**: A boolean when set to true with give you a white background. -## App header - -If you don't want to use the frame page directive, you can still utilize the app-header as you would any other directive. It should be included in all pages of your app. - -There is also a directive called `app-header-two-way-bind`. This has all the same features as `app-header` except all the scope attributes are passed in via `=` instead of `@`. This provides 2 way binding for your header. Research angular directives for more details. - -### Template: - -```html - -``` - -### Params: - -All params are prefixed with `app-`. - -* **title**: The title that will be displayed in the app header -* **icon**: The icon to use as a prefix to the app title. You can use Font Awesome (i.e. "fa-envelope") or Material Icons (i.e. "email"). -* **show-add-to-home**: If set to true, will include the add-to-home directive and its controller in the app header (used for apps that are part of the portal ecosystem). -* **fname**: If provided, it will be used in the add-to-home feature. If not, it'll try to use NAMES.fname constant. - ## Main menu Makes the side navigation menu available. If you have [configured](configuration.md) either the `appMenuTemplateURL` or `appMenuItems` option, you need to include this directive on every page where you want navigation. For this reason, using the frame-page directive for all your pages is recommended. diff --git a/docs/latest/README.md b/docs/latest/README.md deleted file mode 100644 index f865b6960..000000000 --- a/docs/latest/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# The latest documentation - -[The latest documentation](http://uportal-project.github.io/uportal-app-framework/) is hosted live on GitHub Pages. - -(This page exists because this was historically more complicated -- if you followed a link to get here that link should be updated to drop the `/latest/` from the end of it.) diff --git a/docs/latest/index.html b/docs/latest/index.html deleted file mode 100644 index 714183cc2..000000000 --- a/docs/latest/index.html +++ /dev/null @@ -1,25 +0,0 @@ - - - -The latest documentation. - -

(This page exists because historically there were multiple versions of the documentation live. Now you simply go to the live documentation site and see the latest.)

diff --git a/docs/material.md b/docs/material.md index 6cd41a40b..17a9a84ea 100644 --- a/docs/material.md +++ b/docs/material.md @@ -14,7 +14,7 @@ This page will serve as a resource for Material documentation, and how MyUW uses + **[Cards](https://material.angularjs.org/latest/demo/card)**: Used for MyUW widgets, Note there are many parts to a card, including title, media, actions, and content. Use the Angular Material documentation to guide you. + **[Toolbar](https://material.angularjs.org/latest/demo/toolbar)**: Used for the MyUW header. + **[Menu](https://material.angularjs.org/latest/demo/menu)**: Used for MyUW's username, options, and mobile menus. -+ **[Dialog](https://material.angularjs.org/latest/demo/dialog)**: Used for feature announcements and app ratings in MyUW. ++ **[Dialog](https://material.angularjs.org/latest/demo/dialog)**: Used sparingly for feature announcements in MyUW. + **[Input](https://material.angularjs.org/latest/demo/input)**: Bootstrap input components are being phased out in favor of Material input directives throughout MyUW. + **[Loading icon](https://material.angularjs.org/latest/demo/progressCircular)**: Use the Material Progress Circular directive for loading screens in MyUW. This can be colored according to the school's material theme. + **[Radio Buttons](https://material.angularjs.org/latest/demo/radioButton)**, **[Selects](https://material.angularjs.org/latest/demo/select)**, **[Checkboxes](https://material.angularjs.org/latest/demo/checkbox)**, and **[Switches](https://material.angularjs.org/latest/demo/switch)**: Material's input components are fantastic and should be used throughout MyUW. diff --git a/docs/notifications.md b/docs/notifications.md deleted file mode 100644 index 05c3cab69..000000000 --- a/docs/notifications.md +++ /dev/null @@ -1,8 +0,0 @@ -# Retired page - -This page has been retired. If you're seeing this message, please [let the MyUW team know](mailto:myuw-infra@office365.wisc.edu) we need to update a link somewhere! - -You're probably looking for one of these pages: - -+ [In-app messaging (user-facing content)](messaging.md) -+ [In-app messaging (technical implementation)](messaging-implementation.md) diff --git a/docs/overview.md b/docs/overview.md index b02f8e49a..820bc8426 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -23,7 +23,7 @@ In addition to the features pictured above, frame provides: + Error pages + Optional settings + [Frame-specific angular directives](directives.md) -+ [Mascot announcements and notifications](announcements.md) ++ [Mascot announcements and notifications](messaging.md) + Optimizations for small screens (including the [mobile menu](img/mobile-menu.png)) In-depth overviews of frame's features can be found under the Features heading on the [documentation home page](README.md). diff --git a/docs/theming.md b/docs/theming.md index d98f7f637..054282351 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -53,7 +53,7 @@ var example = { + `ariaLabelTitle`: The aria label put in place of the theme title + `crestalt`: The crest alt text. This should be the name of your frame app (i.e. "MyUW Portal"). + `group`: Groups this app should be enabled for automatically. Not sure? Ask the dev list: . -+ `mascotImg` (optional): See documentation about the mascot for announcements [here](announcements.md). ++ `mascotImg` (optional): See documentation about the mascot for announcements [here](messaging.md). + `profileUrl` (optional): Specify a URL for a "Profile" app/page, where users can view and/or update their personal information. + `footerLinks`: An array of links which appear in the footer -- typically contains links to the campus help desk and feedback portal. + `materialTheme`: \[object or string] See the *Material Theme* section below. diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 000000000..5901fc5a6 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,63 @@ +# Upgrading +At a glance notes for upgrading apps between major versions. + +# 6.x.x to 7.x.x +- Wrap routed views in a `` directive. + - remove extraneous `` directives. +- Remove `app-options-template` attribute from existing `` directives. Replace with a partial in `overrides.js`: + - from + ```html + + ``` + - to + ```html + + ``` + ```javascript + var example = { + 'APP_OPTIONS': { + 'optionsTemplateURL': 'my-app/app-options/appOptions.html', + }, + }; + ``` + +# 5.x.x to 6.x.x +- Change pom.xml to reflect new dependency version (and name). + - from + ```xml + + edu.wisc.my.apps + uw-frame + war + 5.2.1 + + ``` + - to + ```xml + + org.apereo.uportal + uportal-app-framework + war + 6.0.0 + + ``` + +# 4.x.x to 5.x.x +- Update the notifications page url attribute name in `override.js` (note the pluralization) + - from `NOTIFICATIONS.notificationFullURL` + - to `MESSAGES.notificationsPageURL` +- Update location for getting notifications feed in `override.js` + - from `SERVICE_LOC.notificationsURL` + - to `SERVICE_LOC.messagesURL` +- Remove `NOTIFICATIONS` and `FEATURES` attribute groups from `override.js` +- Add a default theme configuration to override.js + - e.g. set `APP_FLAGS.defaultTheme` to `'uw-madison'` + +# 3.x.x to 4.x.x +- Rename custom directives that include the word `widget` diff --git a/docs/versions.md b/docs/versions.md deleted file mode 100644 index 5aa82f60d..000000000 --- a/docs/versions.md +++ /dev/null @@ -1,10 +0,0 @@ -# Documentation versions - -The latest [documentation is live on the web](http://uportal-project.github.io/uportal-app-framework/). - -To view documentation for a specific version of `uportal-app-framework` - -1. Navigate to the desired [release on GitHub](https://github.com/uPortal-Project/uportal-app-framework/releases) (or check out the desired tag in your local `git` clone). -2. Read the documentation, either by inspecting a local copy of the source code (you can handily download this from the release on GitHub) or by looking at the codebase at that commit (linked from the release on GitHub). - -(Try not to need to look at old versions of the documentation. Upgrade to latest instead.)