search

acoustic-content-samples / wch-site-application

Source code for the Acoustic Content sample site single page application - Oslo.
Apache License 2.0
6 stars 13 forks source link

readme

wch-site-application

Source code for the Acoustic Content (formerly Watson Content Hub) starter site application - Oslo.

Prerequisites

Overview

This github repository contains all the source code files like javascript, css and html but not the Oslo artifacts like pages, content types, categories, and content. Content tenants created after September 18th 2017 will have the Oslo artifacts automatically deployed. For older tenants you need to manually deploy the artifacts by downloading the Oslo built artifacts from the home page of your tenant from the "Update the sample site" widget. Not sure if you have the Oslo artifacts?

You can compare the Build date with the date shown in the "Update the sample site" widget on the Home page to see if your deployed sample is older than the latest sample code. Instructions on how to update Oslo to the latest can be found here: Updating your Oslo sample.

Documentation

  1. Roadmap for developing your own site
  2. Programming Model
  3. Resources

Updates

At the end of August 2019 we have updated the Oslo starter site with the following features:

At the end of July 2019 we have updated the Oslo starter site with the following features:

At the beginning of January 2019 we have updated the Oslo starter site with the following features:

At the beginning of December 2018 we have updated the Oslo starter site with the following features:

At the end of October 2018 we have updated the Oslo starter site with the following features:

At the beginning of September 2018 we have updated the Oslo starter site with the following features:

At the beginning of August 2018 we have updated the Oslo starter site with the following features:

At the beginning of June 2018 we have updated the Oslo starter site with the following features:

At the end of May 2018 we have updated the Oslo starter site with the following features:

At the end of April 2018 we have updated the Oslo starter site with the following features:

At the end of March 2018 we have updated the Oslo starter site with the following features:

At the end of February 2018 we have updated the Oslo starter site with the following features:

At the beginning of February 2018 we have updated the Oslo starter site with the following features:

At the beginning of January 2018 we have updated the Oslo starter site with the following features:

At the beginning of December 2017 we have updated the Oslo starter site with the following features:

Getting set up

From your cli make sure to install project dependencies by running npm install

Changing the tenant

You can set the tenant information, by changing the values in src/app/Constants.ts. This file determines from which tenant site and layout information gets served from.

Inside src/app/Constants.ts, uncomment these three lines and replace the values:

// static readonly DOMAIN_NAME = 'your-domain-name.com';
// static readonly CONTENT_HUB_ID = '0000000-0000-0000-0000-000000000000';
// static readonly SITE_ID = '00000000-0000-0000-0000-000000000000';

Steps to retrieve the delivery URL for a site:

  1. Log in to your Watson Content Hub and navigate to the Websites tab.
  2. Click the arrow button on your site to flip over the card.
  3. Copy the delivery URL on the back of the card.

Development server

Run npm start for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Use the npm run start-dev-tools command to load the developer tools UI. Read more here.

developer tools UI

Build

Run npm run build to build the project. The build artifacts will be stored in the assets/ directory. Use the -prod flag for a production build.

Deployment to Watson Content Hub

Run npm run deploy to deploy the built code to Watson Content Hub. There is also a shortcut for building and deploying in one step via npm run build-deploy. Note that publishing can take up to 20 minutes for all updates to be available. In case you do not want to wait for the server side akamai cache to time out you can flush the cache via: wchtools clear --cache More information can be found here: Clearing the content delivery network cache

Running unit tests and end-to-end tests

See the included detailed documentation on running tests Running unit tests and end-to-end tests .

Install Sample Site Components

The Oslo site provides scripting to ease the process of importing 3rd party components.
We have provided a set of sample component repositories:

Structure of Sample Site Components

Installation steps

See the readme of sample-active-site-components for details: https://github.com/ibm-wch/sample-active-site-components

HTML5 style URLs

The SPA will now use HTML5 style URLs and routing.

Advanced

Code scaffolding

To use code scaffolding you will want the Angular CLI with this project. To install it globally run npm install -g @angular/cli.

Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|module.

Enabling logging

