skyquake/plugins/composer/src/src/README.md

   1
   2 The application enables editing of CONFD YANG instances.
   3
   4 Catalog Panel - loads the NSD and VNFD and PNFD catalogs from the server and updates the internal indexes used throughout
   5         the UI
   6 Canvas Panel - graphical editor of the relations and networks of NSD and VNFD descriptors
   7 Details Panel - schema driven editor of every property in the YANG models
   8 Forwarding Graphs Tray - editing FG RSP, Classifier and MatchAttribute properties
   9
  10 # Details Panel
  11
  12  - To get an object to show up in the Details Panel it must be defined in the DescriptorModelMeta.json schema file.
  13
  14  - only needs the DescriptorModelMeta.json file to define the JSON to create / edited.
  15
  16  - To make an object appear in the Details Panel you need to add it to the "containersList" in the DescriptorModelFactor.js class.
  17
  18 # Canvas Panel
  19
  20  - is coded specifically to enable graphical editing of certain descriptor model elements and is the least flexible
  21
  22  - To make an object "selectable" it must have a data-uid field.
  23
  24  The canvas panel uses D3 to render the graphical editing experience.
  25
  26 # State Management
  27
  28 There are two layers of state: 1) model state, 2) UI state.
  29
  30 The YANG models are wrapped in Class objects to facilitate contextual operations that may change either state, like
  31 adding and removing property values, accessing the underlying uiState object, etc. These classes are defined in the
  32 `src/libraries/model/` directory.
  33
  34 ## Model State
  35
  36 The UI uses Alt.js implementation of Flux. Alt.js provides for the actions and state of the application. Model state is
  37 managed by the CatalogDataStore. Any change made to the model must notify the CatalogDataStore. Upon notification of a
  38 change the Alt DataStore will setState() with a deep clone of the model causing a UI update.
  39
  40 You will see `CatalogItemsActions.catalogItemDescriptorChanged(catalogItemModel)` everywhere a change is made to the
  41 model. In essence the UI treats the model as immutable. While the object is technically mutable the UI is modifying a copy
  42 of the model and so for changes to 'stick' the UI must notify the CatalogDataStore.
  43
  44 ## UI State
  45
  46 UI state is managed in a couple different ways depending on the specific need of the UI. The three ways are: 1) a field
  47 named 'uiState' added to each YANG model instance when the catalog is loaded from the server; 2) React Component state not
  48 saved in the Alt DataStore; and 3) module variables.
  49
  50 Ideally, all uiState would us the later two methods. The 'uiState' field poses a potential name collision with the YANG
  51 model (not likely, but if it happens could be really bad for the application!).
  52
  53 ## ReactJS and d3
  54
  55 The components built using d3 own the management of the DOM under the SVGSVGElement. ReactJS manages the content DOM element
  56 above the SVG element. This is a clean separation of concerns. Any model or UI state changes are handled by the model
  57 classes and therefore d3 is agnostic and ignorant of managing state. ReactJS is not responsible for the DOM below the
  58 SVG content DIV and so does not care about any of the DOM manipulations that d3 makes.
  59
  60 All of the UI is driven by the model which is always passed down through the props of the parent ReactJS Component. The
  61 d3 components provide a way to pass the model and UI state into them. For an example of this look at the
  62 `CatalogItemCanvasEditor::componentDidMount()` method. You will see the parent content div and the model data are given
  63 to the `DescriptorGraph()` d3 component.
  64
  65 The d3 graphing components are located in the `src/libraries/graph/` directory.
  66
  67
  68
  69