Initial commit

Author: cj13579

.gitignore

@@ -0,0 +1 @@
+.idea/

README.md

@@ -0,0 +1,160 @@
+# Create SAS® App
+
+##  What is this?
+
+This is a collection of open-source [Progressive Web Application (PWA)](https://en.wikipedia.org/wiki/Progressive_web_application) templates we maintain at [Boemska](https://boemskats.com/), which we fondly refer to as 'CSA apps'. These templates all implement a set of [core features](#core-features) that together offer SAS developers a standard and effortless way to begin developing Apps for their SAS platform. They're powered by [React](https://reactjs.org/) and [H54S](https://github.com/Boemska/h54s), and your choice of either [SAS Viya](https://www.sas.com/en_us/software/viya.html) or [SAS 9.4](https://www.sas.com/en_us/software/sas9.html). 
+
+'Standard and effortless' in this context means:
+
+* **Zero Configuration, Native Security**  
+
+Developing apps with these templates will not any require any elevated privileges, Administrator access to SAS, or handling of any secrets, registration of clients, or deployment of refresh tokens. Instead, communication is handled through native mechanisms built into SAS and used by the other browser-based SAS client apps. Authentication, authorisation and session security between the browser runtime and backend services are all handled without the need for new server components, certificates, runtimes, or changes to the platform security configuration. In other words, if you can log on to SAS, you should have everything you need to get started.
+
+* **Standard Create React App Development Experience**  
+
+These templates are provided with a set of added features, described in detail below. Aside from those features, they are standard, 'unejected' [Create React App](https://github.com/facebook/create-react-app) generated web apps. That means that if you're a developer learning how to build apps in React, the templates will make sense and align completely with any React learning material you're following. Likewise, if you already have experience developing with React, you should feel right at home.
+
+
+## Choice of CSA App Templates 
+
+The repository currently contains three pre-built template applications, based on three popular UI component libraries.
+
+* **[IBM Carbon Design](./carbon-ui)** ([homepage](https://www.carbondesignsystem.com/))  
+_"Carbon is IBM’s open-source design system for products and experiences. With the IBM Design Language as its foundation, the system consists of working code, design tools and resources, human interface guidelines, and a vibrant community of contributors."_  
+* **[Onsen UI](./onsen-ui)** ([homepage](https://onsen.io/))  
+_"Onsen UI is a large set of rich UI components specifically designed for mobile apps. It is packed with ready-to-implement features following native iOS and Android design standards."_
+* **[Bootstrap](./bootstrap)** ([homepage](https://getbootstrap.com/))  
+_"Bootstrap is the world’s most popular framework for building responsive, mobile-first sites."_
+
+The one you pick will depend on your objectives, preferences and skills. However, if you're just starting out or unsure of which one to use, this is our opinion:
+
+- If you're not building a handset-first app, we recommend starting with the **[Carbon Design](./carbon-ui)** template. Its a rich UI framework, works well on both the Desktop and on Tablet devices, and is fairly easy to theme while remaining very good in terms of accessibility. We use it for most of the apps we build.
+
+- If you _are_ building a handset-first app, consider using the **[Onsen UI](./onsen-ui)** template. The components it provides will offer an excellent 'native-like' feel to your users, and should enable you to build an awesome user experience.
+
+- For maximum control over your design, have a look at **[Bootstrap](./bootstrap)**. Many of our larger clients have built their own design systems over time, the majority of them being based on Bootstrap. If you have an in-house digital team you're hoping to work with then this is probably the best choice. 
+
+
+## Getting Started
+
+To get started with one of the CSA apps in this repository you'll need to **either**:
+
+1. Clone this repository and then copy the folder of the app you want to use to a location of your choice; or
+2. Download a copy of the app that you want to use from the Releases tab of this repository.
+
+In the folder you just copied, you'll find a README with instructions on how to get started. For the _very_ quick guide, you'll need to do something like the following:
+
+```js
+yarn install
+yarn run configure
+yarn start
+```
+
+Here is an example of that process looks like with the carbon-ui app template.
+
+## Core Features
+
+The templates in this repository are configured with the following base features. 
+
+**Key**  
+**⣿⣿⣿⣿⣿** - Implemented  
+**⣿⣿⣿⣀⣀** - In progress  
+**⣿⣀⣀⣀⣀** - Planned  
+
+| Feature | [carbon-ui](./carbon-ui) | [onsen-ui](./onsen-ui)  | [bootstrap](bootstrap) |
+| -------| ------------------------ | ----------------------- | ---------------------- |
+| H54S (SAS Authentication + transport) | **⣿⣿⣿⣿⣿** | **⣿⣿⣿⣿⣿** | **⣿⣿⣿⣿⣿** |
+| Saving, loading, sharing of projects* | **⣿⣿⣿⣿⣿** | **⣿⣀⣀⣀⣀** | **⣿⣀⣀⣀⣀** |
+| Direct Deploy to Home Screen | **⣿⣿⣿⣿⣿** | **⣿⣀⣀⣀⣀** | **⣿⣀⣀⣀⣀** |
+| Automatic update of app runtime | **⣿⣿⣿⣿⣿** | **⣿⣿⣿⣿⣿** | **⣿⣿⣿⣿⣿** |
+| Offline mode | **⣿⣿⣿⣿⣿** | **⣿⣿⣿⣿⣿** | **⣿⣿⣿⣿⣿** |
+| Direct deployment of back end code* | **⣿⣿⣿⣀⣀** | **⣀⣀⣀⣀⣀** | **⣿⣀⣀⣀⣀** |
+
+\* indicates SAS Viya-only REST API feature 
+
+
+### Integrated SAS Authentication and Communication via H54S
+
+These templates are designed to integrate with your SAS platform, and that integration is managed by [H54S](https://github.com/boemska/h54s), the HTML5 Data Adapter for SAS. The core H54S library manages your app's interaction with your SAS server: requests and data transport, authentication and session management, and debug log management. 
+
+<p align="center">
+<img src="docs/csa-final-login.svg" width="60%" />
+</p>
+
+All app templates contained within this repository are pre-configured with an H54S adapter service (`_adapterService`) instance. In addition, the UI components that you would typically need to create to power the SASLogon handling functionality, as well as the transport status indicator, debug mode switch, application & debug log modals and Log Out button have already been created and integrated with H54S.
+
+For more information about the core H54S library, it is recommended that you check out the [core adapter repository](https://github.com/Boemska/h54s). Some of this functionality is also documented in more detail in our (very) deprecated [Angular v1 Bootstrap Seed App](https://github.com/Boemska/h54s-angular-seed-app).
+
+### Secure Saving, Loading and Sharing of In-app Projects (Viya only)
+
+As you look through this repository and navigate through the templates, you'll notice that one of the core concepts is a _project_. A 'project' is like a saved snapshot of the state of your App. How much data you save is entirely up to you, and will depend on the size and complexity of your app. Saved data can range from a set of dropdown selections that would be recalled by loading a project, to multiple instances of parameter selections, each retaining the data from the time that model was last run. 
+
+<p align="center">
+<img src="docs/csa-final-projects.svg" width="60%" />
+</p>
+
+This functionality will allow your users to Create, Save and Load projects. It will also allow them to Share projects with colleagues, either by copying and pasting a link, or for camera-enabled devices, showing a QR code to a colleague so they can just point their device's camera at it. If they are connected to the network, and are authorised within the Files service to read your project, it will load on an instance of the app on their device.
+
+The project files generated by your app will be saved to the SAS Viya Files service, to a configurable 'Projects' folder location. When a shared project URL is loaded, this is what happens:
+
+* the app loads on the device
+* if the user isn't logged in, they are asked to authenticate
+* once there is a valid auth session, the project file is requested
+* SAS evaluates permissions on that file, and if your colleague is allowed to read that project, it is loaded in to their instance of the app.
+
+Note: This feature is Viya-only for now, as it depends on the Viya Files and Folders services. At Boemska we have an implementation of this functionality which stores projects and allows them to be shared via SAS v9 Metadata Document (TextStore) objects, where similar security / authorisation benefits apply. We may end up porting that functionality to these templates; if you're interested, please let us know by raising an issue. 
+
+
+### App-store-Free Installation
+
+These templates are Progressive Web Apps (PWAs), which means they are designed to be saved to your users' Home Screns. The first time a user opens an app on their iPad or mobile device, they will be prompted to install the application to their home screen (what this prompt looks like depends on their flavour of mobile OS). If they accept, they'll be able to open your CSA app from the home screen of their device, no different to an app they downloaded from their App Store!
+
+<p align="center">
+<img src="docs/csa-final-deploytohome.svg" width="60%" />
+</p>
+
+The parameters for configuring things like home-screen icons, app names and splash images depend on the target device OS, but are also easily configurable. Each template includes a pre-configured example of this.
+
+
+### Easy App Updates
+
+Ensuring that your users update to the latest version of your app is a well-known challenge - especially if the update process is lengthy or requires them to jump through hoops.
+
+With CSA apps, this isn't the case. Whenever you push a change your application, your users will be notified that there is a new version of the application available - regardless of the device they're on. If they choose to update the application, the context of the application is preserved to storage, and the app is updated in-place. Depending on how much of the app an update changes, they might not even notice that an update happened.
+
+In the background, this process is handled by Google's excellent [workbox](https://developers.google.com/web/tools/workbox) library. 
+
+<p align="center">
+<img src="docs/csa-final-update.svg" width="60%" />
+</p>
+
+I guess saying CSA apps are 'no different to an app downloaded from an App Store' isn't _entirely_ fair... to CSA apps.
+
+
+### Offline Mode
+
+One of the really nice things about mobile devices and mobile applications is their... mobility. Frequently, your users can take them places without WiFi or a data connection. 
+
+All of the CSA templates within this repository are offline-capable, again courtesy of Google's excellent [workbox](https://developers.google.com/web/tools/workbox) library. 
+
+<p align="center">
+<img src="docs/csa-final-offlinemode.svg" width="60%" />
+</p>
+
+How you decide what data you save to local storage and make available to your users in offline mode is mostly up to you. However, the ability to load your app when offline, the indicators that show your users that the app is offline, and the hooks that respond to the navigator.online() event are all there already. Documenting how you can make selected [projects](#secure-saving-loading-and-sharing-of-in-app-projects-viya-only) available in offline mode is something we plan to document and automate. Watch this space. 
+
+
+### Automatic deployment of Back-end services (Viya only)
+
+Unlike the other features outlined here, this one is still mostly experimental. It exists specifically for the initial deployment of apps developed using Boemska [AppFactory](https://boemskats.com/products/af/). However, the functionality can be extended to apps that aren't developed using AF.
+
+AppFactory project files are hierarchical JSON files, where the code for SAS-based services is organised into folders representing the role grouping for those services. These AppFactory project files can optionally be bundled with the application front-end. You would package up your app as normal, as a .zip file containing the app build, for deploying to a web server. It would then be deployed to a web server, either by an administrator deploying to `/var/www/html` or a user deploying to their personal `~/public_html`. 
+
+<p align="center">
+<img src="docs/csa-final-autodeploy.svg" width="60%" />
+</p>
+
+The first time that app is loaded into the browser, it won't have the back-end jobExecution services it needs. When this happens, this auto-deployment routine can iterate through all of the folders and services found in the included AF project json file. If the authenticated SAS user has the necessary permissions, the app can then deploy these code objects to the back-end by communicating directly with the `/jobDefinitions` and `/folders` services within SAS Viya. 
+
+
+

bootstrap/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.env

bootstrap/README.md

@@ -0,0 +1,124 @@
+# h54s <3 Bootstrap
+
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+
+## Getting started
+In order to get the application up and running in no time at all, run the following 3 commands from within this folder:
+
+### Deploy the backend
+1. Register our application's startup service. **On Viya** this is a File of type Job Definition, and can be registered through the SASJobExecution WebApp (`https://[yourViyaServer]/SASJobExecution/`). **On SAS v9** this is a Stored Process and can be registered through SAS Management Console or Enterprise Guide. In both cases you'll be registering the code object to a SAS folder that you have permission to write to. In both Viya and v9, I created mine in a sub-folder of my user's `My Folder` location: `csa-boostrap/common/startupService`:
+
+2. Edit the code for the newly registered code object and populate it with the code from the `startupService.sas` file in the `sas` folder of this application.
+
+3. Configure the output type for your newly registered code object.  
+
+**On Viya**, right click on the job name and select properties. From the properties menu select "Parameters". Add the following parameter and then click save:
+  * Name: `_output_type`
+  * Default value: `html`
+  * Field type: `Character`
+  * Required: `false`
+
+**On SAS v9**, make sure you enable Streaming Output as the output type. If you are using Enterprise Guide to do this, also be sure to check "Global Macro Variables" and uncheck "Include Stored Procedure Macros" under the "Include code for" dropdown.
+
+### Modify adapterService configuration
+Update the `config.js` file found in `./src/adapterService`. We need to update the `sasVersion` for the version of the SAS platform that we are running on and update the `metadataRoot` to the location of where we deployed our `startupService` in the step above. 
+
+
+### `yarn install` 
+Install all the dependencies listed within `package.json` in the local `node_modules` folder.
+
+### `yarn run configure`
+In the `package.json` for this quick-start application we hav defined a scripts object called `configure`, this command will run the specified [configure] script. The `configure` script is a guided process for connecting your local quick-start application to your remote SAS instance.
+
+### `yarn start`
+Runs the app in the development mode.<br />
+Open [https://localhost:3000](https://localhost:3000) to view it in the browser.
+
+The app uses a proxy to communicate with the server so it has to open on a an https connection
+
+The page will reload if you make edits.<br />
+You will also see any lint errors in the console.
+
+
+## Other commands
+
+### `yarn test`
+
+Launches the test runner in the interactive watch mode.<br />
+See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+
+### `yarn build`
+
+Builds the app for production to the `build` folder.<br />
+It correctly bundles React in production mode and optimizes the build for the best performance.
+
+The build is minified and the filenames include the hashes.<br />
+Your app is ready to be deployed!
+
+See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+
+### `yarn watch`
+
+Starts build with watch - used npm-watch with setthins in package.json
+```javascript
+"scripts": {
+	...,
+	"watch": "npm-watch"
+},
+"watch": {
+	"build": "src/"
+}
+```
+
+### `serve -s build`
+Serve prod build locally. To use this first run
+```javascript
+yarn global add serve
+```
+
+### `yarn eject`
+
+**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
+
+If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
+
+Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
+
+You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
+
+### To run development scripts follow
+```text
+1. yarn watch
+2. in separated terminal run serve -s build
+3. in separated terminal cd build and run bapsync script
+```
+
+## Learn More
+
+You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
+
+To learn React, check out the [React documentation](https://reactjs.org/).
+
+### Code Splitting
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/code-splitting
+
+### Analyzing the Bundle Size
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size
+
+### Making a Progressive Web App
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app
+
+### Advanced Configuration
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/advanced-configuration
+
+### Deployment
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/deployment
+
+### `yarn build` fails to minify
+
+This section has moved here: https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify

bootstrap/config-overrides.js

@@ -0,0 +1,17 @@
+const {rewireWorkboxInject, defaultInjectConfig} = require('react-app-rewire-workbox');
+const path = require('path');
+
+module.exports = function override(config, env) {
+  if (env === "production") {
+    console.log("Production build - Adding Workbox for PWAs");
+    // Extend the default injection config with required swSrc
+    const workboxConfig = {
+      ...defaultInjectConfig,
+      swSrc: path.join(__dirname, 'src', 'custom-sw.js'),
+			importWorkboxFrom: "local"
+    };
+    config = rewireWorkboxInject(workboxConfig)(config, env);
+  }
+
+  return config;
+};