The SPA uses the ng2-logger package for logging. By default logging will be enabled when running locally and disabled when running in production mode on the tenant. The logging level can be changed by setting a cookie in the browser. The available log levels are

Setting the logging level will result in a waterfall effect, for example if setting warn logging will also be enabled for error and data.

To change the logging level you can enter the following into the browsers console developer tools
document.cookie = 'wch.sites.logging.level=warn'

Manage your Oslo starter site template with a manifest

To make it easier to remove the default Oslo site either completely or just the out of the box images, content, pages and assets, we created two sample manifest files, oslo-complete.json and oslo-sample-artifacts.json for the Oslo site. With these two manifest files, you can easily push and delete your Oslo contents listed in the manifest file with wchtools.

To push, pull, and delete content by manifest, please refer to: https://github.com/ibm-wch/wchtools-cli#pushing-pulling-and-deleting-by-manifest

If you want to start with a new site skeleton without all of the Oslo artifacts that are not required you can delete the extra artifacts with the oslo-sample-artifacts manifest. The deletion will not remove referenced items in Oslo that are not part of the manifest. So, if you created content or other items that are using Oslo content types, content, or assets, these will not be removed by the delete command.

Note: Since the sample manifest files only work for the default Oslo starter site template, if you add new content to your site, you have to create your own manifest files. Details: https://github.com/ibm-wch/wchtools-cli#creating-a-new-manifest

Use cases

You would like to clean out all sample images, renditions, content, and pages associated with Oslo, but leave Oslo layouts, content types and categories so that you can use these to build your custom site. This will leave any additional items that you may have created.
You would like to clean out all artifacts associated with Oslo, but leave any items that you have created. Delete all Oslo artifacts in your tenant:
You would like to update the complete Oslo manifest to include additional items that you created. Update oslo-complete.json after adding your customized content in your tenant:
You would like to create your own SPA site with reusable artifacts from Oslo :

Create your own SPA site based on Oslo minimum template

  1. Download the latest Oslo sample site artifacts from "Update the sample site" widget in your WCH homepage
  2. Unzip the package you downloaded and use your command line tool to change directory to this unzipped folder
  3. Configure your tenant information by running wchtools init
  4. Push Oslo minimum template to your tenant by running wchtools push -A -v -f --manifest oslo-minimum
  5. Open the live site of your tenant, you will see a starter site with only minimum reusable artifacts. Follow the instruction in the page to create your own content and page for your SPA site.

Note: If you have older site in your tenant, you have to delete it first before pushing the Oslo minimum template. wchtools delete -A -v --all would be helpful if you want to clean up your tenant.

Add and configure custom site styles

Different styles can be applied to the application, depending on which site is loaded. To configure your site with custom styles, follow these following steps:

  1. Go to the src/oob-spa/styles directory.
  2. In that directory, add a new .scss file, where the file name matches the site ID that you want to customize (e.g. <site-id>.scss).
  3. Add your custom styles to the newly created .scss file.
  4. In the angular.json file at the root directory, update the styles property, adding your new style as an object with these properties and values:
{
  ...
  "projects":{
    "wch-site-application": {
      "architect": {
        "build": {
          ...
          "options": {
            ...
            "styles": [
              "src/styles.css",
              // start new style configuration
              {
                "input": "src/oob-spa/styles/<site-id>.scss",
                "lazy": true,
                "bundleName": "oob-spa/styles/<site-id>"
              }
              // end new style configuration
            ],
            ...
          },
          ...
        },
        ...
      },
      ...
    },
    ...
  },
  ...
}

That's it! Now, any styles that are added to <site-id>.scss will be applied to the SPA, when rendering the site with a matching ID. You can preview your style changes by running npm start to view the preview server. When ready, you can deploy the changes to the tenant by running npm run build-deploy

License

See the included license file License .

Resources

Acoustic Content developer documentation: https://developer.goacoustic.com/acoustic-content/docs

Acoustic Content API reference documentation: https://developer.goacoustic.com/acoustic-content/reference

Acoustic Content Samples Gallery: https://content-samples.goacoustic.com/